Client API Requirements

The Client API allows users to capture 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 captured in FullStory. The validation requirements are listed in detail below.

• General Payload Requirements
• Event Name Requirements
• Property Name Requirements
• Property Value Requirements
• Reserved Properties
• Property Cardinality Limiting
• 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 Client API call is 512KB. Any payload larger than 512KB will be rejected.

Event Name Requirements

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

Property Name Requirements

Properties must be named using the pattern ident_type. Ident is a sequence of alphanumeric characters (A-Z, a-z, or 0-9), underscores (_), or hyphens (-). Type is a short suffix that denotes the type of the property. Properties names must start with an alphabetic character (A-Z or a-z). The maximum 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. Properties that take nested objects should not be type suffixed. Properties within nested objects must still conform to the naming requirements outlined in this section. For nested 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
    }
  }	
});

Property Value Requirements

The value of a property must conform to the type suffix for the property. If it doesn’t, the property will be rejected. 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.

Property Cardinality Limiting

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

• Up to 500 unique user properties from FS.identify()/FS.setUserVars() or the Set User Properties HTTP API
• Up to 1,000 unique event names from FS.event() or the Server Events HTTP API
• Up to 5,000 unique event properties from FS.event() or the Server Events HTTP API

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 captured by FullStory, and no new property names will be accepted. This limit will slowly reset as property names become older than the Product analytics retention window. While we will still show new events in the event list, they cannot be indexed or made searchable due to the cardinality limit.

Note: Events can still appear in the Event List in Session Replay even when the limit is reached. However, they cannot be indexed or searched for.

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

Property Rate Limiting

There are per-session rate limits for the number of calls to Client APIs. There are burst limits and sustained limits.

• FS.identify and FS.setUserVars have a burst limit of 10/second and a sustained limit of 30/minute.
• FS.event has a burst limit of 40/second and a sustained limit of 60/minute.

If these limits are exceeded for a given time interval, subsequent Client API calls within that time interval will not be captured in FullStory.

Troubleshooting

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