AdID handling
The SDK reads the Google Advertising ID (AdID) automatically when:
- Your app targets Android 12 (API 31) or lower and Google Play Services is available.
- Your app targets Android 13+ (API 33+), has the
play-services-ads:20.4.0+ dependency, and the AD_ID permission declared.
To declare the permission:
<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>
Pass the AdID manually
If you already have the AdID (e.g. you read it via your own integration), pass it explicitly:
Collect.getInstance().setAdID("93200ff8-9c05-4a27-9081-9a123543689b");
Identity patterns
Tie post-login behavior to a known user
Map<String, Object> identities = new HashMap<>();
identities.put("email", "user@example.com");
identities.put("loginid", "userA-123");
identities.put("fpuid", "crm_42");
Collect.getInstance().setUserIdentities(identities);
Map<String, Object> loginEvent = new HashMap<>();
loginEvent.put("method", "password");
Collect.getInstance().setEventProperties("login", loginEvent);
Merge unknown and known users
Use setUserProperties (not setUserIdentities) to attach additional attributes to the same zi:
Map<String, Object> props = new HashMap<>();
props.put("plan", "premium");
props.put("country", "DEU");
Collect.getInstance().setUserProperties(props);
Differentiate two users on the same device
setUserIdentities ties events to the current identity until you unset:
Map<String, Object> alice = new HashMap<>();
alice.put("email", "alice@example.com");
Collect.getInstance().setUserIdentities(alice);
// ... Alice's activity
Collect.getInstance().unsetUserIdentities();
Map<String, Object> bob = new HashMap<>();
bob.put("email", "bob@example.com");
Collect.getInstance().setUserIdentities(bob);
// ... Bob's activity
Send identities only after the SDK hashes them
CollectOptions options = CollectOptions.builder(this)
.credential("YOUR_WRITE_KEY")
.areIdentitiesHashed(false)
.hashIdentities(true)
.build();
Collect.init(options);
Map<String, Object> identities = new HashMap<>();
identities.put("email", "xyz@gmail.com"); // hashed by SDK
identities.put("crmID", "12345"); // custom identity, sent as-is
Collect.getInstance().setUserIdentities(identities);
Send identities that are already hashed
CollectOptions options = CollectOptions.builder(this)
.credential("YOUR_WRITE_KEY")
.areIdentitiesHashed(true)
.build();
Collect.init(options);
Map<String, Object> identities = new HashMap<>();
identities.put("email_sha256_lowercase",
"32e19a491662fd86de7d3806b1199b76f0ee44e928d3475f05b0c8a59912c097");
identities.put("crmID", "12345");
Collect.getInstance().setUserIdentities(identities);
Common payloads
Add to cart
Map<String, Object> cart = new HashMap<>();
cart.put("productID", "sku_123");
cart.put("quantity", 1);
cart.put("price", 29.99);
Collect.getInstance().setEventProperties("addToCart", cart);
Purchase
Map<String, Object> order = new HashMap<>();
order.put("orderID", "order_456");
order.put("total", 89.97);
order.put("currency", "EUR");
Collect.getInstance().setEventProperties("purchase", order);
Logout
Collect.getInstance().unsetUserIdentities();
Set events with a callback
All event methods accept an optional SDKCallback. Use it to confirm dispatch or surface errors:
Collect.getInstance().setEventProperties("Add_to_cart", (res) -> {
// res.get("status"), res.get("message")
});
Working with zi
The SDK generates a zi per app install per write key. Override or reset it for advanced flows:
// Get current zi
String zi = Collect.getInstance().getZI();
// Reset zi (e.g. on logout when you want a fresh identity)
Collect.getInstance().resetZI();
// Override zi (e.g. use your own hashed loginid)
Collect.getInstance().setZI("your-hashed-loginid");
Pause and resume collection
Collect.getInstance().pauseCollection();
// ... no events sent in this window
Collect.getInstance().resumeCollection();
Group events under an event type
Use the eventType property to bucket related events under a common name:
Map<String, Object> props = new HashMap<>();
props.put("eventType", "setConfigurations");
props.put("colour", "black");
Collect.getInstance().setEventProperties("selectColour", props);
Contextual data captured automatically
You don’t need to send these explicitly — the SDK appends them to every event:
- Device ID (Android ID)
- IP address, telco carrier, network type, OS version
- Device manufacturer, model, version
- Client app name and app version
zi (SDK-generated user ID)- AdID (when permitted)
Last modified on June 22, 2026
