Skip to main content

​
Troubleshooting

SymptomWhat to check
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' }.
Build fails with method-too-large or compile errors.Add the Java 8 compile options to the android block: sourceCompatibility JavaVersion.VERSION_1_8 and targetCompatibility JavaVersion.VERSION_1_8.
Init runs but no events appear.Enable enableLogging(true) and check Logcat. Confirm optOut(false) and (if consent is in use) that setConsent has been called.
Init runs, consent looks fine, still no events.Open the Android Source in the Zeotap CDP and watch the PREVIEW tab. If nothing appears, verify the credential(write_key) matches the Source.
AdID is missing in event payloads.On API 31+, declare <uses-permission android:name="com.google.android.gms.permission.AD_ID"/> in your manifest. For apps targeting Android 13+, also add play-services-ads:20.4.0+.
Manual integration: flatDir doesn’t work.On Android Studio Bumblebee or later, flatDir isn’t supported in project-level repositories. Use sourceSets { main { jniLibs.srcDirs = ['libs'] } } inside the android block instead.
PII isn’t being hashed.Confirm hashIdentities(true) is set and the field name is a reserved PII key (email, cellno, loginid, cellno_cc). Custom identity keys are never hashed.
Location: The Maven URL must be included in /build.gradle (project-level) or settings.gradle, inside the repositories block.Consequence of not adding: Gradle won’t be able to resolve the com.zeotap:zeo-collect artifact and dependency resolution will fail at sync time.

​
FAQ

​
What versions of Android does the SDK support?

Minimum SDK 21 (Android 5.0). Tested through Android 14.

​
Where do events end up after they leave the device?

They land in the Android 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 init to complete before calling other methods?

Collect.init(options) returns synchronously, but getInstance() can return null very briefly during early app startup. Standard practice is to initialize in MainApplication.onCreate() and call SDK methods only after that point.

​
How do I get the zi for a user?

String zi = Collect.getInstance().getZI();
The zi is unique per app install per write key. It persists in SharedPreferences until reset via resetZI() or app uninstall.

​
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 — that’s why we recommend setUserIdentities for identifiers. With useConsent(true) and no consent set, the SDK queues events locally (up to maxCacheSize). Once consent arrives, allowed events are flushed; denied events are dropped.

​
How big can the local cache get during a network outage?

maxCacheSize controls this — default 100, max 200. Set it higher for poor-connectivity scenarios.

​
Can the SDK retrieve the AdID itself?

Yes. The behavior depends on your target SDK level:
  • Below Android 13: the SDK retrieves the AdID automatically as long as Google Play Services is on the device.
  • Android 13+: you must include implementation "com.google.android.gms:play-services-ads:20.4.0" and declare the AD_ID permission.
If you’d rather pass it yourself, call Collect.getInstance().setAdID(...).

​
How do I clear all identities on logout?

Collect.getInstance().unsetUserIdentities();
Removes every persisted identity in one call.

​
Accepted identifiers

The following PII keys are recognized and treated as reserved identifier fields:
  • email — registered email address. Hashed to sha256, sha1, md5 (lower + upper).
  • cellno — registered cellular phone number, without country code. Hashed to sha256, sha1, md5.
  • cellno_cc — phone number with country code (e.g. 33 1234567890 for France). Hashed with country code attached.
  • loginid — app-specific login ID. Always hashed.
  • Custom identities — crmID, ECID, visitorID, etc. Sent as-is (no hashing).
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.

​
Contextual data captured automatically

Every event payload includes:
  • Device ID / Android ID
  • IP address, telco carrier, network type, OS version
  • Device manufacturer, model, version
  • Client app name and app version
Last modified on June 22, 2026