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 any CSS selector or text on your site 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 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.

1.gif

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

2.gif

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. 

Currently you can only send client-side events, not server-side events into FullStory.

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 recorded 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 (Recording Client API docs). If event names or properties do not meet these requirements, they will not be recorded 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 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 Recording 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 (Recording 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. 

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.

direct_1550604774781-Screen_Shot_2019-02-19_at_2.32.28_PM.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: 'abc123'
}
Product Purchased
{
  orderId: 'abc123'
  productId: 'pdt1',
  price: 20.00,
  quantity: 0.75,
  revenue: 15
}
Product Purchased
{
  orderId: 'abc123'
  productId: 'pdt2',
  price: 12.87,
  quantity: 6,
  revenue: 77.22
}

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 Custom Events (the names here like "Checkout Error", "Order Completed" are just samples, yours will differ)

direct_1550604955210-Screen_Shot_2019-02-19_at_2.35.43_PM.png

And filtering your list of sessions will have a new option called Custom Events:

direct_1549564029865-1549564029865.png

If you’ve sent over any properties with those events, click the [...] button to expand and filter more based on properties 

direct_1549574647083-Screen_Shot_2019-02-07_at_3.31.01_PM.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:

 direct_1549571567061-Screen_Shot_2019-02-07_at_3.32.14_PM.png

Finally, check out the settings page to make any minor adjustments. You can hide certain properties or events if needed (if you made a mistake, or no longer need to see that event in FullStory). Over time, as your session retention window passes, older events that you stop using will no longer appear in this list.

direct_1550866864068-1550866864068.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.

direct_1550866859002-1550866859002.png

Need to get in touch with us?

The FullStory Team awaits your every question.

Contact us