Google Tag Manager

Install the widget using Google Tag Manager

Overview

This guide will show you how to install our JavaScript widget using Google Tag Manager (GTM). This method is ideal if you already use GTM for managing tracking codes and scripts on your website.

Prerequisites

Before starting, make sure you have:

A Google Tag Manager account
GTM container installed on your website
Admin or Publish access to your GTM container

If you don't have GTM set up yet, visit tagmanager.google.com to create an account.

Installation Steps

Step 1: Access Google Tag Manager

Go to tagmanager.google.com
Log in with your Google account
Select the container for your website

Step 2: Create a New Tag

Click Tags in the left sidebar
Click the New button
Click in the Tag Configuration box

Step 3: Choose Tag Type

Click Tag Configuration area
Select Custom HTML from the list of tag types

In the HTML text box, paste your widget script:

<script src="https://your-domain.com/widget.js"></script>
<script>
  YourWidget.init({
    apiKey: 'YOUR_API_KEY'
  });
</script>

Replace YOUR_API_KEY with your actual API key from your dashboard.

Step 5: Configure Triggering

Click in the Triggering section below
Click All Pages trigger (recommended for site-wide installation)
Or create a custom trigger for specific pages (see advanced section below)

Step 6: Name Your Tag

Click on Untitled Tag at the top
Enter a descriptive name (e.g., "My Widget - All Pages")
This helps you identify the tag later

Step 7: Save the Tag

Click Save in the top right corner
Your tag is now created but not yet live

Step 8: Preview Your Changes

Click Preview button in the top right
A preview mode will start
Enter your website URL in the popup
Click Connect
Your website will open with GTM debug panel
Verify that your tag is firing on the pages you want

Step 9: Publish Your Changes

If the preview looks good, go back to GTM
Click Submit in the top right corner
Add a Version Name (e.g., "Added Widget Script")
Optionally add a Version Description
Click Publish
Your widget is now live on your website!

Installing on Specific Pages Only

Using Page Path Trigger

To add the widget only on specific pages:

When creating your tag, click Triggering
Click the + icon in the top right to create a new trigger
Click Trigger Configuration
Select Page View
Choose Some Page Views
Set conditions, for example:
- Page Path | contains | /product/
- Page Path | equals | /contact
- Page Path | matches RegEx | /blog/.+
Click Save
Give your trigger a name
Use this trigger for your widget tag

Common Page Targeting Examples

Homepage Only:

Page Path | equals | /

Product Pages:

Page URL | contains | /product/

Checkout Page:

Page Path | equals | /checkout

All Pages Except Homepage:

Page Path | does not equal | /

Advanced Trigger Options

DOM Ready Trigger

To fire the widget after the DOM is ready:

Create a new trigger
Select DOM Ready instead of Page View
Choose All Pages or configure specific pages
Use this trigger for your widget tag

This ensures all page elements load before initializing the widget.

Window Loaded Trigger

To fire after the entire page loads:

Create a new trigger
Select Window Loaded
Configure page conditions as needed

Custom Event Trigger

Fire the widget based on custom events:

Create a trigger
Select Custom Event
Enter your event name
Use this for programmatic control

Tag Settings & Options

Support document.write

Leave this unchecked (not needed for our widget)

Advanced Settings

Tag firing options:

Once per page (default - recommended)
Once per event
Unlimited

Tag Sequencing:

Fire tags before/after this tag if needed
Useful for dependencies

Troubleshooting

Check tag status:
- Use Preview mode to verify tag is firing
- Look for green "Tags Fired" indicator
- Your widget tag should appear in the list
Verify trigger:
- Make sure your trigger matches the pages you're testing
- Check trigger conditions in Preview mode
- Look at "Tags Not Fired" if widget isn't showing
Check for errors:
- Open browser console (F12 or right-click → Inspect)
- Look for JavaScript errors
- Share errors with our support team
Verify GTM container:
- Make sure GTM container code is installed on your website
- Check page source for GTM script
- Confirm you published the changes (not just saved)
Clear cache:
- GTM may be cached
- Use Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)
- Try incognito/private browsing

Tag Firing Multiple Times

Check Tag Firing Options
Select "Once per page" in Advanced Settings
Remove duplicate tags if you created multiple

Use Tag Sequencing to control load order
Fire widget after other critical scripts
Check console for JavaScript conflicts

Preview Mode Not Working

