After Collect.init(options) runs, retrieve the singleton with Collect.getInstance(). All tracking methods are called on this instance.
import com.zeotap.collect.Collect;
Collect collect = Collect.getInstance();
collect.setEventProperties("view_product", eventProperties);
Initialization
| Method | Description |
|---|
static void init(CollectOptions options) | Initialize the SDK with the configured options. Call once in MainApplication.onCreate(). |
static Collect getInstance() | Returns the singleton instance. Returns null if init hasn’t been called. |
Events
setEventProperties
Tracks a named event with arbitrary properties.
// Event name only
Collect.getInstance().setEventProperties("Sample Event");
// Event name with properties
Map<String, Object> eventProps = new HashMap<>();
eventProps.put("Prop1", "Some Value");
eventProps.put("Prop2", "Some Value");
Collect.getInstance().setEventProperties("Sample Event2", eventProps);
| Parameter | Type | Description |
|---|
eventName | String | Required. Name of the event. |
eventProperties | Map<String, ?> | Optional. Properties attached to this event. |
cb | SDKCallback | Optional. Callback for response handling. |
setInstantEventProperties
Same as setEventProperties but bypasses the batch queue — sent immediately.
Collect.getInstance().setInstantEventProperties("checkout_complete", eventProps, (res) -> {
// handle response
});
Event types
| Type | Description |
|---|
| System events | Predefined events the SDK emits automatically: Set consent, Update consent, Set identities, Update identities. |
| Custom events | User-defined actions specific to your app: add_to_cart, remove_from_cart, complete_purchase, etc. |
Granular system-event tagging is enabled from May 14, 2024. System events from before that date are tagged with the common name SystemEnrichmentEvent.
{
"events": [{
"eventUUID": "4b22525c-de33-4c5f-8934-e04e682e9f6e",
"event": {
"eventName": "ViewProduct",
"productName": "test product",
"color": "white",
"prize": "100",
"eventTimestamp": "2022-01-11 07:25:23 UTC"
},
"user": {
"App_version": "1.0",
"adid": "93200ff8-9c05-4a27-9081-9a123543689b",
"Device_ID": "51a03094e32facc3",
"IP": "192.168.232.2",
"Network_Type": "Wifi_Internet",
"DeviceInfo": "Google : Android SDK built for x86 : 8.1.0",
"user_zi": "a355b5e1-c5e3-4993-ba33-99c74555cb63",
"App_name": "ZeotapApp",
"Carrier": "Android"
},
"version": "0.0.1"
}]
}
Page tracking
setPageProperties
Logs page properties attached to every subsequent event.
Map<String, Object> pageProperties = new HashMap<>();
pageProperties.put("name", "Product");
Collect.getInstance().setPageProperties(pageProperties);
User attributes
setUserProperties
Sends user attribute information attached to the current zi and any identities set via setUserIdentities.
Map<String, Object> userProperties = new HashMap<>();
userProperties.put("property", "value");
Collect.getInstance().setUserProperties(userProperties);
setUserProperties are hashed before sending, same as setUserIdentities. Prefer setUserIdentities for identities so they persist across events.
country and city are blacklisted for ingestion — Zeotap derives these from the IP address. See blacklisted fields.Identities
setUserIdentities
Captures user identities that persist across subsequent events.
Map<String, Object> userIdentities = new HashMap<>();
userIdentities.put("email", "test@gmail.com");
userIdentities.put("loginid", "testUser123");
userIdentities.put("cellno", "1234890987");
Collect.getInstance().setUserIdentities(userIdentities);
Raw identities
| Scenario | Options | Behavior |
|---|
| Forward raw PII as-is | areIdentitiesHashed(false), hashIdentities(false) | Sent unchanged. |
| Let the SDK hash | areIdentitiesHashed(false), hashIdentities(true) | SDK applies sha256, sha1, md5 (lower + upper) before sending. |
| Key | Description |
|---|
email | User’s raw email. SDK hashes to sha256, sha1, md5 (lower + upper). |
cellno | User’s raw cell phone number without country code. SDK hashes to sha256, sha1, md5. |
loginid | Always hashed before logging. |
cellno_cc | Cell number with country code. Hashed with country code attached. |
Hashed identities
If you hashed PII client-side, send the hash keys directly with areIdentitiesHashed(true):
Map<String, Object> userIdentities = new HashMap<>();
userIdentities.put("email_sha256_lowercase", "...");
userIdentities.put("cellno_with_country_code_sha256", "...");
Collect.getInstance().setUserIdentities(userIdentities);
sha256 / sha1 / md5 (lowercase + uppercase):
email_{sha256,sha1,md5}_{lowercase,uppercase}cellno_without_country_code_{sha256,sha1,md5}cellno_with_country_code_{sha256,sha1,md5}loginid_{sha256,sha1,md5}_{lowercase,uppercase}
See hashing guidelines for expected preprocessing.
Custom identities
Any first-party identifier outside the reserved PII keys — crmID, ECID, visitorID, etc. Custom identities are always forwarded as-is.
Collect.getInstance().setUserIdentities(
Collections.singletonMap("crmId", "123")
);
unsetUserIdentities
Clears persisted identities. Call this on logout so subsequent events aren’t stitched to the logged-in profile.
Collect.getInstance().unsetUserIdentities();
Consent
setConsent
Sets consent in the non-TCF flow. Pass primary consent (track, identify) for Custom mode, or brand consent under any mode.
Map<String, Object> consent = new HashMap<>();
consent.put("track", true);
consent.put("identify", true);
Collect.getInstance().setConsent(consent);
listenToAskForConsent
Registers a callback that fires when the SDK needs consent. Use this to trigger your consent UI.
Collect.getInstance().listenToAskForConsent(() -> {
// trigger UI to appear
});
ZI (user ID)
| Method | Description |
|---|
getZI() | Returns the SDK-generated zi for the current user. |
resetZI() | Resets zi for the current user. Useful when distinguishing pre/post-login users. |
setZI(value) | Overrides the SDK-generated zi. Use a hashed userid or loginid. |
AdID
| Method | Description |
|---|
setAdID(String adID) | Pass the advertising ID manually. If not called, the SDK reads it from the device (when permissions allow). |
Pause / resume
Collect.getInstance().pauseCollection();
Collect.getInstance().resumeCollection();
Callback signature
Most methods accept an optional SDKCallback. The callback receives a res map with status and message. See SDK Reference.
Collect.getInstance().setEventProperties("Add_to_cart", (res) -> {
// handle response
});
