Skip to main content

Identify User

Using identify, you can associate events with specific users. This enables you to build a full picture of how they're using your product across different sessions, devices, and platforms.

An identify call has the following arguments:

  • distinctId: Required. A unique identifier for your user — typically their database ID or email.
  • userProperties: Optional. A dictionary of key/value pairs to set person properties.
  • userPropertiesSetOnce: Optional. Like userProperties, but only sets a property if the user doesn't already have it set.
PaylisherSDK.shared.identify(
    "user_id_from_your_database",
    userProperties: ["name": "Name Surname", "email": "[email protected]"],
    userPropertiesSetOnce: ["date_of_first_log_in": "2024-03-01"]
)

Events captured after calling identify are identified events, and this creates a person profile if one doesn't already exist.

How identify works​

When a user first opens your app, Paylisher automatically assigns them an anonymous ID, which is stored locally. This lets the SDK track anonymous users — even across different sessions.

By calling identify with a distinctId of your choice (usually the user's ID in your database, or their email), you link the anonymous ID and the distinct ID together. All past and future events made with that anonymous ID are then associated with the distinct ID. This is what lets you associate events with a user from before they logged in for the first time, or across different devices and platforms.

You should call identify as soon as you're able to. Typically, this is every time your app loads as well as directly after your user logs in. You only need to call identify once per session to associate the user with their data.

Best practices when using identify​

1. Call identify as soon as possible — when the app first loads and immediately after login.

2. Use unique strings for distinct IDs — generate robust, unique IDs to prevent clashes between users. Avoid generic values like null, true, or default strings.

3. Set person properties — pass available properties via userProperties so the user's profile stays up to date. Person properties can also be set using capture.

Get the current user's distinct ID​

To check whether identify has already been called for the current user, or to fetch their distinct ID, call getDistinctId(). This returns either the ID automatically generated by Paylisher or the ID passed to identify():

let distinctId = PaylisherSDK.shared.getDistinctId()

Resetting user identification on logout​

When a user logs out, call reset() so future events from the same device are not linked to the previous user. This is especially important when multiple users share a device — it prevents data merging and clears the distinct ID and session context associated with the previous user.

PaylisherSDK.shared.reset()

Multiple devices and multiple users​

The SDK handles two common identity scenarios. Both behave identically on iOS and Android.

Same user on multiple devices (multi-device)​

By default, calling identify() again with the same distinctId for an already-identified user is suppressed (the SDK logs already identified with id). If the same user is active on several devices and you want each repeated identify() to refresh the person/device state, enable repeatedIdentifyBehavior:

let config = PaylisherConfig(apiKey: "API_KEY", host: "HOST")
config.repeatedIdentifyBehavior = .capture

When set to .capture, a repeated identify() with the same distinctId emits a fresh $identify event, refreshing the people/device state. It deliberately does not send a new $anon_distinct_id, so no unnecessary merge is created. The default is .ignore, which suppresses these duplicate calls.

Different user on the same device (multi-person)​

When a different user logs in on the same device, the SDK automatically performs an internal user switch: if a user is already identified and you call identify() with a different distinctId, the SDK clears the previous identity state (distinct ID, anonymous ID, groups, feature flags, and session) before identifying the new user. This prevents subsequent events from being attributed to the previous user — even if the app didn't call reset().

No extra flag is needed — just call identify(newUserId):

PaylisherSDK.shared.identify("user-123")
// app restart, then a different user logs in
PaylisherSDK.shared.identify("user-456")
PaylisherSDK.shared.capture("...")   // attributed to user-456

When to use reset()​

reset() is still the right call for logout. Recommended rule:

  • Login / user switch: identify(newUserId)
  • Logout: reset()