Snippet not loading

Quick check

Open your site, open DevTools (F12) → Console tab, and type:

window.zenstep;

Returns an object → snippet is loaded. You can stop here.
Returns undefined → snippet hasn't loaded. Continue below.

Common causes and fixes

1. Snippet tag is missing

Check that the script tag is present in your page's HTML. Open DevTools → Elements tab and search for getzenstep. If you don't find it, the snippet hasn't been added yet.

Follow the installation guide to add the snippet to your site.

2. Wrong snippet key

The data-zenstep attribute must match your organization's snippet key exactly. Find your key in Dashboard → Install. Copy it and paste it into the script tag — don't type it by hand.

<script
  async
  data-zenstep="YOUR_EXACT_KEY_HERE"
  src="https://cdn.getzenstep.com/snippet/latest/index.iife.js"
></script>

3. Script tag added to the wrong place

The script tag must be in a location that loads on every page. Common mistakes:

Added to a specific page component instead of the root layout
Added inside a conditional block that doesn't always render
Added in a Next.js page component instead of app/layout.tsx

For Next.js, use next/script in your root layout:

// app/layout.tsx
import Script from "next/script";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Script
          src="https://cdn.getzenstep.com/snippet/latest/index.iife.js"
          data-zenstep={process.env.NEXT_PUBLIC_ZENSTEP_KEY}
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

4. Content Security Policy (CSP) blocking the script

If your site has a Content Security Policy, the Zenstep CDN must be in your script-src and connect-src directives.

Add to your CSP:

script-src: https://cdn.getzenstep.com
connect-src: https://app.getzenstep.com

Check the browser console for CSP violation messages — they appear as errors starting with "Refused to load script".

5. Ad blocker or browser extension

Some ad blockers and privacy extensions block third-party scripts. Test in an incognito window with all extensions disabled to rule this out.

6. Script loaded but `window.zenstep` not set yet

The snippet loads asynchronously. If you're calling window.zenstep immediately on page load (e.g., in a module that runs before the snippet), it may not be available yet.

The snippet fires a zenstep:ready event when it's initialized:

document.addEventListener("zenstep:ready", () => {
  window.zenstep.identify("user-123", { plan: "grow" });
});

Or use the queue pattern — calls made before initialization are queued and executed once the snippet is ready:

window.zenstep = window.zenstep || { queue: [] };
window.zenstep.identify =
  window.zenstep.identify ||
  function (...args) {
    window.zenstep.queue.push(["identify", args]);
  };

Verifying installation

Once fixed, confirm the snippet is working:

Open the Install page in the dashboard
Load any page on your site
The status indicator should turn green: "Snippet detected"

If it stays gray after 10 seconds of the page being open, the snippet is still not loading correctly.