How the Overlay bookmarklet tracks slot performance

The Overlay bookmarklet allows you to track the performance of posts on your homepage or section pages. It shows historical performance for particular page positions (“slots”), so you can see if an article is doing better or worse than the slot’s average.

How the Overlay bookmarklet tracks slot performance

Overlay tracks slot performance by monitoring the exact location on a page that a reader clicks to get to an article. When a click occurs, Overlay determines the path of the link that’s been clicked—that is, its position on the page relative to other HTML elements—and sends a ping to servers to store it.

The bookmarklet then creates badges in your browser by doing the reverse: retrieving traffic data from our servers and matching an element on the page with the path that was stored on click (shown on the left, below), along with traffic data for that article URL (shown on the right).

Best practices

For best results using Overlay, we recommend the following:

1. Use Google Chrome

2. Turn off ad-blocking extensions like AdBlock or Ghostery

They may  interfere with the Overlay bookmarklet script and cause Overlay not to function.

3. Modify your HTML template

The Overlay bookmarklet may require changes to your HTML templates to function properly.

To determine an article’s slot location on your homepage, Overlay starts from the clicked element and traverses up the DOM tree until it finds either a container element with an ID attribute specified, or until it reaches the top. In cases where there’s no ID, Overlay counts from the top, so a path could end up looking something like “/div[1]/div[5]/article[2]/a”; that is, “Take the first div element, then the fifth div inside it, and then the link inside the second article element.”

In some situations, the process breaks down and Overlay fails to display badges and/or historical data properly. This can occur when:

  • A reader with an ad blocker enabled clicks on an article. Ad blockers often remove HTML elements containing advertisements entirely, so the page structure changes and a path relying on a specific element order will break.
  • Publication of a new article significantly changes the page structure; for example, if you have a breaking news module in your CMS that pushes other stories into new positions further down the page.
  • Your homepage displays different variants to different readers; for example, logged in vs. non-logged in, or desktop vs. mobile.
  • Your CMS creates new container IDs every time a new article is displayed in a slot; for example, IDs based on article URL, or random hashes generated by an A/B testing module.

If you face these problems, the best way to address them is to add divs to your homepage markup corresponding to specific locations, such as “slot-1”, “slot-2”, etc. These divs should wrap the links to your articles, and should be nested within any other container elements around the article that use IDs, as in this example:

overlay slot html

Overlay can then use those IDs and attribute slot data to them over time, rather than traversing a DOM tree that may change structure when new articles appear on the page. Adding this kind of markup to your homepage will give you the best results from Overlay. You can check the xpath that the overlay is using to track a link by right-clicking on it, choosing “Inspect”, and then typing window.ParselyOverlay.getElementXPath($0) in your browser console.

Do you have an urgent support question?