Event Tracking : Sandbox

TABLE OF CONTENTS

Introduction
Setup
Payloads
CLICKED clickType explained
Widget IDs (widgetInstance)
Events
Conclusion

Introduction

At Feefo, we strive to provide you with detailed insights into user interactions with our widgets. Currently, we track loaded, viewed, and clicked events, and we've made it easy for you to integrate this data into your own systems. In this article, we'll guide you through the setup, payloads, and specifics of each event type.

Setup

Setting up the event tracking listener is a straightforward process. Use the provided JavaScript template below, either in a <script> tag in the head of the page or wherever it suits your needs.

<script>
  document.addEventListener('feefo_widgetTracking', (data) => {
    console.log(data.detail);
  });
</script>

This listener will catch the 'feefo_widgetTracking' event broadcasted on the document, allowing you to ingest and parse the data in your systems.

The widgets are situated in the shadow DOM we have used the CustomEvent interface as the event we are broadcasting. Most of the information in the data object is related to the CustomEvent with our tracking details in the details property of the data.

Payloads

The payload, or data broadcasted with our events, contains common properties and additional ones based on the event type. Let's explore the common properties:

Payload	Description	Type	Value
Locale	Default language	String	en-gb
merchantSlug	The merchant identifier	String	example-id
url	The URL where the event was fired	String	http://www.example.com/ path/to/widget
userId	User ID: Unique Session Identifier (UUID)	String	ebd2849-6d34-4b02-932e-1bd4d740
userAgent	Information about application, OS, and version	String	Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_4)…
instanceId	Instance ID for all event types per user session	String	65573e-3aa1-4d15-83f2-eaa849d65
date	Time of the event as a UNIX timestamp	Integer	1702987298464
eventType	Type of event: LOADED, VIEWED, CLICKED	String	LOADED, VIEWED, CLICKED
widgetInstance	The instance of the widget that the event occurred on	String	FEEFOWIDGET-PRODUCT-STARS
productSku / parentSku	Available only for Product Widget Instance	String	DETAIL
reviewData	An object containing the review count along with the average rating for the related product.	Object { reviewCount: number, avgRating: number, }	{ reviewCount: 10, avgRating: 1.8, }
qaaData	An object containing the information about the question and answer widgets (if available). Currently only populated in the question display widget.	Object { questionCount: number, }	{ questionCount: 38, }

Along with the common properties, the CLICKED event also has some additional information about the click. These are stored in the ‘context’ of the event details.

Payload	Description	Type	Value
targetElement	The clicked element type	String	DIV / A / SPAN etc
targetClass	The classname of the element that was clicked on, if present	String	'.feefo-classname'
clickType	Name given for the target section	String	Filters / General / Pagination etc.

CLICKED clickType explained

Within the context of the CLICKED details there is a property named ‘clickType’. This represents which part of the widget was clicked, in most cases this is ‘General’, however, in specifically defined areas of the individual widgets there may be another type such as ‘Pagination’ or ‘Filters’.

On-Page Reviews

Click event types for On-Page Reviews explained (Service/Product, Lightbox: Service/Products)

Target Area #	Target Area	Target Name
1	Undesignated area anywhere in the widget that is not listed below.	General
2	All Ratings or Filter icon	Filter
3	Newest or Popular Tabs	Tabs
4	Pagination Items	Pagination
5	Read all Reviews link	Read reviews Link

Media Integration

CLICK events for Media Integration explained

Target Area #	Target Area	Target Name
1	Undesignated area anywhere in the widget that is not listed below.	General
2	All Ratings or Filter icon	Filters
3	View Product Button	View Product

A screenshot of a website

Description automatically generated

Carousel

Click areas for carousels explained

Target Area #	Target Area	Target Name
1	Undesignated area anywhere in the widget that is not listed below.	General
2	Read all reviews link	Read Review Link
3	Carousel indicator to change the review	Carousel Indicators
4	Carousel right arrow	Right Arrow
5	Carousel left arrow	Left Arrow

A screenshot of a computer screen

Description automatically generated

Click events for the Floating Widget explained.

Target Area #	Target Area	Target Name
1	Undesignated area anywhere in the widget that is not listed below.	General
2	Filter icon	Filters
3	Newest or Popular Tabs	Tabs

Common rules for both LOADED and VIEWED event when either Product SKU or Parent Product SKU is available

This is only applicable to Product widgets. When a page contains the widgets with Parent Product SKU and Product SKU, the Product SKU takes the priority over Parent Product SKU. Therefore the payload will have Product SKU. If no Product SKU is provided but the Parent Product SKU then the payload will contain Parent Product SKU instead.

Product SKU	Parent Product SKU	Payload contains
Yes	No	Product SKU
Yes	Yes	Product SKU
No	Yes	Parent Product SKU

Each payload includes a widgetInstance, identifying the type of widget generating the event. Here are some possible widgetInstance values:

HIGHLIGHTED_SNIPPETS
MEDIA_GALLERY
FACEBOOK
MEDIA_GALLERY_SERVICE
MEDIA_GALLERY_PRODUCT
ON_PAGE_PRODUCT_REVIEWS
ON_PAGE_PRODUCT_OPTIONAL_STARS
ON_PAGE_SERVICE_REVIEWS
POPUP_REVIEWS
POPUP_REVIEWS_SERVICE
POPUP_REVIEWS_PRODUCT
SERVICE_CAROUSEL_WIDGET
SLIDE_OUT_REVIEWS
HIGHLIGHTED_TOPICS
PRODUCT_STARS_WIDGET
QUESTION_DISPLAY
QUESTION_FORM

Events

Loaded

