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

# Google Tag Manager

> Install the Grain Tag on your site with a Google Tag Manager custom HTML tag.

Google Tag Manager installs the Grain Tag without a change to the code of your website. This page
creates one tag, one trigger, and one published version. It takes about 10 minutes.

## Before you start

You need three things:

* Access to your [Google Tag Manager](https://tagmanager.google.com) account. The container must
  be installed on your site.
* Your tenant alias from the [dashboard](https://grainql.com/dashboard). It is the alias shown at
  the top of the dashboard, not the UUID.
* 10 minutes.

## 1. Create a tag

1. Log in to [Google Tag Manager](https://tagmanager.google.com).
2. Select your container.
3. Click **Tags**, then **New**.
4. Click **Tag Configuration**.
5. Select **Custom HTML**.

## 2. Add the code

Paste this code into the HTML field:

```html theme={null}
<script src="https://tag.grainql.com/v4/your-tenant-id.js"></script>
```

Replace `your-tenant-id` with your tenant alias.

## 3. Set the trigger

1. Scroll to **Triggering**.
2. Click the trigger area.
3. Click **+** to create a new trigger.
4. Select **Initialization - All Pages**.
5. Name the trigger "All Pages - Initialization".
6. Click **Save**.

The **Initialization** trigger fires before every other trigger. As a result, the Grain Tag loads
early and records every interaction on the page.

## 4. Name and save the tag

1. Name the tag "Grain Analytics".
2. Click **Save**.

## 5. Test the tag

1. Click **Preview** (top right).
2. Enter the URL of your website. Google Tag Manager opens your site with a debug panel.
3. Make sure that "Grain Analytics" is in **Tags Fired**.
4. Open the browser console (F12).
5. Type `window.GrainTag`. The console shows the `GrainTag` object.

If the console shows the `GrainTag` object, the installation works.

## 6. Publish

1. Click **Submit** (top right).
2. Name the version, for example "Added Grain Analytics".
3. Add a description. This step is optional.
4. Click **Publish**.

The Grain Tag is now live on every page of your site. It records page views, clicks, and scroll
depth without more configuration. Read [Automatic tracking](/core/automatic-tracking).

## Track custom events

After the Grain Tag is installed, you can send an event for a specific user action. Each event is
a new Custom HTML tag with its own trigger.

`{{Click Text}}`, `{{Click URL}}`, and `{{Form ID}}` are built-in Google Tag Manager variables.
Enable them in **Variables**, then **Configure**.

### Button clicks

1. Create a new Custom HTML tag.
2. Add this code:

```html theme={null}
<script>
  GrainTag.track('button_clicked', {
    button_text: {{Click Text}},
    button_url: {{Click URL}}
  });
</script>
```

3. Set the trigger to **All Elements - Click**.
4. Add filters to select the buttons that you want to track.

### Form submissions

1. Create a new Custom HTML tag.
2. Add this code:

```html theme={null}
<script>
  GrainTag.track('form_submitted', {
    form_name: {{Form ID}},
    form_url: window.location.pathname
  });
</script>
```

3. Set the trigger to **Form Submission**.

### Link clicks

1. Create a new Custom HTML tag.
2. Add this code:

```html theme={null}
<script>
  GrainTag.track('link_clicked', {
    link_text: {{Click Text}},
    destination: {{Click URL}}
  });
</script>
```

3. Set the trigger to **Just Links - All Elements**.

Read [Name events](/core/event-naming) for the naming convention.

## Troubleshooting

| Symptom | Cause | What to do |
| - | - | - |
| The tag does not fire | The trigger is not **Initialization - All Pages** | Open the tag and set the trigger. |
| The tag does not fire | The container is saved but not published | Click **Submit**, then **Publish**. |
| The tag does not fire | The browser holds an old copy of the container | Clear the browser cache and reload the page. |
| Events do not show in the dashboard | The tenant alias in the script URL is wrong | Compare the alias with the one at the top of the dashboard. |
| Events do not show in the dashboard | The script did not load | Open the console (F12, then **Console**) and read the errors. Type `window.GrainTag`. The console must show the `GrainTag` object. |
| Another tag conflicts with the Grain Tag | The Grain tag fires too late or too early | Raise the priority in **Tag**, then **Advanced Settings**, then **Tag firing priority**. Or use the **DOM Ready** trigger instead of **Initialization**. |

Read [Troubleshooting](/troubleshooting) for cases that are not specific to Google Tag Manager.

## Next steps

<CardGroup cols={2}>
  <Card title="Trackers" icon="crosshairs" href="/features/trackers">
    Track clicks on specific elements from the dashboard, without code.
  </Card>

  <Card title="Heatmaps" icon="fire" href="/features/heatmaps">
    See where visitors click and how far they scroll.
  </Card>

  <Card title="Tracks" icon="route" href="/features/tracks">
    Build funnels and paths from the events that the Grain Tag records.
  </Card>

  <Card title="Privacy and consent" icon="shield" href="/essentials/privacy-and-compliance">
    What Grain stores, cookieless mode, and consent modes.
  </Card>
</CardGroup>


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