# Identity

Identify your users with your own user id and attach properties to them, so you can target surveys and follow users across devices.

Until you identify them, Screeb tracks your users as anonymous visitors. Identify each user with your own user id when they log in: you then know who answered, you can target surveys on their properties, and you follow the same user on every device. What identified and anonymous users mean on the Screeb side is explained in [Understanding user properties](https://help.screeb.app/user-data/user-properties/).

## Identify a user

Call it after login, with the id and the properties you know:

```swift
import Screeb

Screeb.setIdentity(uniqueVisitorId: "<USER-ID>", visitorProperty: [
    "firstname": "Jane",
    "plan": "pro",
    "last_seen_at": ISO8601DateFormatter().string(from: Date()),
    "authenticated": true,
])
```

The user id must be unique and stable, between 1 and 255 characters. Prefer your internal user id to an email address, which can change. Changing the identity closes any survey running for the previous user.

## Identify at startup

When the user is already logged in when Screeb starts, pass the identity to the initialization instead. Screeb then never creates an anonymous visitor for them.

```swift
Screeb.initSdk(
    context: nil,
    channelId: "<YOUR-CHANNEL-ID>",
    identity: "<USER-ID>",
    visitorProperty: ["plan": "pro", "authenticated": true]
)
```

## Update user properties

Properties describe the user: plan, role, signup date. Use them as hidden fields in your surveys or in targeting rules. Sending a property again overwrites its value; the other properties stay as they are. Set a value to null to delete the property.

```swift
Screeb.visitorProperty(visitorProperty: [
    "plan": "enterprise",
    "seats": 42,
    "signed_up_at": ISO8601DateFormatter().string(from: Date()),
    "trial": NSNull(),
])
```

A user has at most 1000 properties. Property names are 128 characters at most. Values are strings, numbers, booleans or dates. Some names, such as `email` or `firstname`, are reserved and expect a given format: see the [list of reserved properties](https://help.screeb.app/user-data/user-properties/).

On iOS, send dates as ISO 8601 strings and delete a property with `NSNull()`. The Kotlin Multiplatform SDK takes non-null values only: it cannot delete a property, and dates go as ISO 8601 strings.

## Reset the identity on logout

When the user logs out, reset the identity. Screeb starts a new anonymous visitor and closes any running survey.

```swift
Screeb.resetIdentity()
```

> [!WARNING]
> Reset once, on logout only. Each reset creates a new user on the Screeb side: resetting on every anonymous page or screen breaks the user's history, and the same person gets the same survey again.

## Read the current identity

```swift
Screeb.getIdentity { identity, error in
    print(identity ?? [:])
}
```

The result holds `anonymous_id` (generated by Screeb), `user_id` (null until the user is identified), `channel_id`, `session_id`, `session_start` and `session_end`.

```json
{
  "channel_id": "0e2b609a-8dce-4695-a80f-966fbfa87a88",
  "anonymous_id": "30311998-5bc4-4cb7-8aca-d4189319b450",
  "user_id": "user-42",
  "is_ready": true,
  "session_id": "eeba641a-f831-44cb-9d9e-5224ffc5b91b",
  "session_start": "2023-02-01T17:07:50.097Z",
  "session_end": "2023-02-01T17:32:57.632Z"
}
```

## Keep anonymous users out

To collect nothing until the user is identified, turn on **Ignore anonymous users** in your [workspace settings](https://admin.screeb.app/org/last/settings/behaviour). The SDK then waits for an identity before it sends any data.

## Work with an existing CDP

When Amplitude, Segment or RudderStack sends events to Screeb, Screeb finds the user of each event from its user id, or from its anonymous id before login. Once both ids appear on the same event, Screeb links them to one user, so a user who logs in keeps a single profile. Screeb never reads your CDP's ids from your app, and never moves an id from one user to another: keeping both tools on the same ids is part of your code. Three rules do it. The concepts are in [User identity across tools](https://help.screeb.app/integrations/user-identity-across-tools/).

### 1. Use the same user id everywhere

Identify the user in Screeb with exactly the value you give your CDP's `identify`, in the same place in your code, so neither tool lags behind.

```swift
Screeb.setIdentity(uniqueVisitorId: userId)
```

Amplitude drops user ids and device ids shorter than 5 characters, and the event then reaches Screeb as anonymous: use ids of 5 characters or more.

### 2. Share one anonymous id

Before login, CDP events carry only the CDP's own anonymous id (Amplitude device id, Segment or RudderStack anonymous id).

Give that id to Screeb. The current user adopts it and stays anonymous. When your CDP integration already created a Screeb user for that id, Screeb switches to it, so the events it received are not lost, and any survey running for the previous user closes. An identified user is never switched away from: the id then stays with its owner.

```swift
if let deviceId = amplitude.getDeviceId() {
    Screeb.setAnonymousId(anonymousId: deviceId)
}
```

Call it right after initialization: Screeb resolves the id before it creates any user, so both calls behave like a single init option. Calling it later works too. The id is 5 to 128 characters, and calling it again with the same id does nothing. Your CDP is not changed: Screeb never writes to it.

Do not pass the CDP anonymous id as the user id: that turns it into a user identity, and the real login then creates a second user instead of merging. If you cannot read the CDP anonymous id in your app, do the reverse: read the Screeb `anonymous_id` (see [Read the current identity](#read-the-current-identity)) and give it to your CDP as its device or anonymous id before the CDP sends its first event. Prefer the first way: changing your CDP's device id also changes it for every other tool connected to that CDP.

### 3. Reset both tools together on logout

Reset Screeb, reset your CDP, then share the new anonymous id again as in rule 2. A user holds at most 20 anonymous ids: past that, a new one is no longer attached to it.

```swift
Screeb.resetIdentity()
amplitude.reset()
if let deviceId = amplitude.getDeviceId() {
    Screeb.setAnonymousId(anonymousId: deviceId)
}
```

### Check the setup

The workspace setting **Ignore anonymous users**, and the integration option that ignores events from anonymous users, drop CDP events that carry no user id. Rule 2 needs both off: the workspace setting refuses the anonymous id with `anonymous_user_not_allowed`. Events that carry a user id are never dropped, so the merge at login happens either way.

To check it works, read the current identity and compare `anonymous_id` and `user_id` with what your CDP reports for the same user. In Screeb, the user page lists the CDP anonymous id among its aliases while the user is still anonymous, and a survey targeted on a CDP event shows a few seconds after the event.