For all widgets except Product Stars, When any page with the given widget loads, irrespective of its position on the page, this information should be sent to the Feefo API.

For each of the widgets on the page, two ‘LOADED’ events will be fired:

Payload with reviews data
Payload without reviews data

Reviews Data

Reviews Data is an object containing 'avgRating' and 'reviewCount'. This is shown when the average rating and number of displayed reviews have been identified for the widget.

{
  "eventType": "LOADED",
  "date": 1702987298464,
  "locale": "en-GB",
  "merchantSlug": "example-merchant-slug",
  "url": "http://example-retail.com",
  "userId": "ebd2849-6d34-4b02-932e-1bd4d740",
  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.88 Safari/537.36",
  "instanceId": "65573e-3aa1-4d15-83f2-eaa849d65",
  "productSku": "DETAIL",
  "widgetInstance": "FEEFOWIDGET-CONTAINER-ONPAGE-PRODUCT",
  "reviewData": {
    "reviewCount": 9,
    "avgRating": 3.8
  }
}

Product Stars

The LOADED event for a product star is different from other widgets in terms of payload properties and also there will be only one LOADED event and NOT TWO. As a single LOADED event is fired for multiple Product Stars on the page, it does not make sense to have a payload with following properties hence discarded:

Reviews Data
Product SKU, and
Parent Product SKU

{
  "eventType": "LOADED",
  "date": 1702987298464,
  "locale": "en-GB",
  "merchantId": "5570c2836cdb6",
  "url": "http://example-retail.com",
  "userId": "ebd2849-6d34-4b02-932e-1bd4d740",
  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.88 Safari/537.36",
  "instanceId": "65573e-3aa1-4d15-83f2-eaa849d65",
  "widgetInstance": "FEEFOWIDGET-PRODUCT-STARS",
}

Viewed

The 'VIEWED' event is fired when a widget, except Product Stars, has been in the user's viewport for more than 5 seconds.

It’s important here to stress the consecutive nature of the trigger timer here – if the widget leaves the viewport before the timer reaches 5 seconds and then re-enters the viewport, the widget still has to remain here for >= 5 seconds before a view is counted – the timer does not continue from its previous value.

Payload

This is a set of data sent to an API when the widget is in the viewport area for 5 seconds or more after loading. The only difference between LOADING payload and VIEWED payload is the ‘eventType’.

Unlike the LOADED event, the VIEWED event is fired only once. That is one payload object for one widget on the page. The payload for a product widget will have additional ‘productSku’ property.

{
  "eventType": "VIEWED",
  "date": 1702987298464,
  "locale": "en-GB",
  "merchantSlug": "example-merchant-slug",
  "url": "http://example-retail.com",
  "userId": "ebdf2849-6d34-4b02-932e-1bd440",
  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.88 Safari/537.36",
  "instanceId": "6574573e-3aa1-4d15-83f2-eaad65",
  "productSku": "DETAIL",
  "widgetInstance": "FEEFOWIDGET-CONTAINER-ONPAGE-PRODUCT",
  "reviewData": {
    "reviewCount": 9,
    "avgRating": 3.8
  }
}

Product Stars

Like the other widget’s VIEWED event, there will be only one VIEWED event and NOT TWO. As a single VIEWED event is fired for multiple Product Stars on the page, it does not make sense to have a payload with following properties hence discarded:

Reviews Data
Product SKU, and
Parent Product SKU

How does the VIEWED event work for Product Stars?

When there is multiple Product Stars widget on the page, it finds for the first widget that is in the viewport area for more than 5 sec. Once the VIEWED event is fired, the further firing of an event is prevented.

{
  "eventType": "VIEWED",
  "date": 1702987298464,
  "locale": "en-GB",
  "merchantSlug": "example-merchant-slug",
  "url": "http://example-retail.com",
  "userId": "ebdf2849-6d34-4b02-932e-1bd440",
  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.88 Safari/537.36",
  "instanceId": "6574573e-3aa1-4d15-83f2-eaad65",
  "widgetInstance": "FEEFOWIDGET-PRODUCT-STARS",

}

Clicked

A click is specified as any click within the boundaries of the widget.

Debouncing

To minimise the tracking of spam clicks, the debounce effect is applied to each widget. The debounce effect states that a click within the widget is recorded, provided that no further click on that widget is made within the next x time. If a further click is made on the widget in that period, the initial click event is canceled. At the time of writing, the debounce period, x, is 500 ms but is subject to change.

{
  "eventType": "CLICKED",
  "date": 1702987298464,
  "locale": "en-GB",
  "merchantSlug": "example-merchant-slug",
  "url": "http://example-retail.com",
  "userId": "ebdf2849-6d34-4b02-932e-1bd4740",
  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.88 Safari/537.36",
  "instanceId": "6574573e-3aa1-4d15-83f2-eaa89d65",
  "productSku": "DETAIL",
  "widgetInstance": "FEEFOWIDGET-CONTAINER-ONPAGE-PRODUCT",
  "context": {
    "targetElement": "DIV",
    "targetClass": ".feefowidget-viewport-wrapper",
    "clickType": "Newest/Popular Tabs"
  },
  "reviewData": {
    "reviewCount": 9,
    "avgRating": 3.8
  }
}

This example includes additional context information about the clicked element.

Conclusion

By implementing the event tracking listener and understanding the payloads and event types, you can gain valuable insights into user interactions with Feefo widgets on your website. Feel free to customise the integration to meet your specific needs, and always refer to this guide for the most up-to-date information on Feefo event tracking.

Event Tracking

Modified on: Thu, 11 Jan, 2024 at 3:53 PM