Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.spotzee.com/llms.txt

Use this file to discover all available pages before exploring further.

identify joins your external_id (whatever you call users in your own database) to a Spotzee user record and updates that record’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 user

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

Anything in the traits dictionary lands as a top-level field on the user record. The set of accepted traits is defined by your project’s data schema. Read Define custom user attributes for how to add or rename traits. 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 via identify(identity:) overload (below) or via track(event:properties:user:) inline updates.
The trait dictionary accepts [String: Any]. Values serialise as JSON: strings, numbers, booleans, arrays, nested dictionaries.

​
The Identity overload

For when you need to set the anonymous ID explicitly (for example, restoring a session after a crash) or pass timezone / locale, use the Identity initialiser overload: 
let identity = Identity(
    anonymousId: Spotzee.shared.anonymousId,
    externalId: "u_42",
    phone: nil,
    email: "sam@example.com",
    traits: [
        "timezone": "Australia/Sydney",
        "locale": "en-AU",
        "plan": "starter",
    ]
)
Spotzee.shared.identify(identity: identity)

​
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 user. 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. 
// 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.

​
Next steps

Track events

Trigger journeys and feed segments with custom events.

Define custom user attributes

Decide which traits Spotzee accepts.