Plain JavaScript app

This page builds one HTML page that uses Grain Tag for page views, clicks, a form, a user ID, and consent. Every block uses Grain Tag (@grainql/tag or the script tag). Grain Tag has no remote configuration and no template events. For those, read React app.

Install by script tag

Put the tag in the <head> of every page. The script initializes itself when it loads and exposes the global GrainTag object.

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

Install by npm

For a bundled app, install the package and call init one time. The named exports track and identify work before init completes. Grain Tag queues the calls and replays them.

npm install @grainql/tag

// main.js
import { init } from '@grainql/tag';

init({ tenantId: 'your-tenant-id' });

The rest of this page uses the global GrainTag object. With npm, replace GrainTag.track with the track export and GrainTag.getInstance() with the getInstance export.

Page views

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

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

Read Automatic tracking.

Clicks

Grain Tag records every click for heatmaps. A custom event adds the properties that you choose.

document.querySelectorAll('button[data-track]').forEach((button) => {
  button.addEventListener('click', () => {
    GrainTag.track('button_clicked', {
      button_id: button.id,
      button_text: button.textContent,
      page: window.location.pathname
    });
  });
});

For a click on one element, a tracker in the dashboard needs no code. Read Trackers.

Form submissions

A form submission leaves the page. Call flush on the instance before you submit, so the event reaches Grain before the page unloads.

document.getElementById('contact-form').addEventListener('submit', async (event) => {
  event.preventDefault();
  const form = event.target;

  GrainTag.track('form_submitted', {
    form_id: form.id,
    num_fields: form.elements.length
  });

  await GrainTag.getInstance().flush();
  form.submit();
});

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' });
}

Grain Tag has no method that clears the user ID. Read Identify users. Grain Tag is cookieless by default and uses daily rotating IDs. grant switches to a persistent ID in localStorage. revoke returns to daily rotating IDs. status returns the current ConsentState, or null.

const grain = GrainTag.getInstance();

document.getElementById('accept').addEventListener('click', () => {
  grain.consent.grant(['analytics']);
});

document.getElementById('decline').addEventListener('click', () => {
  grain.consent.revoke();
});

const state = grain.consent.status();

Read Privacy and consent.

The complete page

<!DOCTYPE html>
<html lang="en">
<head>
  <title>My App</title>
  <script src="https://tag.grainql.com/v4/your-tenant-id.js"></script>
</head>
<body>
  <h1>Welcome</h1>
  <button id="cta" data-track>Get Started</button>

  <form id="contact-form" action="/contact" method="post">
    <input name="email" type="email" required />
    <button type="submit">Send</button>
  </form>

  <div id="consent">
    <p>We use analytics to improve this site.</p>
    <button id="accept">Accept analytics</button>
    <button id="decline">Decline</button>
  </div>

  <script>
    document.getElementById('cta').addEventListener('click', () => {
      GrainTag.track('cta_clicked', { location: 'hero' });
    });

    document.getElementById('contact-form').addEventListener('submit', async (event) => {
      event.preventDefault();
      GrainTag.track('form_submitted', { form_id: 'contact-form' });
      await GrainTag.getInstance().flush();
      event.target.submit();
    });

    document.getElementById('accept').addEventListener('click', () => {
      GrainTag.getInstance().consent.grant(['analytics']);
    });

    document.getElementById('decline').addEventListener('click', () => {
      GrainTag.getInstance().consent.revoke();
    });
  </script>
</body>
</html>

Open the page in a browser. The dashboard shows the page view and the cta_clicked event within seconds. If an event does not appear, read Troubleshooting.

Apps

Query API

Install by script tag

Install by npm

Page views

Clicks

Form submissions

Identify a user

The complete page

​Install by script tag

​Install by npm

​Page views

​Clicks

​Form submissions

​Identify a user

​Consent

​The complete page

Install by script tag

Install by npm

Page views

Clicks

Form submissions

Identify a user

Consent

The complete page