Please see Fullstory's developer documentation for more detailed API information:
The Fullstory API allows users to capture custom data in Fullstory via a Javascript API. Most methods 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 a sequence of alphanumeric characters (A-Z, a-z, or 0-9), underscores (_), or hyphens (-). Properties names must start with an alphabetic character (A-Z or a-z). The maximum property name length is 512 characters.
Type suffix requirement for API V1
For version 1 of the Fullstory API, type suffixes in the form of _type are required for all property names. For version 2, type suffixes are no longer required. See custom properties for more information.
There are 10 valid type suffixes, which are listed in the table below:
|
Type suffix |
Meaning |
Example |
|
str |
string |
{ |
|
int |
integer |
{ |
|
real |
real |
{ |
|
date |
date in ISO-8601 UTC format |
{ |
|
bool |
boolean |
{ |
|
strs |
list of strings |
{ |
|
ints |
list of integers |
{ |
|
reals |
list of reals |
{ |
|
dates |
list of ISO-8601 UTC format dates |
{ new Date("2014-03-11T13:19:23Z"), new Date("2014-08-11T13:19:23Z") ] |
|
bools |
list of booleans |
{ |
In addition to these types, properties may also contain nested objects. 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.
Property Value Requirements
The value of a property must conform to the type specified for the property. (Either suffix for version 1 or an optional schema for version 2). For version 1, if it does not, the property will be rejected. For version 2, all properties without a type will be inferred by the server. 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
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 (in version 1). These reserved property names do not apply to capturing events.
|
Reserved Property Name |
Type |
Maximum Value Length |
What it does |
|
uid |
string |
256 characters |
Explicitly sets the unique identifier for the user |
|
displayName |
string |
256 characters |
Displays nice-looking user names |
|
|
string |
128 characters |
Displays user's email address |
|
acctId |
string |
256 characters |
Deprecated |
|
website |
string |
1024 characters |
Deprecated |
Property Cardinality Limiting
There is an organization-wide limit on the total number of user properties, event names, and event properties that Fullstory will accept. These limits apply to properties sent by the client API as well as the HTTP API. These limits are as follows:
- Up to 500 unique user properties
- Up to 1,000 unique event names
- Up to 5,000 unique event properties
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 user properties and event properties are considered different properties for the cardinality limit.
- Properties with the same name sent with “identify” and set user properties 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, new property names will be rejected and will not be captured by Fullstory. This limit will slowly reset as property names become older than the Product analytics retention window.
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, please reach out to our Support team here.
Property Rate Limiting
There are per-session rate limits for the number of calls to Client APIs. There are burst limits and sustained limits.
- User properties have a burst limit of 10/second and a sustained limit of 30/minute.
- Events have a burst limit of 40/second and a sustained limit of 60/minute.
- Page properties have a burst limit of 10/second and a sustained limit of 30/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.