Skip to content
Last updated: 2026-04-06
Reference

Installation Guide

Install Dxtra Tag Manager on your website to manage tracking scripts, analytics, and marketing tags.

Prerequisites

  • A Dxtra account with Tag Manager access
  • An application created in the Tag Manager dashboard
  • Access to your website's HTML or CMS

Standard Installation

Add the Tag Manager script to the <head> section of every page:

HTML
<script src="https://tagmanager-edge.dxtra.ai/tm.js" async></script>

For analytics-only (sub-5KB, no tag management features):

HTML
<script src="https://tagmanager-edge.dxtra.ai/analytics.js" async></script>

SPA Support

For single-page applications, add query parameters to enable SPA tracking:

HTML
<!-- History API navigation (React Router, Vue Router, etc.) -->
<script src="https://tagmanager-edge.dxtra.ai/tm.js?opts=spa" async></script>

<!-- Hash-based navigation -->
<script src="https://tagmanager-edge.dxtra.ai/tm.js?opts=spa,hash" async></script>

The spa option listens for History API changes and re-evaluates rules on navigation. The hash option additionally listens for hash changes.

Platform-Specific Installation

WordPress

Use a plugin like "Insert Headers and Footers" or add directly to your theme:

  1. Go to Appearance > Theme Editor
  2. Select header.php
  3. Add the script tag after the opening <head> tag
  4. Save

For child theme installation:

PHP
// In your child theme's functions.php
function dxtra_tag_manager() {
    ?>
    <script src="https://tagmanager-edge.dxtra.ai/tm.js" async></script>
    <?php
}
add_action('wp_head', 'dxtra_tag_manager', 1);

Shopify

  1. Go to Online Store > Themes
  2. Click Actions > Edit code
  3. Open theme.liquid in the Layout section
  4. Add the script tag after the opening <head> tag
  5. Save

Squarespace

Plan Requirement

Code injection requires a Business or Commerce plan.

  1. Go to Settings > Advanced > Code Injection
  2. Paste the script tag in the Header section
  3. Save

Wix

Plan Requirement

Custom code requires a paid subscription plan.

  1. Go to Settings > Custom Code > Advanced
  2. Click + Add Custom Code
  3. Paste the script tag
  4. Set placement to All Pages and location to Head
  5. Apply

MediaWiki

Using the HeadScript extension:

PHP
// In LocalSettings.php
require_once "$IP/extensions/HeadScript/HeadScript.php";

$wgHeadScriptCode = <<<'START_END_MARKER'
<script src="https://tagmanager-edge.dxtra.ai/tm.js" async></script>
START_END_MARKER;

Placement Tags

To display content at specific locations on a page, add placement tag elements:

HTML
<div data-dxtra="true" data-code="YOUR_TAG_CODE"></div>

Replace YOUR_TAG_CODE with the code from your placement tag configuration in the dashboard.

Custom Domain Setup

To serve the Tag Manager script from your own domain:

  1. Create a CNAME DNS record pointing your subdomain to tagmanager-edge.dxtra.ai
  2. Configure the custom domain in your application's environment settings
  3. SSL certificates are provisioned automatically via Let's Encrypt

After setup, use your custom domain in the script tag:

HTML
<script src="https://tm.yourdomain.com/tm.js" async></script>

Verification

Debug Mode

Add #dxtra-debug to any page URL to open the debug overlay:

Text Only
https://yoursite.com/page#dxtra-debug

This requires logging in with your Dxtra account. The overlay shows:

  • Tag loading status
  • Rule evaluation results
  • Events fired
  • Data container values
  • Console output

Browser DevTools

Check the Network tab for successful loading of:

  • tm.js (or analytics.js) -- Tag Manager script
  • Requests to tagmanager-edge.dxtra.ai or tagmanager-api.dxtra.ai

Troubleshooting

Script Not Loading

Issue Solution
404 error Verify your application exists and the environment is deployed
Blocked by ad blocker Use a custom domain to avoid ad blocker lists
CSP error Add tagmanager-edge.dxtra.ai and tagmanager-api.dxtra.ai to your Content Security Policy
Mixed content Ensure you use https:// in the script URL

Tags Not Firing

Issue Solution
No rules configured Create at least one rule with events and actions
Environment not deployed Finalize and deploy a revision to the target environment
Consent not granted Check CMP Check event conditions match your consent setup
Wrong environment Verify the script URL matches the correct environment

Performance

  • Load the script with async to avoid blocking page rendering
  • Use dns-prefetch and preconnect for faster loading:
HTML
<link rel="dns-prefetch" href="//tagmanager-edge.dxtra.ai">
<link rel="preconnect" href="https://tagmanager-edge.dxtra.ai">