Skip to main content

​
Troubleshooting

SymptomWhat to check
npm install zeo-collect errors.Check Node ≥ 16 and npm ≥ 8. Clear cache (npm cache clean --force) and reinstall.
iOS: pod install can’t find ZeotapCollect.Confirm cd ios then pod install (run from the React Native ios/ directory). Try pod repo update first if the spec isn’t found.
iOS: build fails after pod install.Ensure you reopened the project in Xcode via .xcworkspace, not .xcodeproj. Close any other Xcode windows for the project first.
Android: Gradle sync fails with “Could not find com.zeotap:zeo-collect”.Confirm the Zeotap Maven URL is added in the project-level build.gradle (or settings.gradle) repositories: maven { url 'https://sdk.zeotap.com/android-sdk' }.
Android: build fails with method-too-large or compile errors.Add the Java 8 compile options to the app-level build.gradle.
Init runs but no events appear.Set logging: true in options and check the platform logs (Metro for iOS, Logcat for Android). Confirm opt_out: false and (if consent is in use) that setConsent has been called.
iOS shows events but Android doesn’t (or vice versa).Verify both android_write_key and ios_write_key are set in initialiseZeoCollect. Each is a separate Source.
Events from RN flow through but advertising_id is missing (iOS 14+).The RN package wraps the native iOS SDK — you still need to request ATT and pass the status. See iOS SDK → ATT and IDFA.
PII isn’t being hashed.Confirm hash_identities: true is set and the field name is a reserved PII key (email, cellno, loginid, cellno_cc, fpuid). Custom identity keys are never hashed.

​
FAQ

​
What versions of React Native are supported?

React Native 0.65+ is recommended. For the new architecture (Fabric / TurboModules), use zeo-collect 1.3.0 or higher with the required new-architecture configurations. Contact support@zeotap.com for issues on a higher version.

​
Do I need two Sources (one Android, one iOS)?

Yes. The Android and iOS Sources are configured independently in the Zeotap CDP, each with its own write_key. initialiseZeoCollect accepts both keys so events from each platform flow to the right Source.

​
Do I need to call initialiseZeoCollect more than once?

No — initialize once per app lifecycle in App.js inside a useEffect with empty deps. The native SDKs persist their state across screens.

​
Where should I call initialiseZeoCollect?

In your app’s entry point — typically App.js or App.tsx, inside a useEffect(() => { ... }, []) that runs once on mount. Initialize before navigation begins so the first screen view is tracked.

​
Do these functions return promises?

No. The exported functions are synchronous wrappers around native module calls. If you need response handling, pass an optional callback as the last argument: 
setEventProperties("event", { key: "value" }, (res) => {
  // res.status, res.message
});

​
How do I get the zi for a user?

The current React Native API doesn’t expose a JS-level getZI function. The zi is generated by the underlying native SDKs and attached automatically to every event. If you need it client-side, talk to your Zeotap POC.

​
What’s the difference between setUserProperties and setUserIdentities?

setUserIdentities is for identifiers (email, phone, login ID, CRM ID) that persist across every subsequent event. setUserProperties is for attribute snapshots (age, gender, plan tier). If you put an identity in setUserProperties, it won’t be cleared by unSetUserIdentities on logout — use setUserIdentities for identifiers. With use_consent: true and no consent set, the underlying native SDKs queue events locally (up to max_cache_size). Once consent arrives, allowed events are flushed; denied events are dropped.

​
How do I clear all identities on logout?

import { unSetUserIdentities } from 'zeo-collect';

unSetUserIdentities();
Removes every persisted identity in one call.

​
Accepted identifiers

Reserved PII keys (recognized by both native SDKs):
  • email — registered email address. Hashed to sha256, sha1, md5 (lower + upper).
  • cellno — cell phone number without country code. Hashed.
  • cellno_cc — cell phone number with country code. Hashed with country code attached.
  • loginid — app-specific login ID. Always hashed.
  • fpuid — first-party ID (CRM ID, DB ID).
  • Custom identities — crmID, ECID, visitorID, etc. Sent as-is.
Send only the main cell number — no country codes embedded in the number, no leading 0, no +, (, or ) symbols. To add a new reserved identifier, talk to your Zeotap TAM.
Last modified on June 22, 2026