Identify Users

Create user identity

Each time a new session is started by a user who can be identified (your system has logged the user’s personal data) SessionStack allows you to associate him/her with the current session by assigning the user a unique cookie. If the user is anonymous, he’ll automatically get assigned a unique ID and name. As soon as the ‘identify’ function is called, the user will no longer be anonymous and his browsing data will be reconciled with the automatically assigned identifier.

SessionStack.identify({
    userId: 'USER-ID' // Your app user id
});

More personal details like email or display name can be easily stored.

SessionStack.identify({
    userId: 'USER-ID',
    email: '[email protected]',
    displayName: 'John Smith'
});

The userId, email, and displayName are predefined fields and they're of type string.

Along with email/display name, SessionStack lets you save custom data too.

SessionStack.identify({
    userId: 'USER-ID', // Required
    email: '[email protected]', // Not required
    displayName: 'John Smith', // Not required

    // Add your own custom user variables here.
    role_str: 'user',
    pricingPlanType_str: 'premium',
    pricingPlanCost_real: 49.99
});

To set a custom field, add a property in the object passed to the identify function where the key of the property should be composed of the custom field name, underscore, and the type of the field.
customFieldName_type: value

In case the name of the field is composed of multiple words it should be written down in camelCase.

🚧

Warning

The request to identify the session will be ignored completely in the following cases:
The type of the custom field is omitted
The specified type of the field mismatches the actual type of the value (e.g. the field should be of type string but the actual type is integer)

In both cases, a warning will be printed out in the browser console letting you know what needs to be resolved.

🚧

Warning

Once a field is created, its type cannot be changed.

📘

Note

All custom fields must be key/value pairs.

📘

Note

You should not be using the ‘identify’ function for anonymous or guest users, since you don’t actually know who they are.

All user data can be used for searching specific sessions.

Update user identity

All user identity data (except user ID) can be modified during the session. You need to call the identify function with the value(s) you want to update.

If you have identified user with userId: ‘USER-ID’ and email: '[email protected]‘, and you want to change the email to '[email protected]‘, call the identify function with the same userId and the new email

SessionStack.identify({
    userId: 'USER-ID',
    email: '[email protected]'
});

If you need to add user identity data during the session, call the ‘identify’ function passing user ID and the new data as key/value pairs.

SessionStack.identify({
    userId: 'USER-ID',
    displayName: 'John Smith'
});

You can set user email or display name the same way.

Restrictions

The value of each field should correspond to the specified type. In case the types mismatch, a warning will be printed out in the browser console.
The predefined fields (userId, email and displayName) are limited up to 128 characters each. Custom fields of type string should not be longer than 512 characters.

📘

Note

Values longer than the maximum length will be automatically trimmed to fit.

Clear user identity

When a given user logs out, you can clear his/her cookie in order to allow different users to share a browser without mixing up their session data. Calling identify(false) will clear the cookie of the identified user. The next started session from this browser will be associated with a new guest user.

SessionStack.identify(false);