API Overview

• Grain Tag (@grainql/tag) — The primary SDK for browser-side analytics. Cookieless by default, auto-tracks page views, clicks, scroll, sessions, and more.
• Analytics Web (@grainql/analytics-web) — For remote configuration, React hooks, template events, and server-side tracking.

​

Grain Tag

​

Import Paths

// Core SDK
import { init, track, identify, getInstance, isInitialized, destroy } from '@grainql/tag';

// Types
import type { GrainTagConfig, GrainTagInstance, ConsentState } from '@grainql/tag';

​

Lifecycle

init(config) → track/identify → flush → destroy

1. init(config?) — Creates the singleton instance and starts auto-tracking
2. track(name, props?) / identify(userId) — Send events (works before init via pre-init queue)
3. flush() — Force-send all pending events
4. destroy() — Tear down the SDK and clear the singleton

​

Quick Reference

​

Instance Methods

​

Analytics Web

​

Import Paths

// Core SDK
import { createGrainAnalytics } from '@grainql/analytics-web';

// React Hooks
import { GrainProvider, useConfig, useAllConfigs, useTrack, useGrainAnalytics } from '@grainql/analytics-web/react';

// Types
import type { GrainConfig, GrainEvent, AuthProvider } from '@grainql/analytics-web';

​

Quick Reference

​

Remote Configuration

​

Template Events

​

React Hooks

​

Return Values

• Synchronous methods: Direct values or undefined
• Async methods: Promise<T> that resolves to the result
• Hooks: Objects with data, loading states, and errors

​

Error Handling

• track(): Fire-and-forget, errors logged if debug enabled
• Config methods: Return cached/default on failure
• Async methods: Throw errors, catch with try/catch
• Hooks: Provide error property

​

Explore the API