FS.identify - Identifying users

Each time a page or screen loads from a user you can identify, you'll want a bit of JavaScript to call the FS.identify function to associate your own application-specific id with the active user. In this article, we'll refer to this as the uid (unique user id). 

FS.identify(uid); // uid is a string containing a unique identifier for the current user

FullStory maintains user identity using cookies, which can change over time and across devices. FS.identify 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.  

You should not use FS.identify 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 FS.setUserVars).

Careful! You can't re-identify someone once you've given them a unique id with FS.identify. Attempting to call FS.identify 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 FS.identify again with the same UID, but with additional FS.setUserVars values, the session won't be split.

Please note that setting the UID field in FS.setUserVars is equivalent to calling FS.identity, 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 FS.identify.

• 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 FS.setUserVars).

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

• Additionally, you should only call FS.identify 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. You could identify a user like so:

FS.identify('462718483'); // 462718483 appears in your app database as this user's id

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 could call FS.identify like so:

FS.identify(email_hmac);

Why shouldn't you use a guessable uid? Primarily, since FS.identify() 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

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

FS.identify(uid, userVars); // userVars is a JSON dictionary

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

FullStory has special system fields for displayName and email. You can supply values for these fields like so:

FS.identify('462718483', {
 displayName: 'Daniel Falko',
 email: 'daniel.falko@example.com'
});

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. For more about custom fields, see FS.setUserVars.

The userVars argument to FS.identify is the same format expected by FS.setUserVars. It's more convenient to write FS.identify(uid, userVars) instead of FS.identify(uid) immediately followed by FS.setUserVars(userVars). 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.

Anonymizing Users

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

It's important to note: 

As of April 2020, this API call was created as a replacement for FS.identify(false). If you're using an older version of your data capture snippet, you will need to update it to use FS.anonymize(). You can find the latest version of your data capture snippet in your Settings > FullStory Setup view. 

If you've used FS.identify(false) in the past, it will continue to work. 

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 FS.identify()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'}