API Reference - Zeotap docs

After Collect.initialize(option:) runs, retrieve the singleton with Collect.getInstance(). All tracking methods are called on this instance.

import ZeotapCollect

Collect.getInstance()?.setEventProperties("view_product", ["productID": "1234"])

Initialization

Method	Description
`static func initialize(option: Option) -> Void`	Initialize the SDK with the configured options. Call once in `AppDelegate`.
`static func getInstance() -> Collect?`	Returns the singleton instance. Returns `nil` if `initialize` hasn’t been called yet.

Events

setEventProperties

Tracks a named event with arbitrary properties.

Collect.getInstance()?.setEventProperties("view_product")

Collect.getInstance()?.setEventProperties("view_product", [
  "name": "test watch",
  "product": "watch",
  "price": "899"
])

setInstantEventProperties

Same as setEventProperties but bypasses the batch queue — the event is sent immediately. Useful for events you can’t risk losing on app termination.

Collect.getInstance()?.setInstantEventProperties("checkout_complete", eventProperties) { data in
  // handle response
}

Event types

Type	Description
System events	Predefined events the SDK emits automatically: `Set consent`, `Update consent`, `Set identities`, `Update identities`. Triggered on first consent/identity capture and any subsequent changes.
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.

Sample payload

{
  "events": [{
    "eventUUID": "4b22525c-de33-4c5f-8934-e04e682e9f6e",
    "event": {
      "eventName": "ViewProduct",
      "productName": "test product",
      "color": "white",
      "price": "100",
      "eventTimestamp": "2022-01-11 07:25:23 UTC"
    },
    "user": {
      "app_name": "TestApp",
      "advertising_id": "8626081E-56FB-4EB8-968D-56BB6156BB26",
      "att_authorization_status": "authorized",
      "os_type": "iOS",
      "os_version": "15.5",
      "country": "GBR",
      "app_version": "1.0",
      "device_model_identifier": "iPhone13,2",
      "network_type": "wi-fi",
      "carrier": "Jio 4G",
      "zi": "3B2F4C6D-2455-4BFD-8A1C-04FB5FEE4017"
    },
    "version": "1.0.0"
  }]
}

Page tracking

setPageProperties

Logs a page-view-style event and attaches page-level context to every subsequent event.

Collect.getInstance()?.setPageProperties(["name": "Product"])

Parameter	Type	Description
`properties`	`[String: Any]`	Page-specific properties.

User attributes

setUserProperties

Sends user attribute information attached to the current zi (and any identities set via setUserIdentities).

Collect.getInstance()?.setUserProperties([
  "display_name": "xyz",
  "age": 43
])

PII keys passed to setUserProperties are hashed before sending, same as setUserIdentities. Prefer setUserIdentities for identities so they persist across events; use setUserProperties for everything else.

Identities

setUserIdentities

Captures user identities that persist across subsequent events.

Collect.getInstance()?.setUserIdentities([
  "email": "test@gmail.com",
  "loginid": "testUser123",
  "cellno": "49 1234567890"
])

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.

Reserved raw PII keys

Key	Description
`email`	User’s raw email. SDK hashes to `sha256`, `sha1`, `md5` (lower + upper).
`cellno`	User’s raw cell phone number. Recommended format: `<country_code><space><number>`. Do not include `+`.
`loginid`	Always hashed before logging.
`fpuid`	First-party ID (CRM ID, DB ID, etc.).

Hashed identities

If you hashed PII client-side, send the hash keys directly with areIdentitiesHashed(true):

Collect.getInstance()?.setUserIdentities([
  "email_sha256_lowercase": "b0492275843c15593bba8a749c3379e3b5067aab173e91fcb37d840ca8b1738d",
  "cellno_with_country_code_sha256": "..."
])

Supported hashed PII keys — full matrix for email / cellno (with and without country code, plus E.164 format) / loginid across 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}
cellno_e164_{sha256,sha1,md5}
loginid_{sha256,sha1,md5}_{lowercase,uppercase}

See hashing guidelines for the expected preprocessing.

Custom identities

Any first-party identifier outside the reserved PII keys — crmID, ECID, visitorID, etc. Custom identities are always forwarded as-is; hashing flags do not apply.

Collect.getInstance()?.setUserIdentities(["crmId": "12345"])

unsetUserIdentities

Clears persisted identities. Call this on logout so subsequent events aren’t stitched to the logged-in profile.

Collect.getInstance()?.unsetUserIdentities()

setConsent

Sets consent in the non-TCF flow. Pass primary consent (track, identify) for Custom mode, or brand consent (zeotapVendorConsent, etc.) under any mode.

Collect.getInstance()?.setConsent(consent: [
  "track": true,
  "identify": true
])

Full walkthrough: Consent Resolution.

listenToAskForConsent

Registers a callback that fires when the SDK needs consent. Use this to trigger your consent UI.

Collect.getInstance()?.listenToAskForConsent(action: { _ in
  // trigger UI to appear
})

ZI (user ID)

Method	Description
`getZI() -> String`	Returns the SDK-generated `zi` for the current user.
`resetZI() -> Void`	Resets `zi` for the current user. Useful when distinguishing pre/post-login users.
`setZI(zi: String) -> Void`	Overrides the SDK-generated `zi`. Use a hashed `userid` or `loginid`.

ATT (iOS 14+)

On iOS 14+, the IDFA isn’t collected automatically. Use one of these methods after requesting ATT permission:

ATTrackingManager.requestTrackingAuthorization { status in
  // Option 1 — SDK reads IDFA from device
  Collect.getInstance()?.setAdvertisingIdByATTStatus(status: status)

  // Option 2 — pass status + IDFA explicitly
  Collect.getInstance()?.setATTStatusAndAdvertisingId(
    status: status,
    advertisingId: ASIdentifierManager.shared().advertisingIdentifier.uuidString
  )
}

See Examples → ATT and IDFA for the full pattern with switch-case handling.

Pause / resume

Method	Description
`pauseCollection()`	Suspends all event collection.
`resumeCollection()`	Resumes collection if previously paused.

Collect.getInstance()?.pauseCollection()
Collect.getInstance()?.resumeCollection()

Callback signature

Most methods accept an optional ResponseCallback. The callback receives a data object with status and message. See SDK Reference for the full callback contract.

Collect.getInstance()?.setEventProperties("Add_to_cart") { data in
  // handle response
}

​Initialization

​Events

​setEventProperties

​setInstantEventProperties

​Event types

​Page tracking

​setPageProperties

​User attributes

​setUserProperties

​Identities

​setUserIdentities

​Raw identities

​Hashed identities

​Custom identities

​unsetUserIdentities

​Consent

​setConsent

​listenToAskForConsent

​ZI (user ID)

​ATT (iOS 14+)

​Pause / resume

​Callback signature

Initialization

Events

setEventProperties

setInstantEventProperties

Event types

Page tracking

setPageProperties

User attributes

setUserProperties

Identities

setUserIdentities

Raw identities

Hashed identities

Custom identities

unsetUserIdentities

Consent

setConsent

listenToAskForConsent

ZI (user ID)

ATT (iOS 14+)

Pause / resume

Callback signature