Integrate Databuddy with Google Tag Manager for centralized tag management while maintaining privacy-first analytics. Perfect for teams managing multiple tracking tools.

TL;DR: In GTM, create a Custom HTML tag with an inline loader that appends https://cdn.databuddy.cc/databuddy.js and sets data-client-id. Enable optional flags such as data-track-attributes or data-track-errors. Page views and sessions are automatic. Trigger on All Pages and publish.

Why Use GTM with Databuddy?

Centralized Management: Manage Databuddy alongside other marketing tools
Team Collaboration: Non-developers can deploy tracking updates
Version Control: Built-in versioning and rollback capabilities
Testing: Preview and debug mode before publishing
Conditional Loading: Load Databuddy based on specific conditions

Basic Setup

Step 1: Create Databuddy Tag

In GTM, click Add a new tag
Choose Custom HTML as the tag type
Add the Databuddy script:

Important: GTM sanitizes HTML and removes non-standard attributes like data-client-id. Always use createElement() and setAttribute() as shown below:

<script>
  (function () {
    var el = document.createElement("script");
    el.src = "https://cdn.databuddy.cc/databuddy.js";
    el.async = true;
    el.crossOrigin = "anonymous";
    el.setAttribute("data-client-id", "{{Databuddy Client ID}}");
    el.setAttribute("data-track-attributes", "true");
    el.setAttribute("data-track-errors", "true");
    document.head.appendChild(el);
  })();
</script>

Name your tag "Databuddy - Analytics Script"

Step 2: Create Variables

Create a Constant variable for your Client ID:

Go to Variables > User-Defined Variables
Click New > Constant
Name: "Databuddy Client ID"
Value: Your actual Client ID from Databuddy dashboard

Step 3: Set Trigger

In your Databuddy tag, click Triggering
Choose All Pages trigger
Save the tag

Step 4: Publish

Click Submit to create a version
Add version name and description
Click Publish

Advanced Configuration

Environment-Based Loading

Load different Databuddy configurations based on environment:

<script>
  (function() {
    var isProduction = '{{Page Hostname}}' === 'yourdomain.com';
    var clientId = isProduction ? '{{Databuddy Prod Client ID}}' : '{{Databuddy Dev Client ID}}';

    var el = document.createElement("script");
    el.src = "https://cdn.databuddy.cc/databuddy.js";
    el.async = true;
    el.crossOrigin = "anonymous";
    el.setAttribute("data-client-id", clientId);
    el.setAttribute("data-track-attributes", "true");
    el.setAttribute("data-track-errors", "true");
    document.head.appendChild(el);
  })();
</script>

Conditional Loading

Load Databuddy only for specific conditions:

<script>
  (function() {
    // Only load for non-internal traffic
    if ('{{Internal Traffic}}' === 'false') {
      var el = document.createElement("script");
      el.src = "https://cdn.databuddy.cc/databuddy.js";
      el.async = true;
      el.crossOrigin = "anonymous";
      el.setAttribute("data-client-id", "{{Databuddy Client ID}}");
      el.setAttribute("data-track-attributes", "true");
      el.setAttribute("data-track-errors", "true");
      document.head.appendChild(el);
    }
  })();
</script>

Event Tracking Setup

Custom Event Tags

Create tags for specific events:

E-commerce Purchase Tag:

Create Data Layer Variables for the values you need (e.g. Transaction ID, Purchase Revenue, Currency, Items Count), then fire this tag on your purchase event trigger:

<script>
  if (window.databuddy) {
    databuddy.track('purchase', {
      transaction_id: '{{Transaction ID}}',
      value: {{Purchase Revenue}},
      currency: '{{Currency}}',
      item_count: {{Items Count}}
    });
  }
</script>

Form Submission Tag:

<script>
  if (window.databuddy) {
    databuddy.track('form_submit', {
      form_id: '{{Form ID}}',
      form_name: '{{Form Name}}',
      form_location: '{{Page Path}}'
    });
  }
</script>

Data Layer Integration

Send GTM data layer events to Databuddy:

<script>
  if (window.databuddy) {
    databuddy.track('{{Event}}', {
      category: '{{Event Category}}',
      action: '{{Event Action}}',
      label: '{{Event Label}}',
      value: {{Event Value}},
      custom_parameter: '{{Custom Parameter}}'
    });
  }
</script>

Triggers Configuration

The analytics script records pageviews automatically, including SPA navigation. Use the All Pages trigger only to load the script; do not add a second pageview tag.

Scroll Tracking

Databuddy's built-in tracking already covers scroll depth, so you do not need a separate GTM scroll depth tag.

Click Tracking

Track specific button clicks:

Trigger Type: Click - All Elements
Conditions: Click Classes contains "track-button"
Tag: Custom HTML with click tracking

<script>
  if (window.databuddy) {
    databuddy.track('button_click', {
      button_text: '{{Click Text}}',
      button_classes: '{{Click Classes}}',
      page_path: '{{Page Path}}'
    });
  }
</script>

E-commerce Integration

Enhanced E-commerce Setup

Track the complete customer journey. Create Data Layer Variables for the product values your site pushes to the data layer, and fire each tag on the matching data layer event trigger.

Product View Tag:

