Google Tag Manager Template
The Google Tag Manager (GTM) custom tag template deploys the Zeotap Browser SDK through GTM instead of a hand-placed <script> snippet. Marketers import the template once, add tags in the GTM UI, and wire them to triggers — no page-side JavaScript required.
It’s one of three ways to run the browser SDK: the snippet (embed directly in your page), Adobe Launch, or Google Tag Manager (this page). All three send the same Segment-compatible events to the same ingest API.
Install
The template is distributed as a .tpl file imported directly into your container — no gallery listing or marketplace approval is required (a Community Template Gallery listing is planned).
- Download the template: zeotap-cdp-template.tpl
- In GTM, open your container → Templates → Tag Templates → New.
- Open the editor’s ⋮ menu → Import, choose the downloaded
zeotap-cdp-template.tpl, and Save. - The template appears in your tag catalog as Zeotap Composable CDP.
One template, every SDK call
When you add a tag, the Tag Type selector chooses what the tag does. A container typically has one Initialize SDK tag plus one tag per interaction:
| Tag Type | Purpose | Inputs |
|---|---|---|
| Initialize SDK | Loads the SDK and initializes it with your write key. Fire once per page. | Write key, consent mechanism, options |
| Track Event | Records a named event. | Event name, properties |
| Page View | Records a page view. | Category, name, properties |
| Screen View | Records a screen view. | Category, name, properties |
| Identify | Associates a user ID and traits. | User ID, traits |
| Group | Associates the user with a group/account. | Group ID, traits |
| Alias | Links two user identifiers. | New ID, previous ID |
| Set User Identities | Sets PII identities — raw email/phone/login ID are hashed in the browser before any network call. | Identity key/value pairs, pre-hashed toggle |
| Unset User Identities | Removes stored identities. | Keys (empty = all) |
| Set Consent | Sets the user’s consent state. | Category booleans, TCF string, or US Privacy string |
| Reset | Clears identity and queued state (fire on logout). | — |
| Refresh Personalization | Reads the visitor’s Site again now. Only does something when personalization is enabled on Initialize SDK — see Personalization. | Reason (optional) |
Every tag type works before and after the SDK bundle finishes loading — calls made early are queued and replayed in order once the SDK is ready, exactly like the snippet. Tag firing order is preserved.
Worked example
- Tag: Initialize — Tag Type Initialize SDK, Write Key from Events → Event Sources, trigger Initialization — All Pages.
- Tag: Track add-to-cart — Tag Type Track Event, name
Product Added, properties mapped from GTM variables ({{Product ID}},{{Product Price}}), trigger: your add-to-cart event. - Tag: Identify on login — Tag Type Identify (user ID + traits) and a second tag Set User Identities (email/phone), trigger: your login event.
Configure (Initialize SDK)
| Field | Type | Default | Description |
|---|---|---|---|
| Write Key | string (required) | — | Your workspace source write key, from Events → Event Sources. Supports {{variable}} tokens. |
| Consent Mechanism | None | TCF v2 CMP | Custom | None | How consent gates event collection (see Consent). |
| Auto page view | boolean | on | Record a page view automatically when the SDK loads. |
| Debug logging | boolean | off | Verbose SDK console logging (visible in GTM preview/debug mode). |
| Flush after N events / Flush interval | number | 10 / 5000 ms | Event batching controls. |
| Track sessions | boolean | on | Group activity into sessions (visits) and carry the session id plus its rollup on every event. Zeotap emits a session_end event when a visit goes quiet — see Sessions. |
| Session timeout (minutes) | number | 30 | Inactivity before the next event starts a new session. Clamped to between 5 seconds and 30 minutes. |
| First-party cookie mode | boolean + proxy path | off | Server-set HttpOnly identifier via a proxy on your own domain — see First-Party Domain Setup. |
| Enable personalization | boolean | off | Read a Site for the visitor and deliver it to the page — see Personalization. |
| Site key | string | — | The Site’s public key, psk_…. Required when personalization is enabled. |
| Serving endpoint (optional) | string | — | Leave empty: the SDK derives the serving host from the ingest host. Set only if you are given a value. |
| Additional SDK options | key/value table | — | Advanced escape hatch: any SDK load option by name (values keep their JSON types), so new SDK options never require a template update. |
Infrastructure endpoints are not exposed; the template targets production automatically.
Consent
- None — events flow immediately; a Set Consent tag merely attaches the consent state to subsequent events.
- TCF v2 CMP — opt-in gating with automatic CMP integration: events are held until your CMP answers via
window.__tcfapi, and are dropped fail-closed if GDPR applies and the CMP never loads. Pair the Initialize SDK tag with GTM’s Consent Initialization trigger when your CMP loads through GTM. - Custom — opt-in gating without a CMP: events are held until a Set Consent tag fires (wire it to your own banner’s accept/reject).
Consent decisions persist across pages, so returning visitors are not re-gated.
Raw PII passed to Set User Identities is hashed client-side (SHA-256 + SHA-1) before any network call — raw values never leave the browser. On plain-HTTP pages, where the browser’s crypto APIs are unavailable, raw identifiers are dropped rather than sent unhashed; pre-hashed values are unaffected.
For internal and staging testing, Zeotap-owned pages can point the template at a non-production ingest by pushing zeotapApiHost (and, for bundles hosted under content.zeotap.com, zeotapSdkUrl) to the dataLayer before the container loads. These keys are read by the template but are never part of customer configuration — customer sites always use production.
Personalization
The template can also receive. With a Site key on the Initialize SDK tag, the SDK reads what the Site shares for the visitor — its audiences, realtime attributes and profile fields, under their labels — and pushes it onto the data layer, where any GTM trigger and variable can use it. What is pushed, when the page reads again and the consent it needs are set on the Site, not in the container.
Set it up
- On the Initialize SDK tag, tick Enable personalization and paste the Site key (
psk_…, from the Site’s Install dialog). Leave Serving endpoint empty. - On the Site, switch on the Data layer under Where the site gets it (nested is the default shape) and publish.
- Import the Zeotap Personalization variable template (Templates → Variable Templates → New → ⋮ → Import). Create one variable per thing you want to use:
- Read — Audience membership (
true/false), Attribute value or Profile field; - Label — the label the Site shares it under, for example
vip; - Data layer shape — the shape the Site publishes: Nested unless you changed it.
- Read — Audience membership (
- Fire tags on a Custom Event trigger with the event name
zeotap_personalization(or the name your Site sets), with a condition on your variable — for example vip equalstrue. - Optional: add a Refresh Personalization tag on any trigger that should re-read straight away, such as an add-to-cart click. Reads closer together than the Site’s minimum interval are combined. A Refresh tag that fires before the SDK has loaded does nothing; the load reads by itself.
What lands on the data layer
// Nested (the default)
{ event: "zeotap_personalization", _clear: true,
zeotap: { audiences: ["vip"], attributes: { cart_value_30m: 65.5 },
profile: { plan: "pro" }, meta: { site_id, version, as_of } } }
// Flat (when the Site chooses it)
{ event: "zeotap_personalization", zeotap_vip: true, zeotap_cart_value_30m: 65.5,
zeotap_cart_abandoner: false /* left since the last push */ }GTM merges data-layer pushes rather than replacing them. The _clear flag (nested) and the false / null reset keys (flat) make GTM’s data model hold the visitor’s latest answer, not every answer seen on the page. You can also read the pushed values with GTM’s built-in Data Layer Variable — zeotap.audiences or zeotap.attributes.cart_value_30m (nested), zeotap_vip (flat).
What the variable returns. Audience membership is true only when the visitor is in the audience, and false otherwise — including before the first push, when that part of the answer could not be read, and after the visitor leaves the audience. An attribute or profile field returns its value, or undefined when there is none; use the variable’s Format Value → Convert undefined to for a default.
Permissions. Personalization adds one permission to the tag template: calling zeotap.personalization.refresh. The variable template only reads zeotap and zeotap_* from the data layer, so if you change its Namespace (Advanced), edit that permission to match. The variable reads GTM’s own data layer, so a Site that publishes to a differently named data layer is only visible if the container uses that name too.
See On your website for the whole of what the page receives, when it reads again, and consent.
Verifying your setup
Use GTM’s Preview mode: each tag shows as fired, and the SDK logs to the console when Debug logging is on. Events appear in your workspace under Events → Live Stream within seconds. Every event sent through the template carries context.library.integration = {"name": "gtm-template", …}, so you can confirm traffic is coming from GTM rather than a stray snippet.
Next Steps
- Browser SDK — full API reference for what each tag type sends
- On your website — what a page receives from a Site
- Write Keys — provisioning event sources
- First-Party Domain Setup — the proxy behind first-party cookie mode
- Event Contracts — enforce event schemas downstream