Identifying users

You can call our Identify Users API to associate users in Fullstory with a unique user ID (uid) from your database. This allows us to link all sessions from the same user ID to the same user card in Fullstory. Depending on how your login flow works, you may choose to call our Identify Users API on every page to ensure that any post-login redirects capture the ID of the logged in user.   

Fullstory maintains user identity using cookies, which can change over time and across devices. Identify API allows Fullstory to associate the current cookie with the user as your application uniquely knows them. We use the term *uid* to refer to your app's id for a given user.

Note: For Native Mobile apps, we store a uuid to be used for identification. If the user uninstalls the app or clears data from it, a new uuid will be created.

You should not use the identify API for anonymous or guest users, since you don't actually know who they are (however, you can still attribute custom variables to unidentified users with Set User Properties API.)

Careful! You can't re-identify someone once you've given them a unique id with the identify API. Attempting to call the identify API on an already-identified user will split the session and create a new, separate user. Not using it on the logout page or screen can help keep different users sharing a browser from being mixed up.

The uid is opaque to Fullstory, although it is a useful search criterion.

A session will only be split if a different value is passed along for the UID with the call. So, if you are calling the identify API again with the same UID, but with additional user properties, the session won't be split.

Please note that setting the UID field in user properties API is equivalent to calling the identify API, so if the UID is passed to both calls in succession, this will lead to re-identification and the session being split.

Best practices for uids

There are a few best practices you should adhere to when choosing uids for use with the identify API.

• A uid should uniquely identify a user within your application, but the uid string itself shouldn’t contain personal information or be publicly guessable for a given user.

• You should generally refrain from using information like email addresses or phone numbers as uids.  

  • Why shouldn't I use an email address for uid? For businesses that let users change email addresses and continue using the same user account, using the email address as theuid means that if the email address changes, a new user will be created in Fullstory for the new email address. This may not be desired behavior. If this behavior is acceptable, it's okay to use email address for uid. Otherwise, we recommend using a unique ID from your customer database for uid and providing the email address as a user variable instead (see user properties API). 

• We recommend not including special characters, such as a colons, when working with uids.

• Additionally, you should only call the identify API after a user has successfully authenticated into your application.

Suppose you use integers as unique keys for users in your application database. Since these are opaque and not personally-identifiable, they’re suitable for use as uids. I already have such an identifier in your application, a great way to generate one is by using an HMAC. By creating an HMAC of an otherwise-unsuitable uid (such as an email address) using a server-side secret, it becomes opaque.

For example, if your application uses email addresses to identify users, you could generate an HMAC on your server like so (pseudocode):

email_hmac = HMAC(secret, 'daniel.falko@example.com');

This HMAC value should be sent to the client once the user has successfully authenticated. Then, in JavaScript, you can pass the HMAC to the identify API.

Why shouldn't you use a guessable uid? Primarily, since our Identify Users API can be called by anyone on the site or app simply by running some javascript in their own browser, it's very easy to spoof a session to look like someone else. Using a non-guessable UID makes this much harder, since the attacker would need to know that private UID instead to spoof the user (e.g. something like "23sdfsdf3f255" vs "yourname@fullstory.com"). Such an attack in turn would pollute the results you see in Fullstory, since now you could have sessions attributed to a specific user that really didn't come from that user. Additionally, if the uid is guessable, someone could potentially use it to ask our servers if a user has an account on your site or app that has consented.

Specifying display name and email

The identify API also accepts an optional second argument: a JSON object containing simple key/value pairs that you'd like to capture for the current user.

Unlike the uid, you may choose to include personally-identifiable user information in the userVars.

Fullstory has special system fields for displayName and email. 

Display names and email addresses will show up automatically the next time you browse your user list in Fullstory.

You don't have to specify both display name and email as in the above example; either one is fine. That said, if you are passing in an email variable but not a displayName variable, we'll display the email as the display name of the customer's User Card.

userVars can specify fields other than displayName and email. In fact, you can capture any custom fields you like so long as you follow the naming rules. 

The userVars argument to the identify API is the same format expected by the user properties API. It's more convenient to combine the two with identify API instead of calling the identify API immediately followed by user properties API. The two formulations are equivalent, though.

Special Considerations

We have found that there are a handful of uids that can be easily misused. Usually this manifests itself in someone trying to apply a uid when they do not actually know who a particular user is.  As a result, Fullstory will ignore some special values as invalid, including: 0, 1, -1, "nan", "n/a", "undefined", "null", and "nil", along with any uids starting with a double underscore ("__"). You should not use these values as uids for specific users since we'll automatically ignore them. Instead, try to find a different scheme or reserve those identifiers from being applied.

Once a user has been identified with a uid, you cannot change that association. For example, it's not okay for user 5673 to also be user 9816. It's perfectly fine for the user with uid 5673 to have email: 'bob@bobsworld.org' as part of their userVars, because it's their email but not their unique uid.

Fullstory uids are case-sensitive. 

Note: Our Identify Users API is called on each Page/Screen in the Fullstory for Mobile Apps SDK and as such will appear in the events list after each Navigate event in Session Replay.

Anonymizing Users

If you wish to make a previously-identified user anonymous (such as during logout), you can use the Anonymize Users API. This will automatically split the session and associate the new session with a new anonymous user. 

Note: In the instance of previously unidentified users, the first time they are identified, Fullstory connects all of their previous sessions under the new identified ID and the anonymous ID will no longer exist. In the event that an anonymous user becomes identified but then later clears their cookies or accesses your application from a different device, they will become anonymous once more. However, as soon as our Identify Users API is called again, their previous sessions are once more connected to their identified user ID, provided you use the same UID to identify the user each time.

Impersonating Users

When you're impersonating (e.g., when your app's admin system allows support agents to log in as) a user, we recommend you differentiate the unique ids passed to the identify API to disambiguate impersonated users from "real" users.

If you normally generate a server-side HMAC like this:

email_hmac = HMAC(secret, 'name@customer.com');

you would instead generate it like this:

email_hmac = HMAC(secret, 'support@app.com::name@customer.com');

You can also differentiate the displayName variable to render it more cleanly. We use the following to make this look nicer in the UI:

{displayName:'someone@fullstory.com as name@customer.com'}