Tagging Locations
Now that the Tracker is up and running we can start thinking about Tagging some Elements as LocationContexts using Location Taggers.
If you want to know why we ask you to tag your elements, take a look at the Core Concepts Introduction.
Tagging Interactive Elements
A good rule of thumb is to start by identifying all interactive Elements in the Application.
Buttons
Anything that the user can interact with, but does not cause a URL change, can be considered a Button.
// a button tag
<button {...tagPressable({ id: 'button-1' })}>Click Me!</button>
// a Button component
<Button {...tagPressable({ id: 'button-2' })}>Do It!</Button>
// a clickable image
<img {...tagPressable({ id: 'button-3' })} src="/img/ok.png" alt="OK!" />
Links
Links are interactive elements that cause, directly or indirectly, a change in the current URL.
// a link tag
<a {...tagLink({ id: 'link-1', href:"/somewhere" })} href="/somewhere">Go!</a>
// a Link component
<Link {...tagLink({ id: 'link-2', href:"/cart" })} to="/cart">Back</Link>
Currently it's necessary to specify href
manually. We are working on improvements to make this
easier.
Expandables
Elements that cause other Elements, usually their children, to be expanded and displayed to the user, such as Accordions and collapsible Menus.
// an Accordion-like component
<FAQItem {...tagExpandable({ id: 'how-to-1' })} description="How to track Accordions?">
Some content here that will be displayed on click
</FAQItem>
// a contextual Menu
<Menu {...tagExpandable({ id: 'main-menu' })}>
<MenuItem>Menu A</MenuItem>
...
<MenuItem>Menu Z</MenuItem>
</Menu>
Tracking Locations
To make modeling easier it's important to ensure all Tracked interactive Elements are uniquely identifiable.
That said, assigning a unique identifier to each Element is not always possible and most often impractical. Think of reusable components for example.
See Core Concepts - Locations for an explanation of how Sections can be tagged to make Events unique without having to assign a unique idenitifier to each.
An example for React:
<Layout {...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>
<div {...tagContent({ id: 'section2' })}>
<a {...tagLink({ id: 'my-link', href: '/link2' })} href="/link2">Link 2</a>
</div>
</header>
</Layout>
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.
Tagging Sections can/should also be applied to pages/screens, see section Applying Locations to pages/screens below.
Solving collisions
See below for a simplified example taken from our website's About page, which lists the contributors to Objectiv. It renders a link to each Contributor's profile:
function Contributor({name, gitHubUsername}) {
const ghProfileLink = "https://github.com/" + gitHubUsername;
return (
<div {...tagContent({id: 'contributor'})}>
<Link
{...tagLink({id: gitHubUsername, href: ghProfileLink})}
href={ghProfileLink}>
@{gitHubUsername}
</Link>
</div>
);
}
export default function Contributors() {
return (
<Layout>
// `contributors` is retrieved from a JSON file
{contributors && contributors.length > 0 && (
<div {...tagContent({id: 'contributors'})}>
{contributors.map((props, idx) => (
<Contributor key={idx} {...props} />
))}
</div>
)}
</Layout>
);
}
As you can see, each contributor <div>
has the same id
, 'contributor'. This will result in collisions in
the Location Stack, and the browser console will show a warning about the colliding elements:
How to fix this?
- You could remove the
<div>
with the 'contributor'<id>
. But it probably serves a purpose. - Or: you could change the
id
to be unique, e.g. every contributor's GitHub username.
We will use the second option, making each contributor <div>
ID unique:
<div {...tagContent({id: gitHubUsername})}>
instead of
<div {...tagContent({id: 'contributor'})}>
Applying Locations manually
Sometimes it may be preferable, or necessary, to tag Locations manually; for these cases, a low-level tagLocation API is available, which tags a Taggable Element to be tracked as any LocationContext.