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. The Identify Users 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 Users 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 uid's for use with the Identify Users 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.

• The same uid should never be used for more than one user.

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

  • 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 uid's.
• Additionally, you should only call the Identify Users 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 a uid. If you don't 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.

A note on mega users

A uid should uniquely identify a user within your application, therefore the same uid should never be used for more than one user. If the same uid is inadvertently set for multiple users with the Identify Users API, Fullstory coalesces these individuals into the same user card. If an unusually large number of sessions associated with a single uid are captured in a very short amount of time, it can lead to the creation of what we call a "mega user".

Because mega users can cause serious performance implications to our system if left unaddressed, we must take measures in a timely manner to rectify them. These measures may include a required update to the Identify Users API implementation that may have caused the mega user, as well as running a permanent deletion on all mega users and their sessions detected in the account.

You can read more about mega users here.

Specifying display name and email

The Identify Users 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 Users API is the same format expected by the user properties API. It's more convenient to combine the two with the Identify Users API instead of calling the Identify Users API immediately followed by user properties API. The two formulations are equivalent, though.

Special Considerations

We have found that there are a handful of uid's 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 uid starting with a double underscore ("__"). You should not use these values as a uid 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 uid's 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 Users 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'}