Identify contacts

identify joins your external_id (the identifier you use in your own database) to a Spotzee contact and updates that contact’s traits. Until you call it, the SDK records activity against an anonymous ID it minted on first launch and persisted to UserDefaults.

Identify a known contact

import Spotzee

Spotzee.shared.identify(
    id: "u_42",
    email: "sam@example.com",
    phone: "+61491570006",
    traits: [
        "first_name": "Sam",
        "last_name": "Patel",
        "plan": "starter",
        "lifetime_value": 199.50,
    ]
)

The id parameter is your external_id. email, phone, and traits are all optional. Pass only what you have.

How traits flow

The SDK sends the traits dictionary as the contact’s data fields. Read Define custom contact attributes to review discovered attribute paths; project admins can set their visibility there. A few traits map to specific behaviour:

email and phone: top-level fields the email and SMS channels read from. Pass them as arguments to identify rather than nesting them in traits so the SDK puts them in the right place.
timezone and locale: drive personalisation and send-time logic. Set them with track(event:properties:user:) inline updates.

The trait dictionary accepts [String: Any]. Values serialise as JSON: strings, numbers, booleans, arrays, nested dictionaries.

Anonymous to known: automatic alias

The first identify after an anonymous session aliases the anonymous ID to your external_id. All prior anonymous activity now belongs to the known contact. Subsequent track and identify calls carry both IDs automatically. For server-side flows where you already know an anonymous ID separately, call alias directly:

Spotzee.shared.alias(anonymousId: "anon_xyz", externalId: "u_42")

The SDK guards against repeated aliasing: once externalId is set on the singleton, identify skips the auto-alias path. Calling alias directly always sends the request.

When to call identify

On sign-up. First call after the user creates an account.
On sign-in. So a user switching devices gets joined back to their record.
When traits change. Updating profile data, plan, lifetime value, billing state. Identify is upsert: pass only the traits that changed.

Avoid calling identify on every app foreground with the same data. The platform deduplicates server-side, but the network call is wasted.

Worked example: link anonymous browse to checkout

// User browses anonymously. Track fires against the auto-minted anonymous ID.
Spotzee.shared.track(
    event: "Product viewed",
    properties: ["sku": "SHIRT-AU-12"]
)

// User signs in. Identify joins the anonymous session to the known account.
Spotzee.shared.identify(
    id: "u_42",
    email: "sam@example.com",
    traits: ["plan": "starter"]
)

// Subsequent track calls carry both IDs. The "Product viewed" event from above
// is now part of u_42's history.
Spotzee.shared.track(
    event: "Checkout started",
    properties: ["cart_total": 89.95]
)

Reset on sign-out

Spotzee.shared.reset()

reset clears the cached externalId and mints a new anonymous ID. Subsequent activity is anonymous until the next identify.

Get started

Build

Configure

SDKs

Integrate

Reporting

Tools

API conventions

Recipes

Identify contacts

Identify a known contact

How traits flow

Anonymous to known: automatic alias

When to call identify

Worked example: link anonymous browse to checkout

Reset on sign-out

Next steps

Track events

Define custom contact attributes

​Identify a known contact

​How traits flow

​Anonymous to known: automatic alias

​When to call identify

​Worked example: link anonymous browse to checkout

​Reset on sign-out

​Next steps

Track events

Define custom contact attributes

Identify a known contact

How traits flow

Anonymous to known: automatic alias

When to call identify

Worked example: link anonymous browse to checkout

Reset on sign-out

Next steps