Sending custom event data into Fullstory

Please see Fullstory's developer documentation for more detailed API information:


Fullstory gives you out of the box insights, and the ability to construct searches and find insights without any instrumentation. You can always search for users who clicked or tapped any CSS selector or text on your site or mobile app to get insights right away.

But you might want to add some custom instrumented events as an extra layer of context on top of your rich Fullstory data, if you:

  • Want to capture more details than can be captured by user click or tap actions
  • Have already identified a few key events that are crucial for you to understand your customer experience
  • Already have instrumented some events in a customer data platform you'd like to pull into Fullstory

Just like setting user properties, which let you pull in custom user data to identify and add more valuable information about your users to your Fullstory experience, you pull in your custom event data to identify and add more context to events occurring within a session. You can send client-side instrumented events into Fullstory via our Javascript API to search and segment your sessions.

Screen Shot 2022-06-17 at 10.44.50 AM.png

Then when viewing sessions, jump straight to the most important part and view the useful properties you've sent over.

order completed event.png

You can also use custom events to visualize important moments in user Journeys, run powerful Conversions analyses, and measure trends with metrics and dashboards.

If you have already instrumented custom events in Segment or Tealium - we have integrations to pull in your events automatically with no extra code to write. Visit the Segment integration or Tealium integration page for more details.

Limitations & Guidelines

Please review the Client API format docs for a comprehensive look at all the limitations and guidelines for sending custom data over to Fullstory.

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 ("") will also be rejected.

Fullstory cannot currently ingest event properties that are arrays of objects (with the exception of the "Products" property in "Order Completed" events, more details below); these values will be ignored until future work to support them is completed.

Fullstory will index and make available to search any custom event names or properties that you need for your use cases. However, if you are still designing your event naming and payload schema, we recommend adopting the Segment event schema.

  • We plan to surface functionality and analysis for events that conform to this specification. An example of this analysis, and one that we support currently, is tracking the dollar value of Order Completed events for the purposes of revenue attribution. More details below.
  • If you have a data format that differs from Segment's schema, Fullstory will happily accept, index, and make searchable that data too. You should just know that some future search functionality may be more limited.

Order Completed Events

"Order Completed" events get treated in a special way by Fullstory. These events undergo an additional transformation to facilitate future searches based on revenue.

Arrays of objects are generally ignored, but we make an exception to accept arrays of objects in the products property in an "Order Completed" event. Note:This exception only applies for client-sideevents.

If you'd like to format your "Order Completed" events to take advantage of future revenue searches, we'd recommend following Segment's "Order Completed" spec.

There are three things that we do when we receive an "Order Completed" event:

  1. We split the products in the "Products" property into their own event called Product Purchased.
  2. To help track the products to their order and connect them back to the order that they were purchased on, we copy down the orderId and checkoutId properties from the Order Completed event to the Product Purchased event if they're available.
  3. To facilitate future work toward revenue attribution, we will also calculate the revenue from price and quantity property, if they're both available. This is set as another property called revenue in the Products Purchased event and is searchable in the Fullstory app.

So what does this mean when you're looking at a Fullstory session?

  • If an "Order Completed" event that includes 3 products fires, you will see 1 "Order Completed" event and 3 "Product Purchased" events at the same point in the timeline.

order completed and product purchased 3x.png

Here is an example of an `Order Completed` event call using our version 2 API.

FS('trackEvent', {
  name: 'Order Completed',
  properties: {
    orderId: '23f3er3d',
    products: [
        productId: '9v87h4f8',
        price: 20.00,
        quantity: 0.75
      }, {
        productId: '4738b43z',
        price: 12.87,
        quantity: 6

The above Order Completed event gets translated into the following three events in the Fullstory app.

Order Completed
  orderId: '23f3er3d'
Product Purchased
  orderId: '23f3er3d'
  productId: '9v87h4f8',
  price: 20.00,
  quantity: 0.75,
  revenue: 15.00
Product Purchased
  orderId: '23f3er3d'
  productId: '4738b43z',
  price: 12.87,
  quantity: 6,
  revenue: 77.22

Note: Order Completed Events are not supported in Native Mobile as objects and arrays within arrays are not supported.

Testing Information

  1. After you've added the custom event code to your website, perform a test event (like adding a product to cart, or signing up for the email newsletter).
  2. Wait up to 30 minutes, or refresh the page.
  3. Then test within Fullstory to see if you can see the events you sent over with names and properties.
  4. Alternatively, add a delay by 5 minutes on any setVars or custom events calls, if possible— this should allow for our backend to fully process creating a new user and connecting their active session to them, so that after 5 minutes when the custom event is called, it can be associated with the user's active session.

To confirm that your events have successfully sent to Fullstory, look for the custom events in search as well as event filters.

Within Omnisearch (the top search bar) you should see a section called API Events (the names here like "Checkout Error", "Order Completed" are just samples, yours will differ)

API events omnisearch.png

You'll also have a new event filter available in Search called Custom Events:

custom event filter.png

If you've sent over any properties with those events, click the refine event icon to expand and filter more based on properties 

refine event button.png

In playback, you'll be able to see the events as annotation on your playback:


And inside your event list to the right of playback, you can drill down to see the properties associated with the events:

product purchased.png

Finally, check out Settings > Data Management > Events to make any minor adjustments. You can archive certain properties or events if needed (if you made a mistake, or no longer need to see that event in Fullstory). Once archived, you can find these events, properties, etc in the dropdown menu on each subsequent page. If you ever wish to unarchive these, simply click on the vertical ellipsis or folder icon at the end of the row of the corresponding object you are viewing. Over time, as your Products analytics retention window passes, older events that you stop using will no longer appear in this list. Specifically, API defined events will disappear from your events table after the window passes. The exception would be if an API defined event with the same name as the previously expired event gets captured again, it would reappear in your events table. As for User Defined events, these will always stay in your table, even after the window closes.

Screen Shot 2022-06-17 at 10.51.52 AM.png

You can also look at the API errors table to troubleshoot if you're having any issues with your custom events coming through. Check out our Troubleshooting resources to answer any questions that come up based on the errors you see.

Screen Shot 2022-06-07 at 12.35.30 PM.png

Need to get in touch with us?

The Fullstory Team awaits your every question.

Ask the Community Technical Support