API Reference

Widget Events

By default, we send the following events to query.petametrics.com/__activity.gif associated with each widget rendering. Note that, with the exception of widget_response, these events are sent only if you have set up tracking correctly.

  • widget_response: This event is sent when we receive recommendations from LiftIgniter's query server, confirming the list of recommendations we have received and that we plan to render. Note that this will get sent only in LiftIgniter's slice where you are requesting recommendations, and will not get sent in the base slice. It is also independent of your tracking implementation, so it works even if you have not enabled tracking.
  • widget_shown: This event is sent when the widget has rendered and the track functionality is called on it.
  • widget_visible: This event is sent when the widget enters the user's viewport. If the widget is in the viewport at the time it finishes rendering, the event is triggered immediately. Otherwise, it is triggered when the user scrolls to the item.
  • widget_click: This event is triggered when the user clicks (either a left-click or a right-click) on one of the recommended items.

📘

Assumed familiarity with console debugging and event-sending

This page builds on information in the Console Debugging and Pageview and Heartbeat Events sections. You may need to read through those sections if some of the information presented here is unclear to you.

The page also makes more sense after you have read the documentation on Rendering Widgets and Tracking Widgets.

1. Understand what's getting sent

See Section 1 of the Pageview and Heartbeat Events page for details on the fields that get sent by default with most activities.

Additionally, widget events have the following additional fields:

  • vi (stands for visibleItems): This is the list of all the visible items in the recommendation section. This includes all items that match the selector inside the widget area. All widget events associated with a given rendered widget should have the same value of vi. Note that the set of visible items should ideally match with the inventory items being recommended, but it is possible to have additional visible items (such as links to author or section pages that render within the widget). If you have a situation where the anchor link differs from the inventory item being recommended, please get in touch with Support. If you do not have anchors, see the Tracking with no Anchor section.
  • w (stands for widgetName): This is the name of the widget being rendered. It should match the same you use in your register and track calls.
  • source: This describes the A/B test slice. If LiftIgniter's recommendations are used, this should be set to "LI", otherwise it should be set to "base". This value should match the value you set in your track call.

The widget_click event has the following additional fields:

  • clickUrl for the URL that was clicked
  • trigger describes the trigger for the click. It can take two values: click (for a left click) and contextmenu (for a right click).

2. Check that the events are being sent correctly

You can filter in the Network panel for petametrics, load your page, and have it render and track the recommendations. You should check that:

  • The widget_shown,widget_visible, and widget_click events are sent as expected based on their descriptions. For the widget_click event, when testing the left click, you may need to use the Preserve Log function in the Chrome Network Panel in order to capture events across pageviews.
  • The vi, w, and source field values are correctly set for these events.
  • The clickUrl and trigger values are set correctly for the widget_click event.
  • There are no console log messages with warnings from LiftIgniter.

3. Report response errors

If you encouter any trouble or puzzling behavior when debugging, contact Support. In your email, include as much detail as possible about the error.