FAQ & Troubleshooting

Implementation checklist

Walk through this after publishing a new build to confirm the extension is wired up correctly.

SDK loads. Open DevTools Network tab and look for zeotap.min.js — expect status 200.
Global is initialized. In the Console, type zeotap and press Enter. Expect:
```
{_q: Array(0), _qcmp: Array(0)}
```
If undefined, the Load Zeotap SDK action didn’t fire. Check your initialization rule. If _q / _qcmp aren’t empty arrays, events are queued because consent hasn’t been resolved yet.
Cookie syncs fire. In the Network tab, filter for spl.zeotap.com/fp — expect GET requests.
Track Event POSTs land. After a Track Event action fires, look for POSTs to spl.zeotap.com — expect status 204 (or 200). If you see 4xx, the write_key is wrong.
Events appear in CDP. Log into the Zeotap CDP, open your Adobe Tag Extension Source, and watch the PREVIEW tab.

Troubleshooting

Symptom	What to check
Extension not visible in Adobe Tags catalog.	Confirm you’re searching for Zeotap Collect Extension (exact name).
`zeotap.min.js` returns 404.	Adobe’s CDN cache may be stale. Build a new library version and republish.
`zeotap` is `undefined` in console.	Load Zeotap SDK action didn’t fire. Inspect your initialization rule’s event and conditions.
`_q` and `_qcmp` aren’t empty arrays.	Events are queued because consent isn’t resolved. For Custom mode, confirm the Set Custom Consent action fires before tracking events.
POSTs to `spl.zeotap.com` return 4xx.	Check the `write_key` matches the Source in the Zeotap CDP. Build a new library if you updated config.
Events fire but don’t appear in CDP PREVIEW.	Verify the Source is live (not archived). Try a brand-new event and confirm `204` response in the network tab.
Identities aren’t being captured.	Confirm Sync User Identities action is in a rule that fires after SDK is loaded. Identity keys must match reserved names (`email`, `cellno`, `loginid`, etc.).
PII is being sent raw when you expected hashing.	Confirm the PII Hashing Configurations setting on the extension config is PIIs are raw and must be hashed by Zeotap.
Cookie sync isn’t working.	Cookie sync is enabled by default. If it’s been disabled by Zeotap POC, contact them to re-enable.

FAQ

What’s the difference between the Adobe Launch extension and the Web JS SDK?

The Adobe Launch extension wraps the Web JS SDK. Same backend, same payload shape — but configured through Adobe Tags Rules instead of inline JavaScript. Use the extension if your marketing team manages tags through Adobe.

Can I use the Zeotap Adobe extension alongside the Web JS SDK on the same site?

You should pick one or the other. Running both would double-count every event.

Does the extension respect TCF?

Yes. With Consent Method set to GDPR, the extension reads the TCF API on the page and queries the publisher’s consent before recording events. Configure Purposes for track to match your TCF setup.

What’s the difference between the three PII hashing options?

PIIs are hashed by the customer: you hash PII client-side and send the hash keys (e.g. email_sha256_lowercase).
PIIs are raw and must be hashed by Zeotap: you send raw PII (email, cellno); the extension hashes before forwarding.
PIIs are raw and must be consumed as is: you send raw PII; the extension forwards unchanged. Use only when your Source contract permits raw storage.

Use Rules → Actions → Extension: Zeotap Collect → Set Custom Consent with brand-specific keys (zeotapVendorConsent, xyzVendorConsent, etc.). Brand consent works under any Consent Method.

How does the extension handle single-page apps?

The extension fires actions based on Adobe events. For SPA route changes, push a direct call event (_satellite.track('page_view')) and attach a Track Event → Page View action to a matching rule.

Where do I find my Write Key?

In the Zeotap CDP, open your Adobe Tag Extension Source and check the IMPLEMENTATION DETAILS tab. The write key is auto-generated when the Source is created.

Do I need a separate Source for staging and production?

Yes. Each Zeotap CDP Source has its own write_key. Create one Source per environment to isolate staging traffic from production.

How do I add a new identifier that’s not in the reserved keys list?

Contact your Zeotap TAM with the field name you want to add. They’ll update the catalogue and confirm the correct key to use.

Why are `country` and `city` not showing up even though I send them in User Attributes?

They’re blacklisted — Zeotap derives them from the user’s IP automatically. See blacklisted fields for the complete list.

Auto-captured data

Even without configuring it, every event payload includes:

Page URL, path, referrer
IP-derived country (overridden by Country Code config if set)
User-Agent-derived device OS, type, browser
zi (SDK-generated user ID)
gdpr_consent string (when TCF is in use)

​Implementation checklist

​Troubleshooting

​FAQ

​What’s the difference between the Adobe Launch extension and the Web JS SDK?

​Can I use the Zeotap Adobe extension alongside the Web JS SDK on the same site?

​Does the extension respect TCF?

​What’s the difference between the three PII hashing options?

​How do I send brand consent?

​How does the extension handle single-page apps?

​Where do I find my Write Key?

​Do I need a separate Source for staging and production?

​How do I add a new identifier that’s not in the reserved keys list?

​Why are country and city not showing up even though I send them in User Attributes?

​Auto-captured data