Skip to main content
A tracker counts interactions with one HTML element: a button, a link, or a form. You create it in the dashboard under Conversions, or with the visual picker in Studio. Grain Tag reads the tracker definitions and counts the clicks. You do not need to change your site.

​
Two types

​
Create a tracker in the dashboard

1

Open Conversions

In the dashboard sidebar, click Conversions. Then click Create Tracker.
2

Enter a CSS selector

Enter the selector of the element. Examples: #signup-btn, .cta-button, [data-action="purchase"].
3

Name the tracker

Enter a name, for example “Signup Button Clicks”.
4

Choose the type

Choose Conversion or Metric.
5

Set the URL scope

The URL scope is optional. Read the table below. Then save.

​
Create a tracker in Studio

Studio is the Grain browser extension. Its picker writes the selector for you.
1

Open Studio

Open Studio on a page of your site.
2

Choose the Tracker tool

Click the Tracker tool in the toolbar. Then click the element that you want to track. Studio writes the CSS selector.
3

Name and save

Enter a name and choose the type. Then save. The tracker is active at once.

​
URL scope

By default, a tracker counts on every page where the element exists. The URL scope limits the pages where the tracker is active. The values below are the urlScope values of the TrackerDefinition type in @grainql/tag. Grain Tag normalizes the page URL and the pattern before it compares them. It removes the protocol and www., and it adds a trailing slash. As a result, https://www.example.com/pricing and example.com/pricing/ are the same URL. If the same .cta-button class exists on several pages and you want only the homepage, set the scope to equals with the pattern /.

​
What a tracker stores

​
What the dashboard shows

The Conversions page shows, per tracker: You can filter by date range, device type, and traffic source.

​
How Grain Tag runs trackers

  1. On page load, Grain Tag fetches the tracker definitions of your tenant from the Grain API.
  2. For each enabled tracker, it finds the matching elements and attaches a click listener. It prefers a stored fingerprint of the element and falls back to the CSS or XPath selector.
  3. Grain Tag watches the page for DOM changes. When new matching elements appear, for example after a client-side navigation, it attaches the listener again.
  4. Grain Tag reports for each tracker whether the selector matched an element.
The full definition is the TrackerDefinition type in @grainql/tag. When this page and the type disagree, the type wins.

​
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 page, for example “Hero CTA, homepage”.
  3. Create conversion trackers for your goals first. Add metric trackers for engagement later.
  4. If you want the journey that leads to a conversion, create a track with the same 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 Grain Tag is not installed.
  • A tracker does not send a custom event with your own properties. For that, call track. Read Track an event.