Guides

Event model

Auto-tracked events, custom events, and screen tracking across all Zeta SDKs.

Suggest Edits

This page is for developers integrating event tracking into their app. It covers the events the SDK tracks automatically, how to send custom events, and how screen name tracking works across iOS, Android, React Native, and Flutter.

On this page

Auto-tracked events

The SDK automatically tracks lifecycle events without any code from your app.

EventiOSAndroidReact NativeFlutterDescription
app_installedYesYesYesYesFires on first launch only.
app_openedYesYesYesYesFires when the app transitions from background to foreground.
app_closedYesYesYesYesFires when the app transitions from foreground to background.
app_terminatedYesNoNoNoFires when the app is terminated (iOS lifecycle only).

Note: app_terminated relies on iOS application lifecycle callbacks that have no equivalent on Android. React Native and Flutter apps running on iOS receive this event through the underlying native SDK; on Android it is not fired.

Screen name tracking

Use trackScreenName to record screen navigation. The provided screen name is cached in memory and attached to subsequent events as a property until a new screen name is set.

ParameterTypeRequiredDescription
screenStringYesThe name of the current screen.
deeplinkStringNoThe deeplink URL that opened this screen.
properties[String: Any] / Map<String, Any>NoAdditional key-value pairs attached to the screen event.

iOS (Swift)

ZetaClient.shared.event?.trackScreenName(
    screen: "Product Detail",
    deeplink: "myapp://products/123",
    properties: ["category": "electronics"]
)

For Objective-C, see iOS Getting Started.

Android (Kotlin)

ZetaClient.event.trackScreenName(
    screen = "Product Detail",
    deeplink = "myapp://products/123",
    properties = mapOf("category" to "electronics")
)

For Java, see Android Getting Started.

Custom events

Send a custom event by passing a name and a dictionary (or map) of properties.

iOS (Swift)

ZetaClient.shared.event?.send(
    name: "purchase_completed",
    properties: [
        "product_id": "SKU-789",
        "quantity": 2,
        "total": 49.99
    ]
)

For Objective-C, see iOS Getting Started.

Android (Kotlin)

ZetaClient.event.send(
    name = "purchase_completed",
    properties = mapOf(
        "product_id" to "SKU-789",
        "quantity" to 2,
        "total" to 49.99
    )
)

For Java, see Android Getting Started.

Warning: Properties must be JSON-encodable (strings, numbers, booleans, arrays, dictionaries). If any single property value fails JSON encoding, the entire event is discarded. The SDK does not throw an error or notify your app when an event is discarded.

Event property constraints

  • Property keys are case-sensitive. Use consistent naming across platforms.
  • Property values must be JSON-encodable. Supported types: String, Number, Bool, arrays of these types, and nested dictionaries of these types.
  • All date-time values in event properties must be in ISO 8601 format, UTC (e.g., 2024-09-17T05:54:58.000Z).
  • There is no hard limit on the number of properties per event, but keep payloads reasonable. Large payloads increase network usage and processing time.
  • Event names should be meaningful and describe the action (e.g., purchase_completed, article_viewed). Avoid generic names like event1.

See also