Skip to main content

Identify User

Linking events to specific users enables you to build a full picture of how they're using your product across different sessions, devices, and platforms.

This is straightforward to do when capturing backend events, as you associate events to a specific user using distinct_id, which is a required argument. However, on the frontend, a distinct_id is not a required argument and you can capture events anonymously.

To link events to specific users, call identify:

Paylisher.identify(
    distinctId = distinctID, // Replace 'distinctID' with your user's unique identifier
    // optional: set additional person properties
    userProperties = mapOf(
        "name" to "Name Surname",
        "email" to "[email protected]"
    )
)

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

How identify works​

When a user starts browsing your website or app, Paylisher automatically assigns them an anonymous ID, which is stored locally. This enables us to track anonymous users – even across different sessions.

By calling identify with a distinct_id of your choice (usually the user's ID in your database, or their email), you link the anonymous ID and distinct ID together.

Thus all past and future events made with that anonymous ID are now associated with the distinct ID. This enables you to do things like associate events with a user from before they log in for the first time, or associate their events across different devices or platforms.

Best Practices When Using identify​

1. Call identify as Soon as Possible​

In your frontend, call the identify method as early as you can:

  • When the app first loads: Ensures that all events in a session are correctly associated with the user.
  • Immediately after login: Links session data with the authenticated user.

You only need to call identify once per session to associate the user with their data.

2. Use Unique Strings for Distinct IDs​

Avoid data merging or misattribution by ensuring distinct IDs are truly unique:

  • Strong ID generation: Generate robust, unique IDs to prevent clashes between different users.
  • Avoid generic IDs: Do not assign values like null, true, or default strings (distinctId), as this may cause many users to share the same ID.
  • Paylisher safeguards: Paylisher includes protections for common distinct ID issues. Refer to their FAQ for more information.

3. Set Up Person Profiles and Properties​

Use the properties object in the identify method to populate person properties:

  • Pass all available properties: Ensure the user’s profile on Paylisher is consistently updated with the latest data.
  • Alternative via capture: Person properties can also be set using the capture method.

Getting the Current User's Distinct ID​

To verify if identify has already been called for the current user or to fetch their distinct ID:

Paylisher.distinctId()

Resetting User Identification on Logout​

Why Call reset() on Logout?​

When a user logs out, calling reset() ensures that future events from the same device are not linked to the previous user. This is especially critical in scenarios where multiple users share a single computer or device:

  • Prevents user data merging: Ensures that events are not mistakenly attributed to the wrong user.
  • Resets session context: Clears the distinct ID and cookies associated with the previous user.

How to Call reset()​

You can unlink user data by calling reset() during the logout process. For example:

Paylisher.reset()

Multiple devices and multiple users​

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

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:

val config = PaylisherAndroidConfig(apiKey = "API_KEY", host = "HOST")
config.repeatedIdentifyBehavior = 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):

Paylisher.identify("user-123")
// app restart, then a different user logs in
Paylisher.identify("user-456")
Paylisher.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()