Title: Overlay slot tracking customization
Author: bethurban
Published: July 17, 2025
Last modified: November 26, 2025

---

 1. [Installation resources](https://docs.parse.ly/installation-resources/)
 2. [Add-on Features](https://docs.parse.ly/installation-resources/add-on-features/)
 3. Overlay slot tracking customization

#  Overlay slot tracking customization

The [Overlay bookmarklet’s](https://docs.parse.ly/tools-features/overlay/) 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](https://developer.mozilla.org/en-US/docs/Web/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:

    ```lang-php
    <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:

    ```lang-php
    <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.

Last updated: November 26, 2025