Troubleshooting
| Symptom | What to check |
|---|
| Calls are not routing to Zeotap. | Verify init() ran with the correct write_key and options. Check the network tab for failed requests to spl.zeotap.com. |
init() is executed but no calls fire (TCF). | Confirm your TCF 2.0 CMP is implemented correctly and the __tcfapi global is reachable on the page. |
init() is executed but no calls fire (Custom). | Custom consent requires setConsent to be called. The SDK won’t send events until consent is granted. |
| Need to see what’s being sent. | Initialize with { debug: true }. The SDK logs every call to the console instead of dispatching it. |
| PII isn’t being hashed. | Confirm hashIdentities: true is set, and that the field name you’re using is a reserved PII key. Custom identity keys are never hashed. |
| Cookies aren’t being written. | Confirm the page is served over HTTPS — onlySecureCookie defaults to true. Check that your domain option is set correctly for sub-domain scenarios. |
| Events from a sub-domain don’t stitch. | Set the domain option to your top-level domain (e.g. .zeotap.com) so cookies are visible across sub-domains. |
FAQ
Where do events end up after they leave the browser?
They land in the Source you configured in the Zeotap CDP. From there they’re available to segmentation, calculated attributes, profile lookups, and downstream destinations.
Do I need to wait for the SDK to load before calling its methods?
No. The snippet creates a queue (window.zeotap._q) that buffers method calls until the SDK has loaded. Call methods as soon as you’ve pasted the snippet — they’ll execute in order once the SDK is ready.
Can I use the SDK in a single-page app?
Yes. Add the snippet to the root index.html. Re-call setPageProperties on each client-side route change so each “page” gets the right context.
What’s the difference between setUserProperties and setUserIdentities?
setUserIdentities is for identifiers (email, phone, login ID, CRM ID, etc.) that persist across every subsequent event. setUserProperties is for attribute snapshots (age, gender, plan tier, etc.) that send once.
If you’re tempted to put an identity in setUserProperties, use setUserIdentities instead — that way logout (unsetUserIdentities) reliably clears it.
How do I gate cookie sync on a specific consent purpose?
Use the cookieSync primary consent field under the Custom consent strategy:
window.zeotap.setConsent({ track: true, cookieSync: false });
cookieSync flips back to true.
Does the SDK send a gdpr_consent string?
Only if you set includeTCFString: true in init() options and a TCF 2.0 CMP is present on the page. Without a TCF API, the SDK still works — it just doesn’t include the consent string in the payload.
What happens to events while the SDK is waiting for consent?
If useConsent: true and no consent has been resolved yet, the SDK queues events. Once consent arrives (via TCF API or setConsent), queued events are flushed if consent allows tracking — or dropped if it doesn’t.
How do I capture the GA Client ID?
Set allowGAClientId: true and configure gaClientIdCookiePrefix and gaUserIdCookieName to point at your GA cookies. See Configuration → Google Analytics integration.
How do I clear all identities on logout?
zeotap.unsetUserIdentities();
Where can I find the write_key?
In the Zeotap CDP UI, open the Web JS Source and check the IMPLEMENTATION DETAILS tab.
What versions are supported?
The SDK is loaded from https://content.zeotap.com/sdk/zeotap.min.js — that URL always serves the current production build. You don’t need to pin a version.Last modified on June 22, 2026
