> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grainql.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install Grain Analytics in your project

<Note>
  **Looking for a quick start guide?** Check out our [platform-specific integrations](/quickstart/cdn) for step-by-step setup instructions.
</Note>

## Choose Your Installation Method

Pick the method that fits your setup:

<CardGroup cols={2}>
  <Card title="Grain Tag (Script)" icon="globe" href="#grain-tag-script">
    The primary way to install Grain — works everywhere
  </Card>

  <Card title="npm / yarn / pnpm" icon="box" href="#npm-package">
    For React, Next.js, and apps with a build step
  </Card>
</CardGroup>

***

## Grain Tag (Script)

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

```html theme={null}
<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](https://grainql.com/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

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

### Identify Users

```html theme={null}
<script>
  // After your user logs in
  GrainTag.identify('user_123');
</script>
```

### Consent Management

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

```html theme={null}
<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

<Tip>
  **Next steps**: See the [Grain Tag (Script) guide](/quickstart/cdn) for complete examples including forms, navigation tracking, and more.
</Tip>

***

## npm Package

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

<CodeGroup>
  ```bash npm theme={null}
  npm install @grainql/tag
  ```

  ```bash yarn theme={null}
  yarn add @grainql/tag
  ```

  ```bash pnpm theme={null}
  pnpm add @grainql/tag
  ```
</CodeGroup>

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

```typescript theme={null}
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');
```

<Tip>
  **Next steps**: Check out the [React Quick Start](/quickstart/react) or [Next.js Quick Start](/quickstart/nextjs) for complete examples.
</Tip>

***

## 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:

```javascript theme={null}
GrainTag.track('installation_test');
```

Check your [dashboard](https://grainql.com/dashboard) — the event should appear within seconds.

### npm Package

```typescript theme={null}
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.

***

## Privacy & Consent

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:

```html theme={null}
<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>
```

<Info>
  **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](/essentials/privacy-and-compliance) for full details.
</Info>

***

## What's Next?

<CardGroup cols={2}>
  <Card title="Grain Tag (Script)" icon="globe" href="/quickstart/cdn">
    Complete guide with examples for script-based installation
  </Card>

  <Card title="React Quick Start" icon="react" href="/quickstart/react">
    Hooks-based integration for React apps
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    Set up Auth0 or custom JWT authentication
  </Card>

  <Card title="Tracking & Events" icon="chart-line" href="/core/event-tracking">
    Learn about event tracking and best practices
  </Card>
</CardGroup>