Skip to main content
A tracker counts clicks on one HTML element: a button, a link, or a form control. GrainQL Tag reads the tracker definitions of your workspace and sends one event for each click. You create a tracker in the dashboard, with the Visual Picker on your site or in Studio. You do not need to change your site.

​
The event that a tracker sends

GrainQL Tag names the event after the tracker. It changes the name to lowercase and replaces each space with an underscore. A tracker named “Signup Button” sends signup_button. The event shows on the Events page under its name, next to the events that your code sends. To make a click count as a conversion, open the event on the Events page and turn on Counts as a conversion. Mission Control, Campaigns, Overview, Sessions, and Neo then count it. Read Mission Control.

​
Create a tracker with the Visual Picker

The Visual Picker opens your site in a new tab, on top of the live page. GrainQL Tag must be installed on the site.
1

Open Events

In the dashboard sidebar, click Events. Then click Track an event.
2

Choose a click

Choose A click on your site.
3

Open your site

Enter the address of your site, for example example.com. For a local site, add the port. Then click Open the Visual Picker.
4

Click the element

In the new tab, click the element. Enter the event name and confirm. The Visual Picker suggests a name such as signup-btn_click.
The Visual Picker stores the XPath of the element and a fingerprint of the element. It creates a metric tracker with the URL scope contains and the URL of the current page as the pattern.

​
Create a tracker in Studio

Studio is a page of the dashboard. It shows a snapshot of each page of your site, with the trackers on it.
1

Open Studio

In the dashboard sidebar, under Engage, click Studio.
2

Choose a page

In the Pages pane, choose the page. Studio shows its snapshot.
3

Add the tracker

Open the Beans pane. Click Add and enter a CSS selector, for example #signup-btn. Or click Pick element from snapshot, then click the element. Studio fills in its XPath.
4

Name and save

Enter a name, choose Metric or Conversion, and set the URL scope. Then save.
Studio needs page snapshots. If a page has no snapshot, turn on heatmap capture. Read Heatmaps.

​
URL scope

The URL scope limits the pages where a tracker is active. GrainQL Tag normalizes the page URL and the pattern before it compares them. It removes the protocol, www., the query string, and the fragment, and it adds a trailing slash. As a result, https://www.example.com/pricing?ref=ad and example.com/pricing/ are the same URL. An equals pattern must hold the domain, because the page URL holds it. The pattern /checkout never equals example.com/checkout/. A pattern of / alone, or an empty pattern, matches every page.
The TrackerDefinition type of @grainql/tag also accepts prefix. The dashboard and the GrainQL API store only all, contains, and equals.

​
What a tracker stores

​
How GrainQL Tag runs trackers

  1. On page load, GrainQL Tag fetches the tracker definitions of your workspace from the GrainQL API.
  2. For each enabled tracker whose URL scope matches the page, it finds the element and attaches a click listener. It tries the stored fingerprint first and falls back to the CSS or XPath selector.
  3. GrainQL Tag watches the page for DOM changes. When a matching element appears, for example after a client-side navigation, it attaches the listener again.
  4. When a click on a link starts a navigation, GrainQL Tag sends the event at once.
The full definition is the TrackerDefinition type in @grainql/tag. When this page and the type disagree, the type wins.

​
Delete a tracker

On the Events page, open the event of the tracker and click Delete the click tracker. Then confirm with Delete tracker. GrainQL Tag stops sending the event. The events that it already sent stay in your data.

​
Rules for trackers

  1. Use a specific selector. #checkout-btn matches one element. .btn matches every button.
  2. Name the tracker after the element and the action, for example “Hero CTA click”. The name becomes the event name.
  3. Do not rename a tracker that has data. The new name sends a new event name.
  4. If you want the journey that leads to a click, create a track with the event as the goal. Read Tracks.

​
What trackers do not do

  • A tracker does not record what the visitor typed or the content of a form.
  • A tracker does not count on pages where GrainQL Tag is not installed.
  • A tracker does not send your own properties. For that, call track. Read Track an event.