Identity & Users

Identify customers, set properties, and reset identity on sign-out.

The SDK starts with an anonymous identity, so your app can record activity before sign-in. Once a customer signs in, identify them with your application’s account ID to bring their activity, purchases, and Feature access together across devices.

Identifying a user

Call identify() after sign-in, or when your app restores a signed-in account:

// nuxie-doc-fragment: identify-user harness=sync-body
NuxieSDK.shared.identify(
    "user_12345",
    userProperties: [
        "plan": "premium",
        "signup_date": "2025-03-15"
    ],
    userPropertiesSetOnce: [
        "first_seen_platform": "ios"
    ]
)

Use the same stable account ID on every device and with a connected billing provider. Matching those identities lets Nuxie associate purchases and Feature access with the right customer. Your app handles sign-in; identify() associates Nuxie activity and access with that account.

User properties

userProperties sets or overwrites values. userPropertiesSetOnce sets a value only when it is absent:

// nuxie-doc-fragment: update-user-properties harness=sync-body
NuxieSDK.shared.identify(
    "user_12345",
    userProperties: [
        "plan": "enterprise",       // Overwrites existing value
        "company": "Acme Inc"       // Sets new property
    ],
    userPropertiesSetOnce: [
        "first_login": "2025-01-01" // Only sets if not already present
    ]
)

Use these properties in segments and Experience personalization. Properties are delivered with the identity event and updated through profile synchronization.

Reading the current identity

// nuxie-doc-fragment: inspect-user-identity harness=sync-body
// Get the effective distinct ID (identified ID if set, otherwise anonymous ID)
let distinctId = NuxieSDK.shared.getDistinctId()

// Get the anonymous ID (always available)
let anonId = NuxieSDK.shared.getAnonymousId()

// Check if the user is identified
let identified = NuxieSDK.shared.isIdentified

Resetting identity (logout)

Call reset() when the customer signs out:

// nuxie-doc-fragment: reset-user harness=sync-body
NuxieSDK.shared.reset()

The SDK clears the identified customer and creates a new anonymous ID. Pass keepAnonymousId: true only when you want to preserve the existing anonymous ID:

// nuxie-doc-fragment: reset-user-preserving-anonymous-id harness=sync-body
NuxieSDK.shared.reset(keepAnonymousId: true)

What happens during reset

The SDK clears the previous customer’s active properties, feature access, and Experience state, then loads the new anonymous customer’s profile. Subsequent events use the anonymous ID.

reset() changes Nuxie’s identity on the device where you call it. Your app and authentication provider control sign-out and sessions on other devices. Call reset() on each device when its app session signs out.

How identity works

On first launch, the SDK creates and stores an anonymous ID. It uses that ID until identify() selects a known customer.

What happens during identify

When the ID changes, the SDK switches to that customer, restores their cached profile when available, and requests an updated profile. It sends $identify with the supplied properties. Calling identify() with the same ID and no properties makes no change and does not force a refresh.

Anonymous-to-identified linking

On the first anonymous-to-identified transition, the SDK moves queued anonymous events to the identified customer. $identify includes the previous anonymous ID as $anon_distinct_id.

See Tracking events to record app activity and Profile sync for update timing.