Skip to main content

Google Tag Manager

This guide covers installing the DAP SDK through Google Tag Manager (GTM), including conditional loading and SPA considerations.

Prerequisites​

  • A Google Tag Manager account
  • A GTM container published on your target site

Step-by-Step Setup​

1. Create a Custom HTML Tag​

  1. Open your GTM container at tagmanager.google.com.
  2. Navigate to Tags > New.
  3. Name the tag (e.g., "Break Ground SDK").
  4. Click Tag Configuration and select Custom HTML.
  5. Paste the SDK snippet:
<!-- DAP SDK Snippet -->
<script>
  (function (w, d, s, o, f, js, fjs) {
    w["DAPObject"] = f;
    w[f] =
      w[f] ||
      function () {
        (w[f].q = w[f].q || []).push(arguments);
      };
    w[f].l = 1 * new Date();
    js = d.createElement(s);
    fjs = d.getElementsByTagName(s)[0];
    js.id = f;
    js.src = o;
    js.async = 1;
    js.crossOrigin = "anonymous";
    fjs.parentNode.insertBefore(js, fjs);
  })(window, document, "script", "https://cdn.example.com/sdk.js", "DAP");
  DAP("init", { tenantKey: "YOUR_TENANT_KEY" });
</script>

2. Set the Trigger​

  1. Click Triggering below the tag configuration.
  2. Select All Pages (the built-in Page View trigger).
  3. Save the tag.

3. Publish​

  1. Click Submit in the top-right corner.
  2. Add a version name (e.g., "Add Break Ground SDK") and publish.

Using GTM Variables​

To avoid hardcoding the tenant key, create a GTM variable:

  1. Go to Variables > User-Defined Variables > New.
  2. Choose Constant as the variable type.
  3. Name it "BreakGround Tenant Key" and set the value to your tenant key.
  4. Save the variable.
  5. Update the snippet in your tag to reference the variable:
<script>
  (function (w, d, s, o, f, js, fjs) {
    w["DAPObject"] = f;
    w[f] =
      w[f] ||
      function () {
        (w[f].q = w[f].q || []).push(arguments);
      };
    w[f].l = 1 * new Date();
    js = d.createElement(s);
    fjs = d.getElementsByTagName(s)[0];
    js.id = f;
    js.src = o;
    js.async = 1;
    js.crossOrigin = "anonymous";
    fjs.parentNode.insertBefore(js, fjs);
  })(window, document, "script", "https://cdn.example.com/sdk.js", "DAP");
  DAP("init", { tenantKey: "{{BreakGround Tenant Key}}" });
</script>
tip

Using a GTM variable makes it easy to update the tenant key across all tags in one place, and separates configuration from code.

Conditional Loading​

You can control where the SDK loads by configuring trigger conditions:

Load on specific pages only:

  1. Create a new trigger: Trigger > New > Page View.
  2. Set it to fire on Some Page Views.
  3. Add a condition: Page Path contains /app (or your application path).
  4. Assign this trigger to the BreakGround tag instead of All Pages.

Load based on Data Layer variables:

If your application pushes values to the Data Layer, you can use them as trigger conditions:

// In your application code
dataLayer.push({ userLoggedIn: true });

Then create a Data Layer Variable in GTM and use it as a trigger condition.

SPA Route Tracking​

The SDK monitors pushState and popstate events independently. It handles client-side navigation without any GTM configuration.

warning

Do not create additional GTM tags that fire the SDK snippet on History Change triggers. The SDK is designed to load once and track route changes on its own. Firing the tag multiple times will cause errors.

Gotchas​

warning
  • Do not double-load: If the SDK snippet is already in your page HTML, do not also load it through GTM. This will cause duplicate initialization. Choose one method.
  • Tag Sequencing: GTM's Tag Sequencing feature (firing one tag before another) does not guarantee the SDK has fully loaded. If you need to call DAP() from another GTM tag, use the SDK's ready event instead: 
    <script>
      DAP("on", "ready", function () {
        // Safe to call DAP methods here
        DAP("identify", { userId: "user-42" });
      });
    </script>
  • Consent mode: If you use a consent management platform, configure the BreakGround tag to fire only after the user has granted consent. Set the trigger to fire after the consent event rather than on All Pages.

Verification​

In GTM Preview Mode​

  1. Click Preview in GTM to open Tag Assistant.
  2. Navigate to your site. The Tag Assistant panel will show which tags fired.
  3. Confirm the "Break Ground SDK" tag appears under Tags Fired.

On the Live Site​

  1. After publishing, open your site in a browser.
  2. Open the developer console (F12 or Cmd+Option+I).
  3. Type window.DAP and press Enter. You should see the DAP function object.
  4. Enable debug mode for detailed logs:
DAP("init", { tenantKey: "YOUR_TENANT_KEY", debug: true });
  1. Check the Console tab for messages prefixed with [DAP] confirming successful initialization.

Next Steps​