Script tag

This page installs Grain Tag on a website with one script tag. Grain Tag collects page views, clicks, scroll depth, heatmaps, and DOM snapshots without further code. The page ends with a custom event, an identified user, and a consent call.

Before you start

You need three things:

Your tenant alias. The dashboard at https://grainql.com/dashboard shows it. It is not the UUID.
Write access to the HTML of your site, or to a tag manager. For Google Tag Manager, read Google Tag Manager.
A browser with developer tools, to make sure that events arrive.

1. Add the script

Put this tag in the <head> of every page. Replace your-tenant-id with your tenant alias.

<script src="https://tag.grainql.com/v4/your-tenant-id.js"></script>

The script initializes itself when it loads. It exposes the global GrainTag object. Add the tag one time per page. A second tag on the same page is not necessary.

2. Make sure that events arrive

Open the page in a browser. In the developer console, run:

GrainTag.track('installation_test');

The dashboard shows the installation_test event within 30 seconds. If the event does not appear, read Troubleshooting.

3. Track a custom event

Call track with an event name and an optional properties object.

<button id="signup-btn">Get Started</button>

<script>
  document.getElementById('signup-btn').addEventListener('click', function () {
    GrainTag.track('signup_clicked', { location: 'hero' });
  });
</script>

Grain Tag batches events and sends them in groups. A manual flush is not necessary. GrainTag.track and GrainTag.identify work before initialization completes. Grain Tag queues the calls and replays them after initialization. Read Track an event and Name events.

4. Identify a user

After a login, pass the user ID to identify. Every later event holds this user ID.

function handleLogin(userId) {
  GrainTag.identify(userId);
  GrainTag.track('user_logged_in', { method: 'email' });
}

Read Identify users. Grain Tag is cookieless by default and uses daily rotating IDs. When your site asks for consent, call the consent methods on the instance.

const grain = GrainTag.getInstance();

grain.consent.grant();
grain.consent.revoke();
const status = grain.consent.status();

grant enables persistent tracking. Grain Tag stores the persistent ID in localStorage, not in a cookie. status returns the current ConsentState, or null. Read Privacy and consent.

6. Single-page applications

Grain Tag tracks the first page view and every navigation through the History API (pushState and replaceState). A router that uses the History API needs no extra code. If your router does not use the History API, track the navigation yourself:

function navigateTo(url) {
  GrainTag.track('page_viewed', { page: url });
}

Next steps

Core methods

Every method of both SDKs, with signatures.

Trackers

Track element clicks from the dashboard, without code.

Plain JavaScript, Vue, and Svelte

Grain Tag through npm in any framework.

Automatic tracking

What Grain Tag collects without code.

Start here

Install without code

Install with code

Track events

Dashboard

Remote configuration

Guides

React

Advanced

Before you start

1. Add the script

2. Make sure that events arrive

3. Track a custom event

4. Identify a user

6. Single-page applications

Next steps

Core methods

Trackers

Plain JavaScript, Vue, and Svelte

Automatic tracking

​Before you start

​1. Add the script

​2. Make sure that events arrive

​3. Track a custom event

​4. Identify a user

​5. Grant consent

​6. Single-page applications

​Next steps

Core methods

Trackers

Plain JavaScript, Vue, and Svelte

Automatic tracking

Before you start

1. Add the script

2. Make sure that events arrive

3. Track a custom event

4. Identify a user

5. Grant consent

6. Single-page applications

Next steps