Sending custom event data into Fullstory

• Introduction
• Limitations & Guidelines
• Examples
• Order Completed Events
• Testing Information

Introduction

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.

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

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.

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.

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
}

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)

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

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

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:

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. When an event is archived, it will be ignored when the FS.event API attempts to send that event to Fullstory. If you ever wish to unarchive these events, 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.

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.