Reminder: When the main tag has loaded, our tool will collect and transmit most interactions happening on the page: hovers and clicks will thus be treated to give you UX indicators on elements composing the page.
Events handling - General principlesSection titled Events handling - General principles
SetupSection titled Setup
Events are automatically and systematically collected as soon as:
- The main tag has loaded,
- That the web user has been included in the analysis,
- And the content is loaded (
Collected eventsSection titled Collected events
The main Tag collects the following events:
- Clicks —
tapon all elements
- Hovers —
- Focus —
- Resize —
- Mouse moves —
pointermoveon all elements
It associates every element to a timestamp and a page block (meaning an HTML marker).
How is the marker identifiedSection titled How is the marker identified
To target a block in the DOM, our tool reads through all parents chain of the element until finding the first marker with an id (if it has not been ignored, see below). If no IDs are found in the parent chain, it goes up to the
<html> tag. It then goes back down counting the position of the tag within identical markers each time.
Elements taken into account for targeting are underlined.
In these two examples, the two highlighted blocks will be identified as identical, and interaction data will be assimilated.
Ignored “id”sSection titled Ignored “id”s
Multiple occurrences of the same IDSection titled Multiple occurrences of the same ID
The Tracking Tag applies the W3C spec: “id must be unique per webpage DOM tree”. If an ID is not unique, the tag will ignore all its occurrences.
Multiple IDs for the blockSection titled Multiple IDs for the block
Some websites use dynamic ids of which the value changes according to the pages within just one template. This stops us from combining data on those elements in the application.
Also, markers that we want to analyze separately can be placed under the same “id”.
To answer those two issues, we exclude:
- Ids with 4 consecutive digits,
- Elements with a
data-cs-override-idattribute with an empty value (see paragraph below),
Elements taken into account for targeting are underlined.
On this example, the id “product2134” is ignored; its parent will be considered instead.
div#products2134>p>img=> does not allow data combination
Target with dynamic id detected:
div#wrap>div>p>img=> allows data combination
Ignore, override or add an “id”Section titled Ignore, override or add an “id”
If you need to differentiate a block among others in the solution, you can define an ID that will be use by our tracking events mechanism.
Just use the
data-cs-override-id attribute, with a valid ID value (authorized characters are
_). Make sure this value is static and doesn’t change from one URL to another (no dynamic ID).
This attribute can be added to any HTML tag:
<a>, and so on.
It must be added to the HTML code, either in the original code or after the “DOM Ready” (
You can also signify that an ID must be ignored because the ID differentiates blocks when they are, however, of the same nature.
Get Page height and Scroll Rate on a specific HTML elementSection titled Get Page height and Scroll Rate on a specific HTML element
The Tracking Tag listens to scroll events on the document and get the document height to compute Page height, Scroll Rate and Zone Exposure metrics. These metrics will be wrong on pages for which:
- The document height equals the window height
- And the scroll is happening within a HTML element with a height bigger than the document.
In order to get accurate metrics, add the
data-cs-scroll-container attribute to the specific HTML element handling the scroll events. It can be added to the original HTML code or after the “DOM Ready” (
When binding event handlers, the Tracking Tag will detect the presence of an element in the DOM with the attribute
data-cs-scroll-container. If such element is found, the Tracking Tag will not listen to the scroll events and page height on document anymore, but on that specific HTML element instead. It will use its height (and its
padding-top) to compute the page height, scroll rate and exposure metrics.
Which HTML code is compatible?Section titled Which HTML code is compatible?
The solution is made to work on all “normally” developed websites. Here are some rules; they are for the most part derived from standard development.
Start each page with the DOCTYPE
Use only one “id” per page, to designate a functional block.
If an id or a class contains more than one word, use valid separators (
_) or camel case: use
Do not use random “id” or “id” that can change according to the contents or sessions.
Use valid “id”: no space, no “quote”.
Use a consistent hierarchy of information: within the same tag, only put elements of the same nature.
❌ Do not write
✅ Rather write
Close every opened tags; do not close the parent element’s tag before closing the children.
To facilitate the sending of “pageviews”, it is advisable to change the URL with every major UI update.
Verifying the sending of eventsSection titled Verifying the sending of events
Storage and performanceSection titled Storage and performance
So as not to alter display performances, interactions are not sent bit by bit. We stock all interactions in memory on the web user’s browser and then send the collected events by packets.
Sent requestSection titled Sent request
You will regularly notice GET requests to
//c.contentsquare.net/events which will be sent to an encoded version of the latest events.
Event requests are sent when:
- The number of events in memory reaches 50
- The page is reloaded
- The user “leaves” the page by either being redirected to another page, closing/switching tab, closing browser, switching to another app, lock screen, etc. (triggers may vary depending on browsers and device type)