SDK reference - Grain Analytics

These pages describe the public surface of @grainql/tag 4.5.1 and @grainql/analytics-web 3.4.2. Every signature is copied from the .d.ts files that ship inside the published packages. When a sentence on this site disagrees with those files, the .d.ts files win.

The two packages

Package	Version	Runs in	Holds
`@grainql/tag` (Grain Tag)	4.5.1	Browser. Safe to import on a server.	`init`, `track`, `identify`, consent, automatic tracking
`@grainql/analytics-web` (Analytics Web)	3.4.2	Browser and Node.js	`GrainAnalytics` client, template events, remote configuration, consent
`@grainql/analytics-web/react`	3.4.2	React	`GrainProvider`, hooks, consent components

The script build of Grain Tag at https://tag.grainql.com/v4/your-tenant-id.js exposes the same functions on window.GrainTag.

Import forms

import { init, track, identify, getInstance, isInitialized, destroy } from '@grainql/tag';
import type { GrainTagConfig, GrainTagInstance } from '@grainql/tag';

// Script build of Grain Tag. No import.
window.GrainTag.track('signup_completed');

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

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

@grainql/tag has no side effects at import time. Outside a browser, init returns a no-op stub, so a server-rendered application does not need an environment guard.

Reference pages

Page	Holds
Core methods	`init`, `track`, `identify`, consent, user identity, `flush`, `destroy` of both packages
Configuration methods	`getConfig`, `fetchConfig`, `preloadConfig`, change listeners, and the options and response types
Template methods	`trackLogin`, `trackSignup`, `trackCheckout`, `trackPageView`, `trackPurchase`, `trackSearch`, `trackAddToCart`, `trackRemoveFromCart`
React hooks	`GrainProvider`, every hook, and the three consent components
Types	Every exported type of both packages
Query API	The REST endpoint that reads events out

Return values

Package	Method group	Returns
Grain Tag	`init`	`GrainTagInstance`
Grain Tag	`track`, `identify`, `destroy`, `consent.grant`, `consent.revoke`	`void`
Grain Tag	`flush`	`Promise<void>`
Grain Tag	`getInstance`	`GrainTagInstance` or `null`
Analytics Web	`track`, the eight template methods, `setProperty`, `flush`, `preloadConfig`	`Promise<void>`
Analytics Web	`identify`, `setUserId`, `login`, `logout`, `grantConsent`, `revokeConsent`, `destroy`	`void`
Analytics Web	`getConfig`, `getAllConfigs`, `getUserId`, `getSessionId`, `getConsentState`	A value from memory, without a request
Analytics Web	`getConfigAsync`, `getAllConfigsAsync`, `fetchConfig`	A `Promise`
React	`useConfig`, `useAllConfigs`	An object with the value, `isRefreshing`, `error`, and `refresh`

A Grain Tag track call does not return a promise. The event goes into a queue and the transport sends the queue later. To wait for delivery, call flush. An Analytics Web track call is fire-and-forget. A delivery failure does not reject the promise. The client logs the failure when debug is true, and retries the request retryAttempts times. The configuration methods return the cached value or the default on a failure. The Async methods throw, so wrap them in try and catch. Read Errors and retries.

​The two packages

​Import forms

​Reference pages

​Return values

The two packages

Import forms

Reference pages

Return values