Identity & Users

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

Identity & Users

Track users across sessions 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 from the anonymous ID to the identified ID, migrates locally stored data, and starts a new session.

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

Reading the current identity

// 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:

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 notifies all subsystems (profile, segments, campaigns, features) to transition to the new user.
3. If transitioning from anonymous to identified and eventLinkingPolicy is .migrateOnIdentify, locally stored events are reassigned from the anonymous ID to the new ID.
4. A new session starts.
5. 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, campaigns, and flow view models. They are synced to the server with the $identify event and reconciled on the next profile refresh.

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:

NuxieSDK.shared.reset()

By default, reset() keeps the anonymous ID so the device retains a stable identifier across sessions. To generate a fresh anonymous ID:

NuxieSDK.shared.reset(keepAnonymousId: false)

What happens during reset

1. The identified distinct ID is cleared.
2. User properties for the previous identity are removed.
3. Profile cache, segment memberships, campaign journeys, feature access, and flow caches for the previous user are cleared.
4. The session resets.
5. The SDK reverts to the anonymous ID as the effective distinct ID.

Event linking policy

When a user transitions from anonymous to identified, the SDK can reassign locally stored events so they appear under the identified user. This is controlled by the eventLinkingPolicy configuration option:

The server also receives the anonymous ID in the $identify event (as $anon_distinct_id), enabling server-side identity resolution regardless of the local policy.

Next steps

• Tracking Events -- send custom and system events
• Segments -- learn how user properties and events feed on-device segment evaluation
• Configuration -- set the event linking policy and other identity options