Identity

Initial identity via ScreebProvider

Set the initial user identity when wrapping your app:

import { ScreebProvider } from "@screeb/sdk-react";

export const App = () => (
  <ScreebProvider
    autoInit
    websiteId="<YOUR-CHANNEL-ID>"
    userId="<USER-ID>"
    userProperties={{
      firstname: "<user-firstname>",
      lastname: "<user-lastname>",
      plan: "<user-plan>",
      last_seen_at: new Date(),
      authenticated: true,
    }}
  >
    <YourApp />
  </ScreebProvider>
);

info

The userId parameter should be your unique user identifier (user id, internal id, uuid, email, ...).

Change identity

Change the current user identity. Running surveys will be closed. Hooks will be triggered with new identity.

import { useScreeb } from "@screeb/sdk-react";

const MyComponent = () => {
  const { identity } = useScreeb();

  const handleLogin = async () => {
    await identity(
      "<USER-ID>",
      {
        firstname: "<user-firstname>",
        lastname: "<user-lastname>",
        plan: "<user-plan>",
        last_seen_at: new Date(),
        authenticated: true,
      }
    );
  };
};

Requirements

• Property names must be limited to 128 characters
• No more than 1000 attributes
• Supported types for values: string, number, boolean and Date.

Reset current identity

Reset the current user identity. This command must be called only once, since it creates a new identity on Screeb side.

import { useScreeb } from "@screeb/sdk-react";

const MyComponent = () => {
  const { identityReset } = useScreeb();

  const handleLogout = async () => {
    await identityReset();
  };
};

Add properties to the current identity

This command adds properties to the current user identity without resetting the identity.

To delete a user property, set it to null.

import { useScreeb } from "@screeb/sdk-react";

const MyComponent = () => {
  const { identityProperties } = useScreeb();

  const updateUserProperties = async () => {
    // Set user properties
    await identityProperties({
      firstname: "<user-firstname>",
      lastname: "<user-lastname>",
      plan: "<user-plan>",
      last_seen_at: new Date(),
      authenticated: true,
    });

    // Delete user property: set values to null
    await identityProperties({
      age: null,
      company: null,
      logged: true,
    });
  };
};

Requirements

• Property names must be limited to 128 characters
• No more than 1000 attributes
• Supported types for values: string, number, boolean and Date.

Get current identity

Retrieves the current user identity.

import { useScreeb } from "@screeb/sdk-react";

const MyComponent = () => {
  const { identityGet } = useScreeb();

  const getUserInfo = async () => {
    const user = await identityGet();
    console.log(user);
    // {
    //   anonymous_id: "<UUID>",
    //   user_id: "<UUID>",
    //   session_id: "<UUID>",
    //   session_start: "2023-05-04T16:30:15.882Z",
    //   session_end: "2023-05-04T17:02:09.087Z",
    //   channel_id: "<UUID>",
    //   is_ready: true,
    // }
  };
};

Good practices with an existing CDP

When Amplitude, Segment or RudderStack is a Screeb source, Screeb resolves the respondent of each forwarded event from its user id, or from its anonymous id when the visitor is not logged in. Once both ids appear on the same event, Screeb aliases them to one respondent, so a visitor who logs in keeps a single profile. Screeb never moves an id from one respondent to another, and it does not read your CDP's identifiers from your app: keeping the two tools on the same identifiers is part of your instrumentation. Three rules do it.

1. One user id, the same string everywhere

Identify the user in Screeb with exactly the value you give your CDP's identify: a stable internal id rather than an email, which can change. Do it in the same place in your code so neither tool lags behind the other.

const { identity } = useScreeb();
await identity(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. Give your CDP the Screeb anonymous id

Before login, CDP events carry only the CDP's own anonymous id, which is not the Screeb respondent the SDK displays surveys for. Read the Screeb anonymous id and hand it to your CDP as its anonymous or device id; the Screeb respondent id is one of its own aliases, so nothing else is needed on the Screeb side.

const { identityGet } = useScreeb();
const { anonymous_id: anonymousId } = await identityGet();
// Amplitude
amplitude.init(AMPLITUDE_API_KEY, { deviceId: anonymousId }); // or amplitude.setDeviceId(anonymousId)
// Segment
analytics.setAnonymousId(anonymousId);
// RudderStack
rudderanalytics.setAnonymousId(anonymousId);

Do this before the CDP sends its first event. The stock Amplitude, Segment and RudderStack snippets fire an initial page() or session event as soon as they load, before the Screeb anonymous id is available: remove that call or defer the CDP's load() / init() until you have the id. Otherwise that first event alone creates one stray anonymous respondent, and everything after it is aligned.

Without this rule, anonymous visitors exist twice (one respondent per tool) and surveys triggered by CDP events cannot display for them.

3. Reset both tools together on logout

Reset Screeb, read the new anonymous id, then reset your CDP and give it that id, in this order. Reset once, on logout only: resetting on every anonymous screen creates a new respondent each time on both sides.

const { identityReset } = useScreeb();
await identityReset();

Then repeat rule 2 with your CDP's reset().

What the "ignore anonymous users" settings change

The integration's "ignore events from anonymous users" option and the workspace-level "Ignore anonymous users" setting drop CDP events that carry no user id. Rule 2 needs both off to cover the pre-login window. An event carrying a user id is never dropped by them, so the login-time merge happens either way.

Check it works

Read the current identity and compare anonymous_id and user_id with what your CDP reports for the same visitor. In Screeb, the respondent page then lists both ids among its aliases, and a survey targeted on a CDP event displays a few seconds after the event.