FS.setUserVars API - Capturing custom user properties

Anytime you want to capture custom user properties or integrate with external tools (such as help desk software) call the FS.setUserVars function, which takes a single argument: a JSON object containing simple key/value pairs you'd like to capture.

FS.setUserVars(userVars); // userVars is a JSON object

To put it another way:

field: value,

If you have all the needed data, it can be easier to call FS.identify(uid, userVars) and skip a separate call to FS.setUserVars. Then again, sometimes the custom properties you want to capture in FullStory aren't available at page load — maybe due to a delayed XHR, for example — in which case, you'd call FS.setUserVars whenever the data does arrive.

What can you capture in this way? Just about anything. Here's an example that will make more sense after you read the subsequent sections below:

 "displayName" : "Daniel Falko",
 "email" : "daniel.falko@example.com",
 "pricingPlan_str" : "free", // is he a freemium, basic, or pro customer?
 "popupHelp_bool" : true, // did he turn off the aggressive in-app help?
 "totalSpent_real" : 14.50 // how much has he spent on in-app purchases so far?

In the example above, displayName and email are examples of system fields.

A system field is a built-in field that FullStory can use in special ways. For example, displayName is a system field, and setting it will give each user a distinct display name in the FullStory UI that can also be used in search.

System Field


What it does

uid string

Explicitly sets the unique identifier for the user

displayName string

Displays clear & distinct user names

email string

Displays user's email address


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.

The other fields, pricingPlan_str, popupHelp_bool, andtotalSpent_real are examples of hypothetical custom fields that you could capture and later leverage in a search to find sessions of users with specific characteristics. For example, using the custom fields above, you could answer questions such as:

  • Why haven't certain freemium users made in-app purchases?
  • How many freemium users have spent more than $10.50 on in-app purchases?
  • Who leaves pop-up help turned on most often: free, basic, or pro users?

Suffice it to say, custom user fields are pretty powerful.

User Properties in Action

When a userVar is set, it will be preserved on a user until it is changed. The current value of a userVar will be attached to every event (click, activity, custom event) as it happens. The value of the userVar will be preserved for that event to be the actual value set at the time the event occurred. Changes to a userVar will not effect previous events. FullStory does not go back and change the values associated with previous events.

Example Scenarios:

Example 1: You are searching for the exact session where users signed up for something (ie. loyalty rewards, membership, plan type, etc.)

For this example, let’s say we are passing a user variable for signup_status with two options: none or standard. If you just filtered on users with a standard sign-up status, you would see sessions from all of your signed up users, but not the exact session when they signed up. If you just filtered on users that clicked sign-up, you may get some false positives of existing members that clicked that button again for some reason.

However, if you set your user filter to signup_status is standard and then add an event filter of Clicked text is sign-up when the signup_status is none, you’ll find the exact session when the user went from not signed up to signed up. FullStory will pull sessions of existing signed-up users who performed the specific event when they weren’t signed-up. The value here is that the user variable is preserved with the event.


Example 2: You are searching for the first purchase session for your top spenders.

For this example, let’s say we are passing a user variable of lifetimeSpend. You can start your search using a user filter of lifetimeSpend is greater than $5K (for example) and an event filter of Clicked text is purchase when the lifetimeSpend is 0. FullStory will pull existing users who have spent above $5K before and then will show the exact session where they clicked purchase when they hadn’t spent anything at the time of that specific event.



Need to get in touch with us?

The FullStory Team awaits your every question.

Ask the Community Technical Support