Identity & Users

Identify users, manage anonymous IDs, and handle login/logout

Track users with distinct IDs. The SDK assigns every user an anonymous ID on first launch and lets you link it to a known identity when they sign in.

How identity works

Every device starts with an anonymous ID – a UUID generated on first launch and persisted on disk. This is the user’s effective identity until you call identify().

When a user signs in, call identify() with their unique ID from your backend. The SDK switches the effective distinct ID, migrates queued anonymous events, and selects the identified customer’s cached Journey state.

When the user signs out, call reset(). The SDK clears the identified ID and reverts to the anonymous ID.

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

Identifying a user

Call identify() when a user signs in or when you know who they are:

// 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"
    ]
)

What happens during identify

1. The SDK sets the new distinct ID.
2. If the distinct ID changed, it transitions cached Journey facts, releases, feature access, and pending work to the selected user.
3. When transitioning from anonymous to identified, locally stored anonymous events are reassigned to the new ID.
4. An $identify event is tracked with the new distinct ID and any user properties you provided.

User properties

Pass userProperties to set (or overwrite) properties on the user profile. Pass userPropertiesSetOnce to set properties only if they do not already exist.

User properties are used by segments, experiences, and experience view models. They are synced to the server with the $identify event and reconciled on the next profile refresh.

// 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
    ]
)

Resetting identity (logout)

Call reset() when a user signs out:

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

By default, reset() generates a fresh anonymous ID so the next person’s pre-identify events cannot link to the previous person. Preserve the current anonymous ID only when that is an intentional app-specific policy:

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

What happens during reset

1. The identified distinct ID is cleared.
2. User properties for the previous identity are removed.
3. Profile facts, Journey state, signed releases, feature access, and Experience caches for the previous user are cleared.
4. The SDK reverts to the anonymous ID as the effective distinct ID.

Anonymous-to-identified linking

The anonymous-to-identified transition is one fixed contract: the SDK migrates queued anonymous events and includes the previous anonymous ID in the $identify event as $anon_distinct_id. There is no runtime linking-policy switch.

Next steps

• Tracking Events – send custom and system events
• Segments – learn how user properties and events feed server-side segment evaluation
• Configuration – configure SDK setup