Check if browser extensions are blocking GTM
Try a different browser
Make sure you're connected to the same GTM container

Best Practices

Use descriptive names for tags and triggers
Test in Preview mode before publishing
Add version descriptions when publishing
Use folders to organize multiple tags
Document your setup in tag notes
Use consistent naming (e.g., "Widget - Homepage", "Widget - Products")

GTM Container Setup

If you need to install GTM on your website first:

Standard Installation

Add this code to every page of your website, immediately after the opening <head> tag:

<!-- Google Tag Manager -->
<script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
})(window,document,'script','dataLayer','GTM-XXXXXX');</script>
<!-- End Google Tag Manager -->

And this code immediately after the opening <body> tag:

<!-- Google Tag Manager (noscript) -->
<noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-XXXXXX"
height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
<!-- End Google Tag Manager (noscript) -->

Replace GTM-XXXXXX with your actual GTM container ID.

Platform-Specific GTM Installation

WordPress

Use a plugin like "Google Tag Manager for WordPress" or add code to theme files

Shopify

Add GTM code to theme.liquid file or use Shopify's Google & YouTube app

Wix

Use Wix's built-in Google Tag Manager integration in Settings → Tracking & Analytics

Squarespace

Add GTM code to Settings → Advanced → Code Injection

Webflow

Add GTM code to Project Settings → Custom Code

If you need different widget settings on different pages:

Create Multiple Tags

Create one tag for homepage with specific settings
Create another tag for product pages with different settings
Use different triggers for each tag

Example:

Tag 1: Homepage Widget

<script src="https://your-domain.com/widget.js"></script>
<script>
  YourWidget.init({
    apiKey: 'YOUR_API_KEY',
    theme: 'light'
  });
</script>

Trigger: Page Path equals /

Tag 2: Product Widget

<script src="https://your-domain.com/widget.js"></script>
<script>
  YourWidget.init({
    apiKey: 'YOUR_API_KEY',
    theme: 'dark',
    showProducts: true
  });
</script>

Trigger: Page URL contains /product/

Using GTM Variables

Pass dynamic data to your widget using GTM variables:

<script src="https://your-domain.com/widget.js"></script>
<script>
  YourWidget.init({
    apiKey: 'YOUR_API_KEY',
    pageUrl: '{{Page URL}}',
    pageTitle: '{{Page Title}}',
    referrer: '{{Referrer}}'
  });
</script>

GTM will automatically replace these variables with actual values.

Debugging Tools

GTM Preview Mode

Shows which tags fired and didn't fire
Displays variable values
Shows trigger conditions
Best tool for troubleshooting

Browser Console

Check for JavaScript errors
Verify widget is loading
Test widget functionality

GTM Debug Panel

Shows real-time tag firing
Displays data layer events
Helps identify issues

Important Notes

⚠️ Publishing Required:

Changes don't take effect until you publish
Preview mode is for testing only
Always publish after confirming changes work

⚠️ Container Versions:

GTM saves every version
You can roll back if something breaks
Use version descriptions for easy identification

⚠️ Permissions:

You need appropriate permissions to publish
Contact your GTM admin if you can't publish
Test access levels before making changes

Advantages of Using GTM

✅ Centralized Management - All scripts in one place ✅ No Code Changes - Update without touching website code ✅ Version Control - Track and rollback changes ✅ Preview Mode - Test before going live ✅ Multiple Users - Team collaboration ✅ Advanced Targeting - Fire scripts conditionally

Need Help?

If you encounter any issues:

Check our FAQ at [your-support-url]
Contact support at [your-support-email]
Mention you're using Google Tag Manager
Include GTM container ID if possible
Share Preview mode screenshots

For GTM-specific help:

Google Tag Manager Help Center
GTM Community Forum
Tag Manager documentation

To remove the widget via GTM:

Option 1: Pause the Tag

Go to Tags in GTM
Find your widget tag
Click to edit
Click Pause in the top right
Click Submit and publish

Option 2: Delete the Tag

Go to Tags
Find your widget tag
Click the checkbox next to it
Click Delete at the top
Confirm deletion
Click Submit and publish

Quick Reference Checklist

[ ] Create new Custom HTML tag
[ ] Paste widget script with API key
[ ] Configure trigger (All Pages or custom)
[ ] Name your tag
[ ] Test in Preview mode
[ ] Publish changes
[ ] Verify on live site

Remember: Always preview before publishing!