Skip to main content

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.

Grain provides two SDKs for different use cases:
  • 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

The default SDK for browser analytics. Lightweight, privacy-first, and SSR safe.

​
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

MethodDescription
init(config?)Create singleton, returns GrainTagInstance
track(eventName, properties?)Track a custom event
identify(userId)Set user identity
getInstance()Get existing instance or null
isInitialized()Check if SDK is initialized
destroy()Tear down SDK, clear singleton

​
Instance Methods

MethodDescription
grain.track(eventName, properties?)Track a custom event
grain.identify(userId)Set user identity
grain.consent.grant(categories?)Grant consent
grain.consent.revoke(categories?)Revoke consent
grain.consent.status()Get current consent state
grain.flush()Flush pending events
grain.destroy()Tear down instance
grain.isReady()Check if running in browser

​
Analytics Web

For remote configuration, React hooks, template events, and server-side tracking.

​
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

MethodDescription
createGrainAnalytics(config)Create client instance
grain.track(eventName, properties?, options?)Track an event
grain.flush()Flush pending events
grain.setUserId(userId)Set user ID
grain.identify(userId)Alias for setUserId
grain.getUserId()Get current user ID
grain.setProperty(properties, options?)Set user properties
grain.destroy()Clean up resources

​
Remote Configuration

MethodDescription
grain.getConfig(key)Get config value (sync)
grain.getAllConfigs()Get all configs (sync)
grain.getConfigAsync(key, options?)Get config value (async)
grain.getAllConfigsAsync(options?)Get all configs (async)
grain.fetchConfig(options?)Fetch fresh config from server
grain.preloadConfig(keys?, properties?)Preload config values
grain.addConfigChangeListener(listener)Listen for config changes
grain.removeConfigChangeListener(listener)Remove config listener

​
Template Events

MethodDescription
grain.trackLogin(properties?, options?)Track login
grain.trackSignup(properties?, options?)Track signup
grain.trackCheckout(properties?, options?)Track checkout
grain.trackPurchase(properties?, options?)Track purchase
grain.trackAddToCart(properties?, options?)Track add to cart
grain.trackRemoveFromCart(properties?, options?)Track remove from cart
grain.trackPageView(properties?, options?)Track page view
grain.trackSearch(properties?, options?)Track search

​
React Hooks

HookDescription
<GrainProvider config={...}>Context provider
useConfig(key, options?)Get a single config value
useAllConfigs(options?)Get all config values
useTrack()Get track function
useGrainAnalytics()Get client instance

​
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

Methods handle errors gracefully:
  • 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
Learn more in Error Handling.

​
Explore the API

Core Methods

Event tracking and user management

Config Methods

Remote configuration access

Template Methods

Pre-built event methods

React Hooks

React integration hooks

Types

TypeScript type definitions