Overlay slot tracking customization

The Overlay bookmarklet’s slot tracking configuration works when all compared-slots have the same slot-ID and the same X-Path. Static websites that do have structural variance are no problem. We’ll be able to track slot performance without issue as long as the relevant slots have the same X-Path.

But this breaks down when a site has multiple configurations and different content within each configuration. The following sections will break down the most common use cases that we at Parse.ly have found for our Overlay.

How Parse.ly tracks slot performance

With Slot Tracking, Parse.ly monitors the exact location on a page that a user clicks. 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. It retrieves traffic data from our servers and matches each element with the stored XPath.

When using Slot Tracking, we treat link URLs 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.

Defining slots with data-parsely-slot attributes

To ensure historical slot accuracy, it’s important to define slots so that link XPaths remain stable and consistent over time.

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, consistency of internal structure is important. For example, if a widget always has a list of ten stories, it’s fine to define a single slot. But if the list occasionally contains an additional element, 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, e.g., a thumbnail and headline. 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]. On 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.