FS.identify - Identifying users

Each time a page 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 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.


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.

  • In other words, you should refrain from using information like email addresses or phone numbers as 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);


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 record 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.

userVars can specify fields other than displayName and email. In fact, you can record 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". 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. Although It's perfectly fine for the user with uid 5673 to have email: 'bob@bobsworld.org' as part of their userVars, because that is their email, not their unique uid.


Anonymizing Users

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


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'}

Can’t find what you’re looking for?

The FullStory team awaits your every question.

Contact Us