FS Recording Client API Requirements

The Recording Client API allows users to record custom data in FullStory via a Javascript API.  FS.event, FS.setUserVars, and FS.identify each receive as arguments a JSON object containing the custom data.  The contents of these JSON objects are validated before they are recorded in FullStory.  The validation requirements are listed in detail below.

• General Payload Requirements
• Custom Event Name Requirements
• Custom Property Name Requirements
• Custom Property Value Requirements
• Reserved Properties
• Custom Property Cardinality Limiting
• Custom Property Rate Limiting
• Troubleshooting

General Payload Requirements

The payload must be a valid JSON object.  For more details about the JSON format, visit https://www.json.org/.  The maximum payload size for a single Recording Client API call is 512KB.  Any payload larger than 512KB will be rejected.

Custom Event Name Requirements

Custom event names must be strings no longer than 250 characters.  There are no reserved characters for custom event names, so any characters or symbols can be used.  Custom events with names longer than 250 characters will be rejected.  Empty string custom event names (i.e. "") will also be rejected.

Custom Property Name Requirements

Custom properties must be named using the pattern ident_type. Ident is a sequence of alphanumeric characters A-Z, a-z, or 0-9 and underscores ("_"). Type is a short suffix that denotes the type of the property. Custom properties names must start with an alphabetic character (A-Z or a-z).  The maximum custom property name length is 512 characters, including the type suffix.  There are 10 valid type suffixes, which are listed in the table below.

In addition to these types, properties may also contain nested objects.  Custom properties that take nested objects should not be type suffixed.  Custom properties within nested objects must still conform to the naming requirements outlined in this section.  For nested custom events, the property name including the dotted concatenation of all its parent properties must still be under the length limit of 512 characters. 

Example:

FS.event(“exampleEvent”, {
  “nonNestedProperty_str”: “example string”,
  “singleNestedProperty”: {
    “childProperty_bools”: [false, false, true, false]
  },
  “multiNestedProperty”: {
    “childProperty1_date”: new Date("2014-03-11T13:19:23Z"),
    “childProperty2”: {
      “nestedChildProperty_int”: 1
    }
  }	
});

Custom Property Value Requirements

The value of a custom property must conform to the type suffix for the property.  If it doesn’t, the property will be rejected.  Custom properties have a maximum value size of 8192 bytes.  If the value for the property is larger than this limit, the property will be rejected.

Reserved Properties

For FS.setUserVars and FS.identify, there are five reserved property names.  These properties are used for special functionality in the FullStory app.  Reserved property names should not be type suffixed.  These reserved property names do not apply to FS.event.

Custom Property Cardinality Limiting

There is an organization-wide limit on the total number of user variables, custom event names, and custom event properties that FullStory will accept. These limits are as follows:

• Up to 500 unique user properties from FS.identify()/FS.setUserVars()
• Up to 1,000 unique custom event names from FS.event()
• Up to 5,000 unique custom event properties from FS.event()

Here's a few other things to keep in mind when it comes to these cardinality limits:

• A given property name can be sent any number of times and will only count once toward the cardinality limit.

• Properties with the same name sent with FS.setUserVars and FS.event are considered different properties for the cardinality limit.  Similarly, properties with the same name sent with FS.identify and FS.event are considered different properties with this limit.

• Properties with the same name sent with FS.identify and FS.setUserVars are considered the same property for the cardinality limit.

• Properties with the same property name but different event names are considered different properties for the cardinality limit.

If the cardinality limit is reached for either FS.event or FS.identify/FS.setUserVars, new property names will be rejected and will not be recorded by FullStory, and no new property names will be accepted. This limit will slowly reset as property names become older than the data retention window.

If your organization accidentally exceeded the cardinality limit and need it more quickly, contact us at support@fullstory.com.

Custom Property Rate Limiting

There are per-session rate limits for the number of calls to Recording Client APIs.  There are burst limits and sustained limits.  These limits are separate for FS.event and FS.identify/FS.setUserVars.  For FS.event, the burst limit is 10 call per second and the sustained limit is 30 calls per minute.  For FS.setUserVars, the burst limit is 5 calls per second and the sustained limit is 12 calls per minute.  If these limits are exceeded for a given session, subsequent Recording Client API calls for that session will be not be recorded in FullStory.

Troubleshooting

If you notice missing or malformed Recording Client API payloads in FullStory, this article provides guidance to troubleshoot and resolve the issue.