> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grainql.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Trackers

> A tracker counts clicks on one element of your site, without a code change.

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

| Type | Counts | Use for |
| - | - | - |
| Conversion | One interaction per visitor. Repeat clicks from the same visitor do not count. The dashboard shows a conversion rate as a percentage of all visitors. | Goals: sign-ups, purchases, downloads, form submissions |
| Metric | Every interaction, including repeat clicks from the same visitor. The dashboard shows raw counts over time. | Engagement: navigation, content, feature usage |

## Create a tracker in the dashboard

<Steps>
  <Step title="Open Conversions">
    In the dashboard sidebar, click **Conversions**. Then click **Create Tracker**.
  </Step>

  <Step title="Enter a CSS selector">
    Enter the selector of the element. Examples: `#signup-btn`, `.cta-button`,
    `[data-action="purchase"]`.
  </Step>

  <Step title="Name the tracker">
    Enter a name, for example "Signup Button Clicks".
  </Step>

  <Step title="Choose the type">
    Choose **Conversion** or **Metric**.
  </Step>

  <Step title="Set the URL scope">
    The URL scope is optional. Read the table below. Then save.
  </Step>
</Steps>

## Create a tracker in Studio

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

<Steps>
  <Step title="Open Studio">
    Open Studio on a page of your site.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Name and save">
    Enter a name and choose the type. Then save. The tracker is active at once.
  </Step>
</Steps>

## 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`.

| Scope | The tracker is active when | Example |
| - | - | - |
| `all` | The element exists on the page. | A link in the global navigation |
| `contains` | The page URL contains the pattern. | `/pricing` matches `/pricing` and `/pricing/enterprise` |
| `equals` | The page URL equals the pattern. | `/checkout` matches only `/checkout` |
| `prefix` | The page URL starts with the pattern. | `/docs` matches `/docs` and `/docs/api` |

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

| Field | Holds |
| - | - |
| Name | The label that the dashboard shows, for example "Hero CTA" |
| Selector | The CSS selector of the element |
| Type | `conversion` or `metric` |
| URL scope | `all`, `contains`, `equals`, or `prefix` |
| URL pattern | The string for `contains`, `equals`, and `prefix` |
| Enabled | Whether Grain Tag runs the tracker |

## What the dashboard shows

The **Conversions** page shows, per tracker:

| Item | Shows |
| - | - |
| Conversion rate | The percentage of visitors who interacted with the element |
| Total conversions | The number of unique conversions |
| Trend graph | Conversions over time, by day, week, or month |
| Page breakdown | The pages that produce the most conversions, for trackers that run on several pages |

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](/features/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](/core/event-tracking).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.