Google Tag Manager Integration

Set up CADENCE A/B testing through Google Tag Manager. This guide covers the recommended install method, anti-flicker handling, and verification.

When to use GTM vs. direct script

Be honest with yourself about this one.

GTM adds 200-500ms of loading delay. The SDK can't start fetching experiment config until GTM fires, which happens after the page has already started rendering. For tests on content people see immediately (hero sections, navigation, headlines above the fold), that delay causes a visible flash of the original content before your variant kicks in.

Use the direct script tag (Installation Guide) if:

  • You're testing anything above the fold (headers, hero sections, CTAs at the top)
  • You're running visual editor experiments
  • Flicker-free loading matters to you

GTM works well for:

  • Below-the-fold experiments
  • Conversion and event tracking
  • Tests where a brief flash is acceptable
  • Teams where only the growth PM has GTM access and can't edit site code

If you're unsure, start with GTM. You can always switch to the direct script later without changing your experiments.

Quick install (recommended)

Two steps. Takes about 3 minutes.

Step 1: Create the tag

  1. Open your GTM container
  2. Go to Tags → New
  3. Click Tag Configuration → Custom HTML
  4. Paste this code:
html
<script>
  window.CADENCE_CONFIG = {
    projectId: 'YOUR_PROJECT_ID',
    apiUrl: 'https://cdn.softpath.co'
  };
  (function() {
    var s = document.createElement('script');
    s.src = 'https://cdn.softpath.co/sdk/v1/cadence.min.js';
    s.async = true;
    document.head.appendChild(s);
  })();
</script>
  1. Replace YOUR_PROJECT_ID with your actual Project ID (find it in Project Settings in your CADENCE dashboard — looks like proj_Ax8mK2pQr4nB)

Step 2: Set the trigger

  1. Click Triggering
  2. Select All Pages (the built-in Page View trigger)
  3. Name the tag something like "CADENCE SDK"
  4. Click Save
  5. Click Submit to publish the container

That's it. CADENCE is now loading on every page of your site.

Why Custom HTML instead of the Community Template?

The Custom HTML method is simpler and gives you a working setup in 2 minutes. We also provide a Community Tag Template with a form-based UI if you prefer that — but the result is identical.

Anti-flicker setup

If you're running experiments on content that's visible when the page loads, you'll want to prevent the "flash" where users briefly see the original content before the variant appears.

When you need this: Above-the-fold tests installed via GTM. If your experiments only affect content below the fold, skip this.

How to add it

Paste this snippet directly in your site's <head> tag, before the GTM snippet:

html
<script>
(function(d,t){d.documentElement.style.opacity='0';
var r=function(){d.documentElement.style.opacity=''};
if(window.Cadence){r()}
else{var i=setInterval(function(){if(window.Cadence){clearInterval(i);r()}},50);
setTimeout(function(){clearInterval(i);r()},t||300)}})(document,300);
</script>

This hides the page for up to 300ms while the SDK loads. If the SDK loads faster, the page appears sooner. If it takes longer than 300ms (network issues, slow connection), the page shows anyway so users aren't stuck staring at a blank screen.

To change the timeout, replace both 300 values at the end with your preferred millisecond value. We recommend keeping it under 500ms.

This requires editing your site's HTML

The anti-flicker snippet must be added directly to your HTML <head>, not through GTM. GTM fires too late to prevent the flash — that's the whole point of this snippet. If you can't edit your site's <head>, the direct script installation method from the Installation Guide is a better fit.

Passing a known User ID

By default, CADENCE generates an anonymous user ID and stores it in localStorage. This works for most cases.

If your users are logged in and you want consistent variant assignment across devices, pass their ID through the GTM Data Layer.

Step 1: Push the user ID to the Data Layer

In your site's code (or another GTM tag that fires first), push the user ID:

html
<script>
  window.dataLayer = window.dataLayer || [];
  window.dataLayer.push({ cadenceUserId: 'user_12345' });
</script>

Step 2: Create a Data Layer variable in GTM

  1. Go to Variables → New → Data Layer Variable
  2. Set the Variable Name to cadenceUserId
  3. Save it as "Cadence User ID"

Step 3: Update the tag to use it

Modify the CADENCE tag's Custom HTML to include the userId:

html
<script>
  window.CADENCE_CONFIG = {
    projectId: 'YOUR_PROJECT_ID',
    apiUrl: 'https://cdn.softpath.co',
    userId: {{Cadence User ID}}
  };
  (function() {
    var s = document.createElement('script');
    s.src = 'https://cdn.softpath.co/sdk/v1/cadence.min.js';
    s.async = true;
    document.head.appendChild(s);
  })();
</script>

The {{Cadence User ID}} syntax is GTM's variable interpolation. It will be replaced with the value from your Data Layer when the tag fires.

Verification

After publishing your GTM container, open your site and confirm CADENCE is running.

Check the SDK loaded

  1. Open your site in a browser
  2. Open DevTools (right-click → Inspect → Console tab)
  3. Type window.Cadence and press Enter
  4. You should see an object with methods like init, getVariant, track

If you see undefined, the SDK hasn't loaded. Check that your GTM container is published and the tag trigger is set to All Pages.

Check variant assignment

If you have an active experiment, test it:

javascript
// In the console:
await Cadence.ready();
Cadence.getVariant('Your Experiment Name');
// Should return: "Control", "Variant A", etc.

Check with GTM Preview mode

GTM's Preview mode lets you see which tags fired. Look for your "CADENCE SDK" tag in the list — it should show as "Fired" on the Page View event.

GTM Preview and variant assignment

GTM Preview mode injects its own scripts and iframe into the page. In rare cases this can interfere with variant assignment during QA. If you're seeing unexpected behavior in Preview mode, test in a normal browser tab instead. Use ?cadence_variant=Variant+A in the URL to force a specific variant for QA.

Limitations

A few things to keep in mind with the GTM installation method:

  • Loading delay. GTM adds 200-500ms before the SDK can start. For above-the-fold experiments, use the anti-flicker snippet or switch to direct installation.
  • Anti-flicker requires site access. The anti-flicker snippet goes in your HTML <head>, not in GTM. If you can only use GTM, expect some flicker on above-the-fold tests.
  • GTM Preview mode quirks. Preview mode occasionally interferes with variant assignment. If QA results look wrong in Preview mode, verify in a regular tab using URL overrides (?cadence_variant=Variant+Name).
  • Tag firing order. If other GTM tags depend on CADENCE (e.g., sending variant data to analytics), use a Tag Sequencing rule to make sure the CADENCE tag fires first.