Skip to Content
StreamsGoogle Tag Manager

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).

  1. Download the template: zeotap-cdp-template.tpl 
  2. In GTM, open your container → Templates → Tag Templates → New.
  3. Open the editor’s ⋮ menu → Import, choose the downloaded zeotap-cdp-template.tpl, and Save.
  4. 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 TypePurposeInputs
Initialize SDKLoads the SDK and initializes it with your write key. Fire once per page.Write key, consent mechanism, options
Track EventRecords a named event.Event name, properties
Page ViewRecords a page view.Category, name, properties
Screen ViewRecords a screen view.Category, name, properties
IdentifyAssociates a user ID and traits.User ID, traits
GroupAssociates the user with a group/account.Group ID, traits
AliasLinks two user identifiers.New ID, previous ID
Set User IdentitiesSets 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 IdentitiesRemoves stored identities.Keys (empty = all)
Set ConsentSets the user’s consent state.Category booleans, TCF string, or US Privacy string
ResetClears identity and queued state (fire on logout).—
Refresh PersonalizationReads 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)

FieldTypeDefaultDescription
Write Keystring (required)—Your workspace source write key, from Events → Event Sources. Supports {{variable}} tokens.
Consent MechanismNone | TCF v2 CMP | CustomNoneHow consent gates event collection (see Consent).
Auto page viewbooleanonRecord a page view automatically when the SDK loads.
Debug loggingbooleanoffVerbose SDK console logging (visible in GTM preview/debug mode).
Flush after N events / Flush intervalnumber10 / 5000 msEvent batching controls.
Track sessionsbooleanonGroup 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)number30Inactivity before the next event starts a new session. Clamped to between 5 seconds and 30 minutes.
First-party cookie modeboolean + proxy pathoffServer-set HttpOnly identifier via a proxy on your own domain — see First-Party Domain Setup.
Enable personalizationbooleanoffRead a Site for the visitor and deliver it to the page — see Personalization.
Site keystring—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 optionskey/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.

  • 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

  1. On the Initialize SDK tag, tick Enable personalization and paste the Site key (psk_…, from the Site’s Install dialog). Leave Serving endpoint empty.
  2. On the Site, switch on the Data layer under Where the site gets it (nested is the default shape) and publish.
  3. 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.
  4. 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 equals true.
  5. 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

Last updated on