Automatic tracking

Both SDKs start to collect data as soon as they load. The Grain Tag collects the most. Analytics Web collects page views, sessions, and heartbeats, and adds heatmap tracking as an option. Every automatic feature adapts to consent: before consent it sends a minimal payload, and after consent it sends the full one. Automatic tracking runs only in a browser. The SDK looks for window and starts tracking on the client side. The TypeScript types of the published packages win over this page when they disagree.

What is collected

What is collected	Grain Tag	Analytics Web	Option
Page views, including History API and hash navigation	Yes	Yes	`enablePageViews` (Grain Tag), `enableAutoPageView` (Analytics Web)
Sessions: `_grain_session_start` and `_grain_session_end`	Yes	Yes	None. Always on.
Heartbeat: `_grain_heartbeat` at a fixed interval	Yes	Yes	`enableHeartbeat`, `heartbeatActiveInterval`, `heartbeatInactiveInterval` (Analytics Web)
Clicks and click heatmaps	Yes	Yes	`enableHeatmaps` (Grain Tag), `enableHeatmapTracking` (Analytics Web)
Scroll depth	Yes	Yes	`enableHeatmaps` (Grain Tag), `enableHeatmapTracking` (Analytics Web)
DOM snapshots for heatmap overlays	Yes	No	`enableSnapshots` (Grain Tag)
Attention: section views and scroll duration	Yes	Yes	None. Read Attention quality.
Dashboard trackers on CSS selectors	Yes	No	None. Defined in the dashboard. Read Trackers.
`dataLayer` events from Google Tag Manager	Yes	No	`enableDataLayer` (Grain Tag)
Rescue campaigns	Yes	No	`enableRescue` (Grain Tag)

Every Grain Tag option above defaults to true. In Analytics Web, enableAutoPageView and enableHeartbeat default to true. Read Configuration options. Read Heatmaps for what the dashboard shows from clicks, scroll depth, and snapshots. Automatic events carry device, attribution, and session properties. Read Automatic properties.

Page views

The SDK sends a page_view event on the first load, on pushState and replaceState, on popstate, and on hashchange. React Router, Vue Router, Next.js App Router and Pages Router, and hash routing need no extra configuration. Query parameters are removed from the page property by default. A URL of https://example.com/products?search=shoes is sent as /products. Set stripQueryParams to false to keep them. stripHash removes the hash in the same way.

Analytics Web

import { createGrainAnalytics } from '@grainql/analytics-web';

const grain = createGrainAnalytics({
  tenantId: 'your-tenant-id',
  enableAutoPageView: false,
  stripQueryParams: true
});

await grain.trackPageView({ page: '/custom-page' });

With enableAutoPageView set to false, call trackPageView yourself.

Heartbeat

The heartbeat measures whether a session is active. The SDK watches mouse, keyboard, touch, and scroll events. It sends _grain_heartbeat with status set to active or inactive. The first heartbeat is sent on page load. The heartbeat starts when the SDK initializes and stops on destroy.

Limit	Value	Where
Interval while the user is active	120000 ms (2 minutes)	`heartbeatActiveInterval` in `GrainConfig`
Interval while the user is inactive	300000 ms (5 minutes)	`heartbeatInactiveInterval` in `GrainConfig`

Analytics Web

const grain = createGrainAnalytics({
  tenantId: 'your-tenant-id',
  enableHeartbeat: true,
  heartbeatActiveInterval: 120000,
  heartbeatInactiveInterval: 300000
});

Set enableHeartbeat to false to turn the heartbeat off. The listeners are passive and debounced, and the heartbeat runs on a timer, not on every event. Before consent, the SDK uses a session ID that lives only in memory. It sets no cookie and writes no identifier to localStorage. After consent, it uses a persistent user ID in localStorage or a cookie.

Data	Before consent	After consent
User ID	Session ID in memory only	Persistent user ID
Page path without query parameters	Sent	Sent
Timestamp, device, browser, OS	Sent	Sent
Heartbeat `status`	Sent	Sent
Referrer and page title	Not sent	Sent
Full URL	Not sent	Sent
Heartbeat `duration` and `event_count`	Not sent	Sent
`_minimal`	`true`	`false`
`_consent_status`	`pending`	`granted`

A heartbeat before consent:

{
  "eventName": "_grain_heartbeat",
  "userId": "ephemeral-session-id-123",
  "properties": {
    "type": "heartbeat",
    "status": "active",
    "timestamp": 1704067200000,
    "_minimal": true,
    "_consent_status": "pending"
  }
}

The same heartbeat after consent:

{
  "eventName": "_grain_heartbeat",
  "userId": "user-persistent-id-456",
  "properties": {
    "type": "heartbeat",
    "status": "active",
    "timestamp": 1704067200000,
    "page": "/dashboard/settings",
    "duration": 120000,
    "event_count": 15,
    "_minimal": false,
    "_consent_status": "granted"
  }
}

When a user is identified with identify or login, or the SDK uses JWT authentication, the SDK uses the persistent identifier before consent too. This use is functional, not analytical. Read Privacy and consent for the consent modes of both SDKs and the legal basis for minimal tracking. When the user grants consent, the SDK moves from the minimal payload to the full one on its own.

Before consent, events carry the session ID that lives in memory.
On grant, the SDK sends _grain_consent_granted with the old session ID and the new user ID.
After the grant, every event carries the persistent user ID.

{
  "eventName": "_grain_consent_granted",
  "userId": "user-persistent-id-456",
  "properties": {
    "previous_session_id": "ephemeral-session-id-123",
    "new_user_id": "user-persistent-id-456",
    "timestamp": 1704067200000
  }
}

With this event, a backend can join the events from before and after consent.

const grain = GrainTag.getInstance();

grain.consent.grant();
grain.consent.revoke();

grain.grantConsent();
grain.revokeConsent();

After revoke, automatic tracking continues with the minimal payload or stops. The consent mode in the configuration decides which.

Read the session

Analytics Web exposes the identifiers that automatic tracking uses.

Analytics Web

const sessionId = grain.getSessionId();
const userId = grain.getEffectiveUserId();
const ephemeralId = grain.getEphemeralSessionId();
const currentPage = grain.getCurrentPage();
const hasConsent = grain.hasConsent('analytics');

getSessionId returns the in-memory session ID before consent and the persistent one after. getEffectiveUserId returns the persistent ID when one exists.

Rules for the client

Keep the defaults on. The dashboard reads sessions, page views, and heartbeats from these events.
Keep stripQueryParams set to true. Query strings hold search terms and tokens.
State in your privacy policy what Grain collects before and after consent, from the table above.
Test the site with consent denied. Make sure that only the minimal payload leaves the page.
To stop every automatic feature at run time, call destroy. To stop one feature, set its option to false at initialization.

Start here

Install without code

Install with code

Track events

Dashboard

Remote configuration

Guides

React

Advanced

What is collected

Page views

Heartbeat

Read the session

Rules for the client

​What is collected

​Page views

​Heartbeat

​Before and after consent

​Consent upgrade

​Read the session

​Rules for the client

What is collected

Page views

Heartbeat

Before and after consent

Consent upgrade

Read the session

Rules for the client