FS.setUserVars API - Recording custom user data

Anytime you want to record custom user data 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 record.

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 data you want to record in FullStory isn't available at page load — maybe due to a delayed XHR or something — in which case, you'd call FS.setUserVars whenever the data does arrive.

What can you record 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?

displayName and email are examples of system fields. pricingPlan_str, popupHelp_bool, andtotalSpent_real are examples of hypothetical custom fields that you could record to later search for sessions whose users have specific characteristics. For example, using the custom fields above, you could answer questions such as:

  • What's going with freemium users who have never 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?

Custom user fields are pretty powerful.

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 nice-looking 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 nice-looking user names

email string

Activates "Email this user"


Custom fields

A custom field is one that you define that FullStory saves, displays, and that can be used in search. For example, pricingPlan_str is a custom field, as you can see by the formulation of its name: all custom field names have an underscore and suffix. More specifically, custom fields must be named using the pattern ident_type, where ident is a sequence of alphanumeric characters A-Z, a-z, or 0-9 and type is a short suffix that denotes the type of the field, which can be any of these. Custom field names must start with an alphabetic character (A-Z or a-z).

Type suffix Meaning Example
str string
 "nickname_str": "boo"
int integer
 "PasswordResets_int": 49 
real real
 "amtAbandonedInCart_real": 3.84 
date date in ISO-8601 UTC format
new Date("2014-03-11T13:19:23Z") }
bool boolean
 "didSelfServiceSignup_bool": true
strs list of strings
"cartIds_strs": ["a123", “b456”]
ints list of integers
"ids_ints": [123, 456, 789]
reals list of reals
"coordinates_reals": [40.7, -74.0]
dates list of ISO-8601 UTC format dates
 "date_range_dates": [ 
new Date("2014-03-11T13:19:23Z"),
new Date("2014-08-11T13:19:23Z")
bools list of booleans
"preferences_bools": [true, false, true]


All of the fields you capture will be visible in the FullStory UI using the Event Scope drop down, as well as in Settings > FullStory Setup.

Learn more about common troubleshooting tips for custom user data.


Need to get in touch with us?

The FullStory Team awaits your every question.

Contact us