why tagging?

If you want to know why we ask you to tag your elements, take a look at the Core Concepts Introduction.

To understand tagging, we first need to know what we mean by Elements.


When talking about Elements we usually refer to DOM Interfaces and APIs such as Nodes / Elements and EventTargets.

Taggable Elements

Taggable Elements are HTMLElements and SVGElements, which are implementations of the beforementioned Elements.

Examples are a <div> or an <a> element in HTML.

Tagging of Elements

Location Taggers are used to tag any Element that you want to track. The Tracker then uses this information to automatically decorate the Element in the DOM with the respective BrowserTracker:TaggingAttributes.

A tagging example in React:

[tagLink]="{ id: 'lnk-id', href: '/path' }"

...would result in something like the following decorated attributes:

data-objectiv-element-id="<a unique identifier>"
data-objectiv-context="<stringified location context>"

When the Tracker wants to send an Event related to an Element (e.g. a click), it uses its decorated BrowserTracker:TaggingAttributes to compose the Event.

Tagging Content

You can tag logical sections in your application's UI (e.g. the hero element on a homepage) using tagContent. This binds a ContentContext to it.

This might seem without benefit, as no Events are triggered (by default) on tagged sections. However, tagging Elements is useful in two main ways:

  1. When any Event triggers, a hierarchical Location Stack is generated for it, including all the sections it originated from. When analyzing the resulting data, you can fully understand where every Event came from.
  2. Every Event becomes unique (see next section about collisions).

An example of tagging sections and Links in your UI:

 <section [tagContent]="{ id: 'layout' }">
<header [tagContent]="{ id: 'homepage-hero' }">
<div [tagContent]="{ id: 'section1' }">
<a [tagLink]="{ id: 'my-link', href: '/link1' }" href="/link1">Link 1</a>
<div [tagContent]="{ id: 'section2' }">
<a [tagLink]="{ id: 'my-link', href: '/link2' }" href="/link2">Link 2</a>

As you can see, there are two links with the same ID (my-link). However, as they are contained within different tagged Sections, they are still unique, and when analyzing the data, you can follow the Location Stack to understand where in the UI each Event originated.

Tagged Elements

These are Taggable Elements that have been already decorated by the Objectiv Tracker with at least the elementId and context BrowserTracker:TaggingAttributes. The Tagging Attributes supply the Tracker with the information needed to compose & send the right Events.

Children Tagging Elements

These are Taggable Elements that have been already decorated with the BrowserTracker:TaggingAttribute.tagChildren by using the tagChildren Location Tagger. They will execute the given BrowserTracker:ChildrenTaggingQueries, at runtime, and tag matching children Elements.

BrowserTracker:ChildrenTaggingQuery objects are composed of a CSS Selector query and a set of TaggingAttributes. Each matching Element will be decorated with the given Location Tagger result.

A tagChildren example:

queryAll: 'button[aria-label=&quot;Previous&quot;]',
tagAs: tagPressable({ id: 'prev' })
queryAll: 'button[aria-label=&quot;Next&quot;]',
tagAs: tagPressable({ id: 'next' })

The div Element above has been decorated with a ChildrenTaggingQuery. It will execute the given queryAll and apply the result of the tagPressable parameter to any matching child Element.