<script>
  if (window.databuddy) {
    databuddy.track('product_view', {
      product_id: '{{Product ID}}',
      product_name: '{{Product Name}}',
      product_category: '{{Product Category}}',
      product_price: {{Product Price}},
      currency: '{{Currency}}'
    });
  }
</script>

Add to Cart Tag:

<script>
  if (window.databuddy) {
    databuddy.track('add_to_cart', {
      product_id: '{{Product ID}}',
      product_name: '{{Product Name}}',
      quantity: {{Quantity}},
      value: {{Item Revenue}},
      currency: '{{Currency}}'
    });
  }
</script>

Begin Checkout Tag:

<script>
  if (window.databuddy) {
    databuddy.track('begin_checkout', {
      value: {{Cart Value}},
      currency: '{{Currency}}',
      item_count: {{Items Count}}
    });
  }
</script>

Respect user privacy choices:

<script>
  (function() {
    // Check consent status
    var hasConsent = '{{Cookie Consent Status}}' === 'granted';

    if (hasConsent) {
      var el = document.createElement("script");
      el.src = "https://cdn.databuddy.cc/databuddy.js";
      el.async = true;
      el.crossOrigin = "anonymous";
      el.setAttribute("data-client-id", "{{Databuddy Client ID}}");
      el.setAttribute("data-track-attributes", "true");
      el.setAttribute("data-track-errors", "true");
      document.head.appendChild(el);
    }
  })();
</script>

Integrate with Google Consent Mode:

<script>
  gtag("consent", "default", {
    analytics_storage: "denied",
    ad_storage: "denied",
  });

  // When user grants consent
  gtag("consent", "update", {
    analytics_storage: "granted",
  });

  // Initialize Databuddy after consent
  if (window.databuddy) {
    databuddy.track("consent_granted", {
      consent_type: "analytics",
      timestamp: new Date().toISOString(),
    });
  }
</script>

Debugging and Testing

Debug Mode Setup

Enable debug mode for testing:

<script>
  var isDebugMode = '{{Debug Mode}}' === 'true';

  if (window.databuddy && isDebugMode) {
    console.log('Databuddy Debug Mode Enabled');
    databuddy.track('debug_event', {
      page: '{{Page Path}}',
      timestamp: new Date().toISOString()
    });
  }
</script>

Preview Mode Testing

Click Preview in GTM
Visit your website in the debug session
Verify Databuddy tags are firing correctly
Check browser console for any errors
Confirm events in Databuddy dashboard

Variable Testing

Create test variables for debugging:

Debug Info Variable:

function() {
  return {
    page_path: '{{Page Path}}',
    page_title: '{{Page Title}}',
    user_agent: navigator.userAgent,
    timestamp: new Date().toISOString()
  };
}

Best Practices

Performance Optimization

Async Loading: Always load Databuddy asynchronously
Conditional Loading: Only load when necessary
Error Handling: Wrap in try-catch blocks

<script>
  (function () {
    try {
      var el = document.createElement("script");
      el.src = "https://cdn.databuddy.cc/databuddy.js";
      el.async = true;
      el.crossOrigin = "anonymous";
      el.setAttribute("data-client-id", "{{Databuddy Client ID}}");
      el.onerror = function () {
        console.warn("Databuddy script failed to load");
      };
      document.head.appendChild(el);
    } catch (e) {
      console.error("Error initializing Databuddy:", e);
    }
  })();
</script>

Tag Organization

Naming Convention: Use clear, descriptive names
Folders: Organize tags by vendor or purpose
Notes: Add descriptions explaining each tag's purpose
Triggers: Name triggers clearly (e.g., "Databuddy - All Pages")

Version Management

Descriptive Names: Use meaningful version names
Notes: Document changes in each version
Testing: Always test in preview before publishing
Rollback Plan: Know how to revert if issues arise

Migration from Google Analytics

Replacing GA4 with Databuddy

Pause GA4 tags (don't delete immediately)
Create Databuddy tags with equivalent functionality
Test thoroughly in preview mode
Gradual rollout using percentage-based triggers
Monitor data for consistency

Data Mapping

Map GA4 events to Databuddy equivalents:

GA4 Event	Databuddy Event	Notes
page_view	screen_view	Automatic
purchase	purchase	Enhanced with privacy features
add_to_cart	add_to_cart	Same structure
scroll	scroll_depth	Covered by built-in tracking

Troubleshooting

Common Issues

Tag Not Firing:

Check trigger conditions
Verify variable values in preview mode
Ensure GTM code is properly installed

Events Not Tracking:

Verify Databuddy script loads successfully
Check browser console for errors
Confirm Client ID is correct

Performance Issues:

Ensure scripts load asynchronously
Check for blocking JavaScript errors
Monitor Core Web Vitals impact

Debug Checklist

✅ GTM container code installed correctly
✅ Databuddy tag fires on correct triggers
✅ Client ID variable contains correct value
✅ No JavaScript errors in console
✅ Events appear in Databuddy dashboard
✅ Privacy settings respected

Shopify

Complete e-commerce tracking with purchase analytics.

Next.js

App Router and Pages Router setup for Next.js apps.

WordPress

Plugin or manual setup for WordPress sites.

Need help with your GTM integration? Contact us at support@databuddy.cc.

Google Tag Manager