TABLE OF CONTENTS


Introduction

Welcome to Feefo's comprehensive guide, tailored to enhance your customer insights through effective widget interaction tracking. Understanding how customers interact with our widgets on your site is crucial for optimising user engagement and experience. To facilitate this, we have developed a sophisticated tracking system that not only captures essential interactions like load, view, and click events but also can integrates effortlessly with your analytics tools, such as Google Analytics. This integration provides a richer, more detailed understanding of customer behaviours and preferences.

In this guide, we'll cover:

  1. Effortless Integration: Step-by-step instructions to embed our tracking in your system.
  2. Tracking Payloads Detail: A breakdown of the data captured for each widget interaction.
  3. Event-Specific Insights: Deep dive into the nuances of load, view, and click events, helping you extract maximum value from these insights.

Our objective is to equip you with in-depth, actionable data that can significantly enhance your customer engagement strategies. Let’s dive into the implementation details.


Setup

Example Widget Implementation with Google Analytics Integration

Below is a sample implementation of a Feefo widget for a merchant with the slug 'example-id'. This code snippet includes event listening for Feefo widget interactions and demonstrates how to log these events to the console and push them to Google Analytics.

<html>
<head>
    <script async type="text/javascript" src="https://api.feefo.com/api/javascript/example-id"></script>
    <script>
        document.addEventListener('feefo_widgetTracking', (event) => {
            // Console log the data for debugging
            console.log(event.detail);

            // Pushing event data to Google Analytics
            if (window.dataLayer) {
                window.dataLayer.push({
                    'event': 'feefo_interaction',
                    'category': 'Feefo Widget',
                    'action': event.detail.action, // e.g., 'loaded', 'viewed', 'clicked'
                    'label': event.detail.label // additional details about the interaction
                });
            }
        });
    </script>
</head>
<body>
    <div id="feefo-product-review-widgetId" data-parent-product-sku="123456"></div>
</body>
</html>

This code ensures that every interaction with the Feefo widget is not only logged for internal review but also sent to Google Analytics. 


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:


PayloadDescriptionTypeValue
LocaleDefault languageStringen-gb
merchantSlugThe merchant identifierStringexample-id
urlThe URL where the event was firedStringhttp://www.example.com/
path/to/widget
userIdUser ID: Unique Session Identifier (UUID)Stringebd2849-6d34-4b02-932e-1bd4d740
userAgentInformation about application, OS, and versionStringMozilla/5.0 (Macintosh; Intel Mac OS X 10_14_4)…
instanceIdInstance ID for all event types per user sessionString65573e-3aa1-4d15-83f2-eaa849d65
dateTime of the event as a UNIX timestampInteger1702987298464
eventTypeType of event: LOADED, VIEWED, CLICKEDStringLOADED, VIEWED, CLICKED
widgetInstanceThe instance of the widget that the event occurred onStringFEEFOWIDGET-PRODUCT-STARS
productSku / parentSkuAvailable only for Product Widget InstanceStringDETAIL
reviewDataAn object containing the review count along with the average rating for the related product.Object {
reviewCount: number, avgRating: number,
}
{
reviewCount: 10,
avgRating: 1.8,
}
qaaDataAn 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.


PayloadDescriptionTypeValue
targetElementThe clicked element typeStringDIV / A / SPAN etc
targetClassThe classname of the element that was clicked on, if presentString'.feefo-classname'
clickTypeName given for the target sectionStringFilters / 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 AreaTarget Name
1Undesignated area anywhere in the widget that is not listed below.General
2All Ratings or Filter iconFilter
3Newest or Popular TabsTabs
4Pagination ItemsPagination
5Read all Reviews linkRead reviews Link

Media Integration


CLICK events for Media Integration explained


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


A screenshot of a website

Description automatically generated



Click areas for carousels explained


Target Area #Target AreaTarget Name
1Undesignated area anywhere in the widget that is not listed below.General
2Read all reviews linkRead Review Link
3Carousel indicator to change the reviewCarousel Indicators
4Carousel right arrowRight Arrow
5Carousel left arrowLeft Arrow


A screenshot of a computer screen

Description automatically generated


Floating Widget


Click events for the Floating Widget explained.


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


A screenshot of a test

Description automatically generated


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 SKUParent Product SKUPayload contains
YesNoProduct SKU
YesYesProduct SKU
NoYesParent Product SKU


Widget IDs (widgetInstance)


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:

  1. Payload with reviews data
  2. 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-id",
"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",
"merchantSlug": "example-id",
"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-id",
"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-id",
"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-id",
"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.