The Stellar snippet allows you to start creating and running experiments on your website. While you can install it directly or through Google Tag Manager, we strongly recommend direct installation for optimal performance and the best user experience.
Quick Summary: Direct installation in your HTML <head> is faster, more reliable, and enables anti-flicker to work correctly. Google Tag Manager installation is convenient but comes with performance tradeoffs and makes anti-flicker ineffective.
Building a React or Next.js app? The snippet covers visual experiments on any site. To A/B test components, flows and features inside your own code, use the Stellar SDK for React & Next.js. The two work side by side on the same site.
Installing the Stellar snippet directly in your website's HTML provides the best performance and user experience. This is our recommended approach.
Open your website's HTML template or layout file and find the <head> section. This is typically in:
header.php file or a header plugin. WordPress guidetheme.liquid in the theme editor. Shopify guide_document.js, layout.js, or index.html fileIn your Stellar dashboard, navigate to your domain settings and copy your unique Stellar snippet code.
Paste your Stellar snippet directly into the <head> section of your HTML. For optimal performance:
<head> - ideally right after the opening <head> tag<!DOCTYPE html>
<html>
<head>
<!-- Place Stellar snippet here, as high as possible -->
<script>!function(){var e="body {opacity: 0 !important;}",t=document.createElement("style");t.type="text/css",t.id="page-hide-style",t.styleSheet?t.styleSheet.cssText=e:t.appendChild(document.createTextNode(e)),document.head.appendChild(t),window.rmo=function(){var e=document.getElementById("page-hide-style");e&&(e.parentNode.removeChild(e),document.body.style.opacity="")},setTimeout(window.rmo,3e3)}();</script>
<link rel="preconnect" href="https://d3niuqph2rteir.cloudfront.net" />
<link rel="dns-prefetch" href="https://d3niuqph2rteir.cloudfront.net" />
<script async src="https://d3niuqph2rteir.cloudfront.net/client_js/stellar.js?apiKey=your_api_key"></script>
<!-- Other head content -->
<meta charset="UTF-8">
<title>Your Website</title>
<!-- ... -->
</head>
<body>
<!-- Your page content -->
</body>
</html>When generating your snippet in the Stellar dashboard, you'll see an Anti-Flicker toggle:
How Anti-Flicker Works: When enabled, the snippet temporarily hides your page content (typically for 100-300ms) until experiments are loaded and applied. This prevents the "flash" of original content that visitors might otherwise see. Learn more in our Anti-Flicker documentation.
Save your HTML changes and publish them to your live site. The Stellar snippet will now load on every page.
To confirm the snippet is working:
stellar.js - if you see it, you're all set!Important: If you don't see the snippet immediately, try clearing your browser cache or doing a hard refresh (Ctrl+Shift+R or Cmd+Shift+R).
Heads up: Google Tag Manager loads scripts asynchronously, which can cause flicker (the original page may appear briefly before a variant). When possible, paste the Stellar snippet directly in your site’s <head>. See the Anti-Flicker guide.
While Google Tag Manager offers convenience for managing multiple scripts, it comes with significant tradeoffs for A/B testing tools like Stellar:
Not Recommended: Installing through GTM introduces latency and makes the anti-flicker option counterproductive. We only recommend this method if direct installation is absolutely not possible for your setup.
When you install Stellar through Google Tag Manager, the following sequence occurs:
This delay means:
The Core Issue: Stellar (and any A/B testing tool) needs to run before the page renders to prevent flicker. GTM, by design, runs after the page has already started rendering, making it impossible to prevent flicker effectively.
If direct installation isn't possible and you need to use Google Tag Manager:
In your GTM workspace, click Tags → New.
Select Custom HTML as the tag type and paste your Stellar snippet code into the HTML field.
Critical: When generating your Stellar snippet, make sure the Anti-Flicker option is TURNED OFF. With GTM installation, anti-flicker will cause visible page blinking/reloading and worsen the user experience.
Add a trigger to control when and where the snippet loads:
In the tag's Advanced Settings, set a low priority number (e.g., 1 or 10) to ensure Stellar loads before other tags when possible.
Save your tag, then submit and publish your GTM container changes to activate the Stellar snippet.
After publishing:
If using GTM, minimize the impact with these practices:
Our Recommendation: Unless you have a specific technical constraint, always choose direct installation. The performance benefits and proper anti-flicker functionality are worth the small effort of adding code to your HTML.
Each platform has a short install page with the exact menu path. Use that if you are not editing HTML by hand.
For React, Vue, Angular, or other SPA frameworks, install the Stellar snippet in your main HTML template or layout component:
_document.js or app/layout.jsapp.html or layouts/default.vueindex.htmlNote: For SPAs, Stellar automatically handles route changes and re-evaluates experiments on navigation. No additional configuration needed.
For WordPress sites, you have several options. The short version is on the WordPress install guide.
header.php directly in Appearance → Theme Editorheader.phpImportant for WordPress Users: Optimization plugins like WP Rocket, NitroPack, Autoptimize, and similar tools can break the Stellar snippet by minifying, combining, or deferring it. This will prevent experiments from running correctly and may cause flicker issues.
Solution: Exclude the Stellar snippet from optimization. Most optimization plugins provide settings where you can exclude specific scripts from minification/combination. Look for options like "JavaScript Optimization Exclusions" or "Exclude from JS minify" and add:
stellar.js or d3niuqph2rteir.cloudfront.netWithout these exclusions, your experiments may not work properly, and you may experience worse flickering than without optimization.
Squarespace has no plugin. Paste the snippet into the site header with Code Injection. Full steps are on the Squarespace install guide.
Plan: Code Injection needs a Core, Plus, or Advanced plan, or an older Business or Commerce plan. Basic and Personal plans cannot add scripts to the header. Do not use a Code block. That only covers one page and loads too late.
For Shopify stores. Step by step: Shopify install guide.
theme.liquid<head> sectionIf you need to track users across multiple domains, install the same Stellar snippet on all domains and configure cross-domain tracking. Learn more in our Cross-Domain Tracking documentation.
By default Stellar assigns variants at random. Sometimes the variant is decided before the visitor reaches your site: an ad promises a specific offer, and the landing page must show exactly that offer. For this, a variant can be addressed from the URL.
The flow: ad promise → utm_content → variant → WhatsApp. Each ad creative carries its own utm_content, the matching variant is shown and stored for that visitor, and the WhatsApp button on the page carries the variant name so your sales team knows what the visitor saw.
Open the variant in the experiment page (Edit variant) and fill in URL parameter value, for example promo-a for the control and promo-b for variant B. Values are matched case-insensitively and must be unique within the experiment. Variants without a value keep the normal random assignment.
The experiment reads utm_content by default, so ad platforms work without any change: Meta, Google and TikTok all let you set utm_content per creative. If you prefer another parameter, change Assignment URL parameter in the experiment settings (for example variant).
Ad A (promises the standard offer): https://yoursite.com/landing?utm_source=meta&utm_campaign=spring&utm_content=promo-a Ad B (promises the 20% offer): https://yoursite.com/landing?utm_source=meta&utm_campaign=spring&utm_content=promo-b
A visitor arriving from Ad B is assigned variant B, the assignment is saved in their browser, and every later page view keeps variant B even without the parameter. Sessions and conversions are reported exactly as for a random assignment, so the experiment results stay correct. If the value matches no variant, the usual assignment logic runs unchanged.
For QA you can also force any experiment with ?stellar_variant=<variant id or name>, for example ?stellar_variant=Variant%20B. Unlike the preview parameter of the SDK, this is a real, stored assignment.
Note: a URL-param assignment overrides the traffic allocation roll (an ad that promised variant B always gets variant B), but target rules and mutually exclusive experiments still apply. The parameter only needs to be present on the landing page.
Once a visitor has a variant (new, stored, or from a URL parameter), the snippet announces it once per experiment per page view, so Google Tag Manager, GA4 and your own code can react.
window.dataLayer.push({
event: 'stellar_variant_assigned',
stellar_experiment_id: 123,
stellar_experiment_name: 'Landing offer',
stellar_variant_id: 456,
stellar_variant_name: 'Variant B'
});In GTM, create a Custom Event trigger named stellar_variant_assigned and Data Layer Variables for the stellar_* keys. When gtag is on the page the snippet also sends a GA4 event with the same name and parameters.
// React when a variant is assigned
window.addEventListener('stellar:variant_assigned', function (e) {
console.log(e.detail);
// { experiment_id, experiment_name, variant_id, variant_name }
});
// Or read the current assignments at any time
window.stellar.getAssignments(); // [{ experiment_id, ..., variant_name }]
window.stellar.assignments[123]; // keyed by experiment idTo let your sales team know which offer the visitor saw, the snippet can append stellar_variant=<variant name> to links. Declare which links before the snippet loads; any <a href> containing one of the substrings gets the parameter, including links rendered later by widgets.
<script>
window.stellarConfig = {
appendVariantToLinks: ['wa.me', 'api.whatsapp.com']
};
</script>
<script async src="https://d3niuqph2rteir.cloudfront.net/client_js/stellar.js?apiKey=your_api_key"></script>
<!-- Before: https://wa.me/5491112345678?text=Hola -->
<!-- After: https://wa.me/5491112345678?text=Hola&stellar_variant=Variant+B -->If several experiments are assigned on the same page, the parameter carries all their variant names separated by commas.
Putting it all together: the ad promises the 20% offer and sends utm_content=promo-b, Stellar shows and stores variant B, the dataLayer event tells GTM what was shown, and the WhatsApp link carries stellar_variant=Variant B so the conversation can start with the right offer.
If the snippet isn't loading on your site:
<head> tag, not in the <body>https://api.gostellar.app,https://.gostellar.app,https://d3niuqph2rteir.cloudfront.netIf the snippet loads but experiments don't run:
If you're seeing flicker even with anti-flicker enabled:
<head> tag as possibleNo - just add it once to your site's global HTML template (usually in the <head>). It will then automatically load on all pages. You control which pages run experiments through Stellar's targeting rules.
The Stellar snippet is optimized for minimal performance impact. When installed directly (not through GTM), it typically adds less than 50ms to page load time. The anti-flicker option adds 100-300ms of visual delay but doesn't slow down actual page loading.
No - never install the snippet twice. Choose one method and stick with it. Installing both will cause duplicate tracking and potentially interfere with experiments.
In most cases, you don't need to update your snippet - experiments are configured server-side. However, if we release a major update requiring snippet changes, we'll notify you and provide migration instructions.
Stellar stores minimal, anonymous session data necessary for A/B testing. If you have strict cookie consent requirements, you may need to delay snippet loading until consent is granted. Contact support for specific guidance on your setup.
Once your snippet is installed and verified:
Need Help? If you run into issues installing the snippet, contact our support team at hello@gostellar.app. We're happy to help!