Events handling

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 principles

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 (DOMContentLoaded event).

Collected events

The main Tag collects the following events:

Clicks — click, pointerdown, pointerup, tap on all elements
Hovers — mouseover, mouseout on <a>, <button>, <select>, <input>, <textarea> elements
Focus — focus, blur, change on <input>, <textarea>, <select> elements
Resize — window.resize
Mouse moves — scroll, pointermove on all elements

It associates every element to a timestamp and a page block (meaning an HTML marker).

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”s

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 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-id attribute 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.

Original target: 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”

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 a to z, A to Z, 0 to 9, - and _). 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: <div>, <p>, <form>, <a>, and so on.

It must be added to the HTML code, either in the original code or after the “DOM Ready” (DOMContentLoaded) event in JavaScript.

<div class="cta"></div>
<div class="main_cta" data-cs-override-id="main_cta"></div>
<div class="cta"></div>
<div class="cta"></div>

You can also signify that an ID must be ignored because the ID differentiates blocks when they are, however, of the same nature.

<div class="product"></div>
<div class="product" id="<IDENTIFIER_TO_IGNORE>" data-cs-override-id></div>
<div class="product"></div>
<div class="product"></div>

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” (DOMContentLoaded) event in JavaScript.

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.

<html>
  <head>...</head>
  <body>
    <div>...</div>
    <div class="main">
      <div class="scrollable" data-cs-scroll-container>...</div>
    </div>
  </body>
</html>

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 <!DOCTYPE html>.
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 addToCart or add-to-cart instead of addtocart and addtoCart.
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	`<div class="category"> <div class="product"></div> <div class="product"></div> <div class="product"></div> <div class="paging"></div> </div>`
✅ Rather write	`<div class="category"> <div class="list"> <div class="product"></div> <div class="product"></div> <div class="product"></div> </div> <div class="paging"></div> </div>`

❌ Do not write

<div class="category">
  <div class="product"></div>
  <div class="product"></div>
  <div class="product"></div>
  <div class="paging"></div>
</div>

✅ Rather write

<div class="category">
  <div class="list">
    <div class="product"></div>
    <div class="product"></div>
    <div class="product"></div>
  </div>
  <div class="paging"></div>
</div>

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 events

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 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)