Skip to main content
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
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