Tracking widget performance is the most important part of the LiftIgniter integration. There are three events that make up widget tracking:
- widget_shown: Were the recommendations loaded on the page?
- widget_visible: Did the user scroll the recommendations into their viewport?
- widget_click: Which item in the recommendations did the user click on?
Our Javascript SDK takes care of capturing all of these events when the $p("track") function is invoked. This function tags all of the URLs in the recommendation area with event listeners and query strings so that each of the events above can be detected.
In an API integration, the developer will need to include code for detecting these events and reporting them to our /activity endpoint. This article will discuss tracking primarily using our Javascript SDK for examples.
Invoking $p("track")
In the code example below, you'll notice that the "track" function is invoked in the callback of $p("register") and after $p("render"). This is because all of the elements in the recommendation area need to be loaded on the page in order for the track function to tag the correct items. If you are using dynamic page loading extensively, race conditions can sometimes allow tracking to be applied to the baseline or fallback items that are being overwritten in the A|B test, instead of to the item that LiftIgniter recommended and that was displayed to the user. We'll go over some common issues like this and how to identify them in the "Verifying Tracking Accuracy" section below.
$p('register', {
max: 6, // Number of items you want to show
widget: 'my-widget-name',
callback: function(resp) {
var el = document.querySelector('#li-recommendation-unit');
var template = document.querySelector('#li-recommendation-template').innerHTML;
el.innerHTML = $p('render', template, resp);
$p('track', {
elements: document.querySelectorAll('#li-recommendation-unit > div.recommended_item'),
name: 'my-widget-name',
source: 'LI'
});
}
});Notes on function arguments:
$p('track', {
elements: document.querySelectorAll('#li-recommendation-unit > div.recommended_item'),
name: 'my-widget-name',
source: 'LI',
_debug: true
}- elements: An array of the DOM elements that should be tracked. The selector should be the entire DOM element corresponding to a particular recommendation. In the example above, the Mustache.js template uses #li-recommendation-unit for the widget area and 'div.recommended_item’ to identify each item within the area.
- name: Name of the widget being tracked (this should match the name set in the $p("register") "widget" argument).
- source: Name of algorithm active during this impression. Please use ‘LI’ for LiftIgniter. In an A|B test, you can use a variable name here and define which algorithm ('base' or 'LI') is being used to generate the recommendations.
- _debug: Optional, for help with testing. When set to "true", browser alerts will appear for visible and click events on elements being tracked. Make sure to remove or set to "false" before pushing your code to production!
Using _Debug
If _debug is set to true, you should see the following in your browser:
- When the items being rendered first enter the viewport, you should see an alert pop up saying something like "visible for default-widget:LI". This means that an event was triggered telling the LiftIgniter system that the items entered the viewport.
- If you click on any of the recommended items, you should see an alert pop up saying something like "click for default-widget:LI". This means that an event was triggered telling LiftIgniter that the user clicked on the recommendation. To make debugging easier, we recommend right-clicking so that you do not accidentally navigate away from the page.
- You can see the exact events that are being sent to LiftIgniter by going to your Network Panel in Chrome Developer Tools and filtering to petametrics.com. This will include both the widget-specific events and pageview and heartbeat events. For more background, see the Widget Events page, which builds on some other pages in the web debugging section.
Make sure _debug is set to false or removed before implementing in production.
Verifying Tracking Accuracy
Using the _debug argument in development environments will help ensure events are triggering successfully. However, we also need to check that the right values are being sent for each event. Below is a quick checklist for each of the widget events you'll be seeing in the Dev Tools Network log.
Widget_shown and widget_visible
- Only one widget_shown and at least one widget_visible event is fired for each widget on the page
- The visibleItems (vi) parameter in each widget_shown and widget_visible event contains the correct URLs for all of the items displayed
- Check the list of visible items is the same as the list returned by LiftIgniter in the "widget_response", and are displayed in the same rank order (the highest ranked item should be in the first/most visible space in the widget area)
- If only a few of the items are visible at a time (such as in a carousel or paginated display) make sure that widget_visible contains only the items actually visible to the user. Additional widget_visible events can be triggered as the user scrolls through additional items. Please contact Support if you have any trouble with this!
- If you see the widget_visible and widget_click events, but do not see our tags (&li_source=LI&li_medium=<widget-name>) in the URL after you clicked to it, this may be because your site automatically rewrites or strips off tags. This is not a problem for our tracking or for training our algorithms, but it will make third-party verification of the numbers harder and means that some of the analytics we compute won’t be available (such as calculating the rate of a second widget click in a session).
Widget_click
- Make sure only one widget_click event is sent when an item is clicked. Multiple click events usually mean the "track" function has been applied multiple times to the same DOM element. This can happen in single-page web applications or other setups where page content is updated or replaced dynamically.
- Make sure the "cu" and "ccu" value for the click event is the URL of the page where the widget is displayed. "cu" is the current URL - this may have query strings included, and should exactly match the URL displayed in the browser window. The "ccu" is the current canonical URL and should have only the base URL with no query strings included.
- The "clickUrl" value should be the URL of the item that was clicked on.
- If you are using any on-click overrides, this can cause our click tracking to fail! Make sure that every link goes to the intended recommendation rather than the baseline recommendations or looping back to the current page.