Google Tag Manager Integration¶

This guide covers everything you need to connect Google Tag Manager to Adwize: account linking, template installation, configuration options, and how data flows from your site to the Adwize platform.

For a quick-start walkthrough, see the Connect GTM guide.

Prerequisites¶

• A Google account with access to the GTM container you want to monitor.
• An Adwize account (accept your beta invite first).
• Your API Key from the Adwize dashboard (Settings > API Keys).

Step 1: Connect Your Google Account¶

1. Log in to Adwize and go to Settings > Data Sources.
2. Click Google Tag Manager.
3. Click Connect with Google — you'll be redirected to Google's OAuth consent screen.
4. Grant Adwize read-only access to your GTM accounts and containers.

Step 2: Select a Container¶

After authorization, Adwize lists all your GTM accounts and containers. Click the container you want to monitor. Adwize will fetch and store a snapshot of its configuration (tags, triggers, variables, and version history).

Step 3: Install the Monitoring Tag¶

The Adwize monitoring tag is a custom GTM template that captures events and sends them to the Adwize API. You can install it using either method below.

Option A: Download and import¶

1. In the Adwize Data Sources page, click Download .tpl, then in GTM go to Templates > Tag Templates > New > click the three-dot menu (⋮) > Import > select the file > Save.
2. Go to Tags > New > choose Adwize - Data collection monitoring. Paste your API Key (copy it from the sidebar) and add the All Pages trigger.
3. Click Preview to verify the tag fires, then Submit > Publish.

Option B: Template Gallery¶

1. In GTM, go to Templates > Search Gallery > search for "Adwize" > Add to workspace.
2. Create a tag with the template, paste your API Key, and add the All Pages trigger.
3. Click Preview to verify, then Submit > Publish.

Step 4: Verify Integration¶

Adwize automatically verifies your integration. On the Data Sources page, the Verify Integration section checks three things:

1. Template imported — Adwize detects whether the custom template exists in your GTM container (via the config snapshot).
2. Tag created and published — Adwize checks if an Adwize tag is present in your live and/or draft configuration.
3. Events flowing — Adwize checks for recent events (last 24 hours) with source: gtm from your container.

Click Check Status to refresh, or wait for the automatic check on page load. When all three items are green, you'll see "Integration complete — events are being monitored."

If events haven't appeared yet, make sure you've published the container and visited a page where GTM is installed.

You can also verify manually by going to the Events page and looking for events with source: gtm.

Template Fields¶

Advanced Settings¶

These are under a collapsible "Advanced Settings" section in the tag configuration:

Trigger Modes¶

All Events (recommended) — Captures every GTM event (page_view, click, purchase, custom events, etc.). Best for comprehensive monitoring.

E-commerce Events Only — Only captures standard GA4 e-commerce events: purchase, add_to_cart, remove_from_cart, begin_checkout, add_payment_info, add_shipping_info, view_item, view_item_list, select_item, view_cart, add_to_wishlist, refund.

Custom Event List — Only captures the events you specify in a comma-separated list. Use this for targeted monitoring of specific conversion events.

How It Works¶

The Adwize tag reads event data from the dataLayer when GTM fires an event:

Page load / user action
  → GTM fires an event (e.g. page_view, purchase)
    → Adwize tag reads event name + data from the dataLayer
      → Tag builds a JSON payload with event data + container metadata
        → sendPixel sends a GET request to the Adwize collect endpoint
          → Adwize API ingests, monitors, and alerts on data quality

Payload structure¶

Each event sends a JSON payload containing:

• source: "gtm"
• source_id: Your GTM container ID (e.g., GTM-XXXXX)
• events[].type: The event name (e.g., page_view)
• events[].timestamp: Millisecond timestamp when the event occurred
• events[].data: Event-specific data (e-commerce fields, dataLayer snapshot if enabled)
• events[].metadata: Container version, environment, and page URL

Collection endpoint¶

The tag sends data via sendPixel (a GET request) to:

https://api.getadwize.com/api/v1/events/collect?k=YOUR_API_KEY&d=URL_ENCODED_JSON

The endpoint returns a 1x1 transparent GIF. This approach is lightweight, works across all browsers, and doesn't block page rendering.

Template Testing¶

The template includes 8 built-in unit tests. To run them:

1. In GTM, go to Templates > click the Adwize template to edit.
2. Click the Tests tab.
3. Click Run Tests.

The tests validate:

• All events mode captures and sends correctly
• E-commerce mode filters out non-ecommerce events (e.g., page_view)
• E-commerce mode captures purchase events
• Custom mode filters events not in the list
• Custom mode captures listed events
• The pixel URL is constructed with the API key
• GTM lifecycle events are captured in all mode
• Null event names are filtered out

All 8 tests should pass. If any fail after making changes, review the test output in the console for details.

Managing the Connection¶

Refresh Configuration¶

If you update your GTM container (add/remove tags), click Re-sync in Settings > Data Sources to re-fetch the latest container snapshot. Adwize will also re-check whether the Adwize template and tag are still present.

View Configuration¶

The Data Sources page shows a summary of your container's live and draft configuration: tag count, trigger count, variable count, and whether there are unpublished changes. It also shows whether the Adwize template is installed and the Adwize tag is active.

Allowed Domains¶

The Data Sources sidebar shows your current domain restrictions. There are two collection mechanisms with different domain behavior:

• Pixel endpoint (GET /events/collect, used by the GTM template): Accepts events from any domain. This is by design — the GTM template fires from your visitors' browsers on whatever domain GTM is installed.
• POST endpoint (POST /events, used by SDKs and direct API calls): Enforces allowed domain restrictions if any are configured under Settings > API Keys.

If no allowed domains are set, both endpoints accept requests from any origin.

Disconnect¶

To remove the GTM connection, click Disconnect in Settings > Data Sources. This removes the stored OAuth tokens and container configuration from Adwize. You should also remove the Adwize monitoring tag from your GTM container.

Troubleshooting¶

Events not appearing¶

1. Container is published: Unpublished changes won't send events. Make sure you clicked Submit > Publish after adding the Adwize tag.
2. API key is correct: Verify the tag is configured with the correct API key from Settings > API Keys.
3. Tag is firing: Use GTM Preview mode (Tag Assistant) to verify the Adwize tag appears in the "Tags Fired" list.
4. Check the console: Enable Debug logging in the tag's Advanced Settings, then open your browser's developer console. Look for [Adwize] log entries.
5. Use the built-in check: Click Check Status in the Verify Integration section of the Data Sources page. It will tell you exactly which step is missing.

403 Forbidden when using POST /events¶

If you're sending events via the POST /events endpoint (not via GTM) and getting 403 errors, check that your request's origin domain is in the allowed list under Settings > API Keys. The GTM pixel endpoint is not affected by domain restrictions.

OAuth error during connection¶

1. Disconnect and reconnect: Go to Settings > Data Sources, click Disconnect, then try connecting again.
2. Check GTM access: Ensure your Google account has at least Viewer permissions on the GTM container.
3. Clear browser cache: Try an incognito window if cached tokens cause issues.

GTM Preview shows errors¶

• If you see charCodeAt is not a function — you are using an outdated version of the template. Re-download and re-import the latest .tpl file from the Adwize dashboard.
• If Tag Assistant shows "no debuggable Google tags" — this refers to Google's own tags (GA4, Ads), not custom templates. Your Adwize tag can still fire correctly.

Stale configuration¶

If you've made changes in GTM but Adwize doesn't reflect them, click Re-sync in Settings > Data Sources to fetch the latest container snapshot.