Installation

Looking for a quick start guide? Check out our platform-specific integrations for step-by-step setup instructions.

Choose Your Installation Method

Pick the method that fits your setup:

Grain Tag (Script)

The primary way to install Grain — works everywhere

npm / yarn / pnpm

For React, Next.js, and apps with a build step

Grain Tag (Script)

The fastest way to add Grain to any site. Drop a single script tag in your HTML and you’re live.

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

Replace your-tenant-id with your tenant identifier (not UUID) from your dashboard. The Grain Tag handles everything automatically: page views, click tracking, scroll depth, heatmaps, rage clicks, dead clicks, session management, and DOM snapshots.

Track Custom Events

<script>
  // Track custom events
  GrainTag.track('signup_clicked', { location: 'hero' });
</script>

Identify Users

<script>
  // After your user logs in
  GrainTag.identify('user_123');
</script>

Grain is cookieless by default. When you need explicit consent handling:

<script>
  const grain = GrainTag.getInstance();

  // Grant consent (upgrades to persistent IDs stored in localStorage)
  grain.consent.grant();

  // Revoke consent (returns to cookieless mode with daily rotating IDs)
  grain.consent.revoke();

  // Check current consent status
  const status = grain.consent.status();
</script>

Consent modes:

auto (default) — Cookieless analytics, no consent required
opt-in — No tracking until the user grants consent
opt-out — Tracking by default, user can revoke

Next steps: See the Grain Tag (Script) guide for complete examples including forms, navigation tracking, and more.

npm Package

For React, Next.js, and other apps with a build step, install @grainql/tag:

npm install @grainql/tag

yarn add @grainql/tag

pnpm add @grainql/tag

The package includes:

Core analytics SDK
Automatic tracking (page views, heatmaps, scroll depth)
Privacy-first identity (cookieless by default)
Full TypeScript support

Import and Use

import { init, track, identify } from '@grainql/tag';

// Initialize once
const grain = init({ tenantId: 'your-tenant-id' });

// Track events
track('button_clicked', { button_id: 'signup' });

// Identify users
identify('user_123');

Next steps: Check out the React Quick Start or Next.js Quick Start for complete examples.

Platform Support

Grain works across multiple environments:

Browser

Chrome, Firefox, Safari, Edge
Modern ES6+ and legacy ES5
Module bundlers (Vite, Webpack, esbuild)

Frameworks

React
Next.js (App Router & Pages Router)
Vue, Svelte, Angular
Vanilla JavaScript

Server

Node.js 14+
Serverless (AWS Lambda, Vercel, Netlify)

Verify Installation

Grain Tag (Script)

Open your browser console after adding the script tag. You should see Grain initialization logs. Then run:

GrainTag.track('installation_test');

Check your dashboard — the event should appear within seconds.

npm Package

import { init, track } from '@grainql/tag';

const grain = init({
  tenantId: 'your-tenant-id',
  debug: true
});

track('installation_test');
console.log('Grain initialized!');

Check your browser console to see batching and sending activity.

Grain is cookieless by default — no consent banner needed for basic analytics. Daily rotating IDs ensure user privacy without sacrificing analytics quality. When you need explicit consent management:

<script>
  const grain = GrainTag.getInstance();

  // Grant consent (upgrades to persistent IDs stored in localStorage, not cookies)
  grain.consent.grant();

  // Revoke consent (clears stored IDs, returns to cookieless mode)
  grain.consent.revoke();

  // Check consent status
  const status = grain.consent.status();
</script>

GDPR Compliance: In the default auto mode, Grain uses only ephemeral daily rotating IDs — no cookies or persistent tracking. Calling consent.grant() upgrades to persistent IDs stored in localStorage (not cookies). See Privacy & Compliance for full details.

What’s Next?

Grain Tag (Script)

Complete guide with examples for script-based installation

React Quick Start

Hooks-based integration for React apps

Authentication

Set up Auth0 or custom JWT authentication

Tracking & Events

Learn about event tracking and best practices

Getting Started

Integrations

Tracking & Events

Dashboard

MCP Server

Guides

React SDK

Advanced

Choose Your Installation Method

Grain Tag (Script)

npm / yarn / pnpm

Grain Tag (Script)

Track Custom Events

Identify Users

npm Package

Import and Use

Platform Support

Browser

Frameworks

Server

Verify Installation

Grain Tag (Script)

npm Package

What’s Next?

Grain Tag (Script)

React Quick Start

Authentication

Tracking & Events

​Choose Your Installation Method

Grain Tag (Script)

npm / yarn / pnpm

​Grain Tag (Script)

​Track Custom Events

​Identify Users

​Consent Management

​npm Package

​Import and Use

​Platform Support

​Browser

​Frameworks

​Server

​Verify Installation

​Grain Tag (Script)

​npm Package

​Privacy & Consent

​What’s Next?

Grain Tag (Script)

React Quick Start

Authentication

Tracking & Events

Choose Your Installation Method

Grain Tag (Script)

Track Custom Events

Identify Users

Consent Management

npm Package

Import and Use

Platform Support

Browser

Frameworks

Server

Verify Installation

Grain Tag (Script)

npm Package

Privacy & Consent

What’s Next?