Earn 30% commission with our Partner Program. Learn more

How to Install the Stellar Snippet

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.

On this page

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.

Method 1: Direct Installation (Recommended)

Installing the Stellar snippet directly in your website's HTML provides the best performance and user experience. This is our recommended approach.

Step 1: Locate Your HTML <head> Tag

Open your website's HTML template or layout file and find the <head> section. This is typically in:

  • WordPress: Your theme's header.php file or through a plugin that allows custom head code
  • Shopify: theme.liquid file in your theme editor
  • Custom sites: Your main HTML template or layout component
  • React/Next.js: Your _document.js, layout.js, or index.html file

Step 2: Copy Your Stellar Snippet

In your Stellar dashboard, navigate to your project settings and copy your unique Stellar snippet code.

Step 3: Paste the Snippet

Paste your Stellar snippet directly into the <head> section of your HTML. For optimal performance:

  • Place it as high as possible in the <head> - ideally right after the opening <head> tag
  • Place it before other scripts when practical (especially if using anti-flicker)
  • Avoid async/defer attributes - the snippet is designed to load synchronously
<!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>

Step 4: Configure Anti-Flicker

When generating your snippet in the Stellar dashboard, you'll see an Anti-Flicker toggle:

  • ✓ Enable Anti-Flicker if you're installing directly in HTML and running visual experiments - this prevents visitors from briefly seeing original content before experiment changes apply
  • ✗ Disable Anti-Flicker if you're only tracking events without visual changes, or if page speed is absolutely critical

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.

Step 5: Save and Publish

Save your HTML changes and publish them to your live site. The Stellar snippet will now load on every page.

Step 6: Verify Installation

To confirm the snippet is working:

  1. Open your website in a new incognito/private browser window
  2. Open your browser's developer tools (F12 or right-click → Inspect)
  3. Go to the Network tab
  4. Look for a request to stellar.js - if you see it, you're all set!
  5. You can also check the Console tab for any Stellar-related messages or errors

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).

Method 2: Google Tag Manager Installation

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.

Why GTM is Less Ideal

When you install Stellar through Google Tag Manager, the following sequence occurs:

  1. Your page HTML loads
  2. Browser starts rendering page content
  3. Google Tag Manager container loads
  4. GTM evaluates triggers
  5. GTM executes the Stellar snippet
  6. Stellar loads and applies experiment changes

This delay means:

  • Experiments load later: There's always a delay between page render and experiment activation
  • Anti-flicker becomes harmful: By the time the anti-flicker code runs, content is already visible. Hiding it creates a noticeable "double-load" effect that's worse than flicker itself
  • Increased flicker risk: Even without anti-flicker, users are more likely to see original content before variants apply

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 You Must Use GTM

If direct installation isn't possible and you need to use Google Tag Manager:

Step 1: Create a New Tag

In your GTM workspace, click Tags → New.

Step 2: Choose Custom HTML Tag Type

Select Custom HTML as the tag type and paste your Stellar snippet code into the HTML field.

Step 3: Disable Anti-Flicker

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.

Step 4: Configure Trigger

Add a trigger to control when and where the snippet loads:

  • All Pages: Use the built-in "All Pages" trigger to run the snippet site-wide (most common)
  • Specific Pages: Create a custom trigger with page URL conditions if you only want Stellar on certain pages
  • Priority: Consider setting a high firing priority (low number) to load Stellar as early as possible relative to other GTM tags

Step 5: Set Tag Priority

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.

Step 6: Save and Publish

Save your tag, then submit and publish your GTM container changes to activate the Stellar snippet.

Step 7: Test Carefully

After publishing:

  • Test your experiments thoroughly in preview mode before going live with real traffic
  • Watch for visible flicker or page "reloading" effects - this is expected with GTM but try to minimize it by testing below-the-fold elements
  • Monitor page load times to ensure GTM + Stellar aren't significantly impacting performance

GTM Best Practices

If using GTM, minimize the impact with these practices:

  • Focus on below-the-fold tests: Experiment with elements that aren't immediately visible to reduce noticeable flicker
  • Test subtle changes: Small modifications are less noticeable than dramatic visual changes
  • Monitor user feedback: Watch for complaints about page loading or flickering
  • Consider hybrid approach: Use GTM for tracking tags but install Stellar directly in HTML

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.

Special Installation Scenarios

Single Page Applications (SPAs)

For React, Vue, Angular, or other SPA frameworks, install the Stellar snippet in your main HTML template or layout component:

  • React/Next.js: Add to _document.js or app/layout.js
  • Vue/Nuxt: Add to app.html or layouts/default.vue
  • Angular: Add to index.html

Note: For SPAs, Stellar automatically handles route changes and re-evaluates experiments on navigation. No additional configuration needed.

WordPress

For WordPress sites, you have several options:

  1. Theme editor: Edit header.php directly in Appearance → Theme Editor
  2. Plugins: Use plugins like "Insert Headers and Footers" or "Code Snippets" to add the snippet without editing theme files
  3. Child theme: If using a child theme, add the snippet to your child theme's header.php

Important 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.net
  • Any inline script containing your Stellar API key

Without these exclusions, your experiments may not work properly, and you may experience worse flickering than without optimization.

Shopify

For Shopify stores:

  1. Go to Online Store → Themes
  2. Click Actions → Edit code
  3. Open theme.liquid
  4. Paste the Stellar snippet inside the <head> section
  5. Save your changes

Multiple Domains / Cross-Domain Tracking

If 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.

Troubleshooting

Snippet Not Loading

If the snippet isn't loading on your site:

  • Check cache: Clear your browser cache and CDN cache (if applicable)
  • Verify placement: Ensure the snippet is inside the <head> tag, not in the <body>
  • Check for errors: Open browser dev tools and look for JavaScript errors
  • Validate HTML: Make sure your HTML is valid and the snippet isn't inside a comment
  • Content Security Policy: If you have a CSP, whitelist https://api.gostellar.app,https://.gostellar.app,https://d3niuqph2rteir.cloudfront.net

Experiments Not Running

If the snippet loads but experiments don't run:

  • Check experiment status: Ensure the experiment is published and active
  • Verify targeting: Confirm the URL targeting rules match your test page
  • Check traffic allocation: Make sure you're allocating traffic to variants (not 100% control)
  • Use incognito mode: Test in a private/incognito window to avoid caching issues

Visible Flicker Despite Anti-Flicker

If you're seeing flicker even with anti-flicker enabled:

  • Check installation method: Are you using GTM? If yes, disable anti-flicker
  • Move snippet higher: Place the snippet as close to the opening <head> tag as possible
  • Remove async/defer: The snippet must load synchronously for anti-flicker to work
  • Check page load time: Very slow pages may exceed the anti-flicker timeout

Frequently Asked Questions

Do I need to install the snippet on every page?

No - 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.

Will the snippet slow down my website?

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.

Can I use both direct installation and GTM?

No - never install the snippet twice. Choose one method and stick with it. Installing both will cause duplicate tracking and potentially interfere with experiments.

How do I update my snippet?

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.

What about GDPR / cookie consent?

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.

Next Steps

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!