Grain Analytics - Grain Analytics

Grain Analytics is privacy-first web analytics. It is cookieless by default and identifies a visitor with an ID that rotates every day. One script tag installs it, and Grain sets no cookies in the default configuration, so a consent banner is not required for it. This site documents the browser script, the TypeScript SDK, the Query API, and the MCP server. Grain does six things:

It collects page views, clicks, scroll depth, heatmaps, DOM snapshots, sessions, and attention without tracking code.
It records the custom events that your code sends, with properties, and it identifies users.
It stores user properties and serves remote configuration values to your code.
It shows trackers, tracks, heatmaps, and goals in the dashboard.
It returns your events over the Query API.
It answers questions from an AI assistant over the MCP server.

Surfaces

Surface	Package or host	Reader
Grain Tag, the browser script	`https://tag.grainql.com/v4/your-tenant-id.js`, npm `@grainql/tag`	Front-end developers, and every no-code install
Analytics Web, the TypeScript SDK	npm `@grainql/analytics-web`	Backend developers, and React developers who need hooks or remote configuration
Query API	`https://queryapis.grainql.com/v1/api/query`	Developers who export or dashboard data
MCP server	`https://grainql.com/api/mcp`	Developers who use Claude, Cursor, or ChatGPT

Every surface identifies your account by the tenant alias that the dashboard shows. Read Authentication.

Two paths

I do not write code

Install Grain Tag with Google Tag Manager, Shopify, or WordPress. Then read the dashboard pages: Trackers, Tracks, Heatmaps, and Mission Control.

I write code

Install Grain Tag with a Script tag, in React, or in Next.js. Install Analytics Web for Node.js and servers. Then read Track an event.

If you are not sure which package to install, the chooser decides. Read Install Grain.

A first event

When the script loads, Grain Tag starts automatic tracking. GrainTag.track sends a custom event:

<script src="https://tag.grainql.com/v4/your-tenant-id.js"></script>
<script>
  GrainTag.track('signup_clicked', { location: 'hero' });
</script>

Replace your-tenant-id with the tenant alias from the dashboard.

The documentation

Group	Read it for
Start here	Install Grain, Authentication, Privacy and consent, Troubleshooting
Install without code	Google Tag Manager, Shopify, WordPress
Install with code	Script tag, Plain JavaScript, Vue, and Svelte, React, Next.js, Node.js and servers
Track events	Track an event, Name events, Automatic tracking, Automatic properties, Identify users, User properties, Template events, Tracking checklist
Dashboard	Trackers, Tracks, Heatmaps, Mission Control
Remote configuration	Remote configuration, Feature flags, A/B tests, Personalization
Guides	E-commerce tracking, Export and query data
React	React hooks and one page per hook
Advanced	Configuration options, Errors and retries, Security, Performance, TypeScript, Attention quality
API reference	SDK reference, Query API
AI tools	Facts for coding agents, MCP server
Examples	Plain JavaScript app, React app, Next.js app, E-commerce store, Authentication flow, Custom dashboard, Data export

What Grain does not do

Grain Tag has no remote configuration and no React hooks. Both are in Analytics Web.
Analytics Web takes no DOM snapshots and runs no dashboard trackers. It collects page views and heatmap clicks by default (enableAutoPageView, enableHeatmapTracking).
Grain Tag has no authentication strategy. It sends events with the tenant alias only.
Grain sets no cookies and stores no persistent ID until your code calls consent.grant().
The Query API is not available on the Free plan.
The MCP server is read-only. An assistant cannot send events or change a configuration.

What wins on conflict

The TypeScript types of the published packages, @grainql/tag and @grainql/analytics-web, win over the prose on this site. If a page and the types disagree, the types are correct, and the page has an error.

Start here

Install Grain

Your situation, the package to install, and the page to read.

Script tag

Grain Tag on any site, with the first custom event.

Track an event

track in both SDKs, properties, batching, and delivery.

Facts for coding agents

A dense fact sheet for a coding agent.

​Surfaces

​Two paths