FS.event API - Sending custom event data into FullStory

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 FS.identify and FS.setUserVars, which let you pull in custom user data to identify and add more valuable information about your users to your FullStory experience, we built FS.event to let 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. 

So, if you’d like to send client-side events over using our FS.event Javascript API, read on.

Instructions

The new FS.event JavaScript API allows you to add a custom event to the event stream captured by FullStory.

FS.event(eventName, eventProperties); //

The eventName parameter is a string containing the name of the event. The exact event name will be searchable via FullStory’s OmniSearch capabilities.

The eventProperties parameter is a JSON object containing additional information about the event. The set of properties relevant to each event may vary widely. Event properties will be searchable via OmniSearch.

eventName and eventProperties have specific formatting and content requirements.  These requirements are detailed in the (Client API docs). If event names or properties do not meet these requirements, they will not be captured into FullStory.

Add the FS.event code to your website, redeploy, and then follow the Testing Information below to see your custom events inside FullStory!

To successfully use FS.event, please check that the FullStory snippet deployed on your webpage or mobile application is up to date with the snippet in your settings page. You're specifically looking for a line in the snippet with the phrase "g.event". If the snippet you have installed on your website doesn't have the g.event line, please update your snippet.

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. 

All properties should be type suffixed in accordance with the requirements in (Client API format docs).  If a property is not type suffixed, we will attempt to infer the type.  Type inferencing is meant as a fallback, and we recommend that all custom properties sent to FullStory include a type suffix.

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.

Examples

✅ These 2 examples of events will be accepted by FullStory.

FS.event('Product Added', {
  cart_id_str: '130983678493',
  product_id_str: '798ith22928347',
  sku_str: 'L-100',
  category_str: 'Clothing',
  name_str: 'Button Front Cardigan',
  brand_str: 'Bright & Bold',
  variant_str: 'Blue',
  price_real: 58.99,
  quantity_real: 1,
  coupon_str: '25OFF',
  position_int: 3,
  url_str: 'https://www.example.com/product/path',
  image_url_str: 'https://www.example.com/product/path.jpg'
});
FS.event('Subscribed', {
  uid_str: '750948353',
  plan_name_str: 'Professional',
  plan_price_real: 299,
  plan_users_int: 10,
  days_in_trial_int: 42,
  feature_packs: ['MAPS', 'DEV', 'DATA'],
});

🚫 Below is an example of an event passing in an array of objects that will be ignored.

FS.event('Created Fields', {
  project_id_str: '1435323',
  fields: [{
    id: 'f84th3',
    name: 'User'
  }, {
    id: 'v8e9jv4',
    name: 'Title'
  }]
});

 

Order Completed Events

“Order Completed” events get treated in a special way by FullStory. The “Order Completed” 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. This exception only applies for client-side events.

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.

FS.event('Order Completed', {
  orderId_str: '23f3er3d',
  products: [{
    productId_str: '9v87h4f8',
    price_real: 20.00,
    quantity_real: 0.75
  }, {
    productId_str: '4738b43z',
    price_real: 12.87,
    quantity_real: 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 FS.event code to your website, perform a test event (like added 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.

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:

direct_1549571582013-Screen_Shot_2019-02-07_at_3.31.30_PM.png 

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