FS.setUserVars - 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 dictionary

To put it another way:

FS.setUserVars({
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:

FS.setUserVars({
 "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

Type

What it does

displayNamestring

Displays nice-looking user names

emailstring

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:

Type suffixMeaningExample
strstring
{ 
 "nickname_str": "boo"
}
intinteger
{
 "PasswordResets_int": 49 
}
realreal
{ 
 "amtAbandonedInCart_real": 3.84 
}
datedate in ISO-8601 UTC format
{ 
 "initialSignupDate_date": 
 new Date("2014-03-11T13:19:23Z") 
}
boolboolean
{ 
 "didSelfServiceSignup_bool": true 
}

Note: you will need to use camelCase when defining a custom field, with no intervening spaces or punctuation. For example pricingPlan_str will work, while pricing-plan_str will not.


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


Can’t find what you’re looking for?

The FullStory team awaits your every question.

Contact Us