Overlay: Technical Overview

The Parse.ly Overlay allows editors to quickly understand the performance of links on homepages and landing pages. It also provides historical comparisons for particular page positions (“slots”), so that it’s easy to see whether a given link is doing better or worse than previous links in the same position.

How Parse.ly tracks slot performance

When slot tracking is enabled, Parse.ly monitors the exact location on a homepage or index page that a user clicks to get to a post page (see Distinguishing between “posts” and “pages” to understand how Parse.ly categorizes webpages). When a click occurs, the Parse.ly tracker determines the link’s XPath and stores it in the browser. Then, when the target page loads, the Parsely tracker on that page reads the stored XPath and includes it in the slot data sent with its first pageview event.

The Overlay bookmarklet then creates badges in your browser by doing the reverse: retrieving traffic data from our servers and matching each element on the page with the XPath that was stored on click, along with traffic data for that post URL.

With slot tracking enabled, link URLs are treated as referrers for their target pages. For example, clicking a link on a page http://examplesite.com/home with the target href="http://examplesite.com/feature1" tells the Parsely tracker that the pageview event sent from /feature1 should have /home as its referring URL.

Technical Caveats

Slots tracking works best for customers with high traffic to their homepage or index pages. High traffic means multiple clicks through multiple slots within any given 10-minute window.

Please note that Slots data is not designed to work for the following cases:

• When a slot receives fewer than 1 click within the last 10 minutes.
• Slots linking to Non-posts (click here to see how Parse.ly distinguishes between Posts and Non-posts).
• Slots linking to external sites, i.e., sites that do not share the same SiteID.

Defining slots with data-parsely-slot attributes

To ensure that historical slot comparisons are accurate, it’s important to define slots so that link XPaths remain stable and consistent over time, regardless of the content they contain or the presence of other transient page elements (such as ad units, consent modals, etc.).

To illustrate how to add the necessary markup to an existing page, let’s consider this simplified example:

<section id="hero">
	<div>
		<article>
			<a href="/feature/1"><img src="/photo1"></a>
			<div>
				<a href="/feature/1"><h2>Main Story Headline</h2></a>
				<p>A small description</p>
			</div>
			<ul>
				<li><a href="/feature/2"><h3>Related Story 1</h3></a></li>
				<li><a href="/feature/3"><h3>Related Story 2</h3></a></li>
			</ul>
		</article>
	</div>
</section>
<section id="list-1">
	<ul>
		<li><a href="/news/1"><h2>News Headline 1</h2></a></li>
		<li><a href="/news/2"><h2>News Headline 2</h2></a></li>
		<li><a href="/feature/1"><h2>Main Story Headline</h2></a></li>
	</ul>
</section>

To define a slot, add a data-parsely-slot attribute with a unique value to a semantically appropriate DOM element. The XPath will be calculated by traversing upwards through the parent elements of the clicked link until an element with a defined data-parsely-slot value is found (or the top of the document is reached).

While it’s not necessary to define a slot for each link on the page, it is important that the internal structure of each slot is consistent. For example, if a widget always has a list of ten stories with links, it’s fine to define a single slot at the list level. But if the list occasionally contains an additional list element with an ad, then it’s better to define each slot at the list-element level.

For the example above, it might be sufficient to add the attribute to just a couple elements:

<section id="hero">
	<div>
		<article data-parsely-slot="feature-story-1">
			<a href="/feature/1"><img src="/photo1"></a>
			<div>
				<a href="/feature/1"><h2>Main Story Headline</h2></a>
				<p>A small description</p>
			</div>
			<ul>
				<li><a href="/feature/2"><h3>Related Story 1</h3></a></li>
				<li><a href="/feature/3"><h3>Related Story 2</h3></a></li>
			</ul>
		</article>
	</div>
</section>
<section id="list-1">
	<ul data-parsely-slot="latest-news-list">
		<li><a href="/news/1"><h2>News Headline 1</h2></a></li>
		<li><a href="/news/2"><h2>News Headline 2</h2></a></li>
		<li><a href="/feature/1"><h2>Main Story Headline</h2></a></li>
	</ul>
</section>

All data-parsely-slot values on a page should be unique, just as if you were defining id attributes. It’s also useful to use semantically meaningful values, as we have above.

Slot grouping

There are often multiple link elements that point to the same target page (for example, a thumbnail and headline that both link to an article). As long as the href attribute of these links is exactly the same, and the links share the same data-parsely-slot ancestor, the Parse.ly Overlay will combine their data into a single, aggregated slot.

In the example above, there are two links in the feature-story-1 slot that point to /feature/1. While they have different XPaths ( //*[@data-parsely-slot="feature-story-1"]/a[1] and //*[@data-parsely-slot="feature-story-1"]/div[1]/a[1], respectively), because they share the same data-parsely-slot ancestor, they will be grouped together. But the link nested in latest-news-list will not be grouped, even though it points to the same page.

Default Behavior

When there are no page elements with data-parsely-slot attributes, the tracker will instead calculate XPaths by traversing up the DOM tree from the clicked link until it finds the first element with an id attribute (or it reaches the top). In the initial example above, the Xpath for the first link would be //*[@id="hero"]/div[1]/article[1]/a[1]. In a real webpage, with many deeply nested elements, these XPaths can become long and brittle, depending on where id attributes are used.

In this default mode, if two links have the exact same href attribute and have bounding rectangles in close physical proximity, their data will be aggregated into a single slot.