Skip to content
Open Screeb

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.

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

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.

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.

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

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.

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.

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.

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

Screeb.resetIdentity()
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.

{
"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"
}

To collect nothing until the user is identified, turn on Ignore anonymous users in your workspace settings. The SDK then waits for an identity before it sends any data.

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.

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.

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.

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.

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) 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.

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.

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

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.