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>
<script>
  // SDK auto-initializes, get the instance
  const grain = GrainTag.getInstance();

  // Track custom events
  grain.track('button_clicked', { button_id: 'signup' });
</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, session management, and DOM snapshots for heatmaps.

​
Identify Users

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

  // After your user logs in
  grain.identify('user_123');
</script>
Grain is cookieless by default. When you need explicit consent handling: 
<script>
  const grain = GrainTag.getInstance();

  // Grant consent (enables persistent tracking)
  grain.consent.grant();

  // Revoke consent (returns to cookieless mode)
  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 remote config.

​
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
  • Remote configuration
  • React hooks (optional)
  • Full TypeScript support

​
Import and Use

import { GrainTag } from '@grainql/tag';

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

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

// Identify users
grain.identify('user_123');

​
React Hooks

import { GrainProvider, useTrack, useConfig } from '@grainql/tag/react';
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 (hooks included)
  • 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: 
const grain = GrainTag.getInstance();
grain.track('installation_test');
Check your dashboard — the event should appear within seconds.

​
npm Package

import { GrainTag } from '@grainql/tag';

const grain = GrainTag.init({
  tenantId: 'your-tenant-id',
  debug: true // Enable console logging
});

grain.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. When you need explicit consent management: 
<script>
  const grain = GrainTag.getInstance();

  // Grant consent (enables persistent tracking with cookies)
  grain.consent.grant();

  // Revoke consent (clears cookies, 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 session IDs — no cookies or persistent tracking. 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