Core Methods

Grain Tag Methods

Primary SDK for browser analytics. Import from @grainql/tag.

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

init()

Creates and returns the singleton GrainTagInstance. In non-browser environments (Node, SSR), returns a safe no-op stub.

function init(config?: Partial<GrainTagConfig>): GrainTagInstance

Parameters:

config — Configuration object. tenantId is the only required field.

Returns: GrainTagInstance Example:

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

If called more than once, returns the existing instance and logs a warning. Use destroy() first to re-initialize with new config.

track()

Track a custom event. If called before init(), the event is queued and replayed automatically once the SDK initializes.

function track(eventName: string, properties?: Record<string, unknown>): void

Parameters:

eventName — Name of the event
properties — Optional key-value pairs

Example:

track('button_clicked', { button: 'signup', page: '/pricing' });

identify()

Set user identity. If called before init(), the call is queued and replayed after initialization.

function identify(userId: string): void

Parameters:

userId — User identifier

Example:

identify('user-123');

getInstance()

Get the existing SDK instance, or null if not yet initialized.

function getInstance(): GrainTagInstance | null

Example:

const grain = getInstance();
if (grain) {
  grain.track('custom_event');
}

isInitialized()

Check whether the SDK has been initialized.

function isInitialized(): boolean

Example:

if (!isInitialized()) {
  init({ tenantId: 'your-tenant-id' });
}

destroy()

Tear down the SDK instance and clear the singleton. After calling this, you can call init() again with new config.

function destroy(): void

Example:

destroy();

Instance Methods

Once you have a GrainTagInstance (from init() or getInstance()), these methods are available:

grain.track()

Same as the top-level track(), but called on the instance directly.

grain.track(eventName: string, properties?: Record<string, unknown>): void

grain.identify()

Same as the top-level identify(), but called on the instance directly.

grain.identify(userId: string): void

Grant consent. Upgrades from cookieless to permanent identity tracking.

grain.consent.grant(categories?: string[]): void

Parameters:

categories — Consent categories to grant. Defaults to ['necessary', 'analytics', 'functional'].

Example:

// Grant all default categories
grain.consent.grant();

// Grant specific categories
grain.consent.grant(['necessary', 'analytics']);

Revoke consent. Downgrades back to cookieless identity mode.

grain.consent.revoke(categories?: string[]): void

Parameters:

categories — Categories to revoke. If omitted, revokes all.

Example:

grain.consent.revoke();

Get the current consent state.

grain.consent.status(): ConsentState | null

Returns: ConsentState object or null if no consent decision has been made.

interface ConsentState {
  granted: boolean;
  categories: string[];
  timestamp: number;
  version: string;
}

Example:

const status = grain.consent.status();
if (status?.granted) {
  console.log('Consent granted for:', status.categories);
}

grain.flush()

Force-send all pending events immediately.

grain.flush(): Promise<void>

Example:

await grain.flush();

grain.destroy()

Tear down the instance. Same as the top-level destroy().

grain.destroy(): void

grain.isReady()

Returns true if the SDK is fully initialized in a browser environment.

grain.isReady(): boolean

Analytics Web Methods

For remote config, React hooks, and server-side tracking. Import from @grainql/analytics-web.

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

createGrainAnalytics()

Creates a new Grain client instance.

const grain = createGrainAnalytics(config: GrainConfig): GrainAnalytics

Parameters:

config — Configuration object (see Types)

Returns: GrainAnalytics client instance Example:

const grain = createGrainAnalytics({
  tenantId: 'your-tenant-id',
  userId: 'user_123'
});

track()

Track an event. Two signatures available:

track(eventName, properties?, options?)

grain.track(
  eventName: string,
  properties?: Record<string, unknown>,
  options?: SendEventOptions
): Promise<void>

Parameters:

eventName — Name of the event
properties — Optional event properties
options.flush — Force immediate send (default: false)

Example:

grain.track('button_clicked', {
  button: 'signup',
  page: '/home'
});

// With flush
await grain.track('purchase', { total: 99.99 }, { flush: true });

track(event, options?)

grain.track(
  event: GrainEvent,
  options?: SendEventOptions
): Promise<void>

Parameters:

event — Complete event object
options.flush — Force immediate send

Example:

grain.track({
  eventName: 'purchase',
  userId: 'user_123',
  properties: { total: 99.99 },
  timestamp: new Date()
});

flush()

Manually flush all queued events.

await grain.flush(): Promise<void>

Returns: Promise that resolves when events are sent Example:

await grain.flush();
console.log('All events sent');

When to use:

Before page navigation
Critical events
Serverless functions
Before app closes

setUserId()

Set global user ID for all subsequent events.

grain.setUserId(userId: string | null): void

Parameters:

userId — User identifier, or null to clear

Example:

// Set user ID
grain.setUserId('user_123');

// Clear on logout
grain.setUserId(null);

identify()

Alias for setUserId(). Sets user ID for subsequent events.

grain.identify(userId: string | null): void

Example:

grain.identify('user_123');

getUserId()

Get current user ID.

grain.getUserId(): string | null

Returns: Current user ID or null if not set Example:

const userId = grain.getUserId();
if (userId) {
  console.log(`Tracking as: ${userId}`);
}

setProperty()

Set user properties for analytics and personalization.

await grain.setProperty(
  properties: Record<string, unknown>,
  options?: SetPropertyOptions
): Promise<void>

Parameters:

properties — Up to 4 key-value pairs (values converted to strings)
options.userId — Optional user ID override

Returns: Promise that resolves when properties are set Example:

// Set for current user
await grain.setProperty({
  plan: 'premium',
  location: 'US',
  signup_date: '2024-01-15'
});

// Set for specific user
await grain.setProperty({
  status: 'active'
}, { userId: 'user_456' });

Limits:

Maximum 4 properties per request
All values converted to strings
Subject to rate limiting

destroy()

Clean up resources and send remaining events.

grain.destroy(): void

Example:

// On app unmount
grain.destroy();

What it does:

Flushes queued events
Removes event listeners
Cleans up timers
Stops auto-refresh

Next Steps

Config Methods

Remote configuration methods

Template Methods

Pre-built event methods

Types

TypeScript type definitions

API Documentation

Query API

Grain Tag Methods

init()

track()

identify()

getInstance()

isInitialized()

destroy()

Instance Methods

grain.track()

grain.identify()

grain.flush()

grain.destroy()

grain.isReady()

Analytics Web Methods

createGrainAnalytics()

track()

track(eventName, properties?, options?)

track(event, options?)

flush()

setUserId()

identify()

getUserId()

setProperty()

destroy()

Next Steps

Config Methods

Template Methods

Types

​Grain Tag Methods

​init()

​track()

​identify()

​getInstance()

​isInitialized()

​destroy()

​Instance Methods

​grain.track()

​grain.identify()

​grain.consent.grant()

​grain.consent.revoke()

​grain.consent.status()

​grain.flush()

​grain.destroy()

​grain.isReady()

​Analytics Web Methods

​createGrainAnalytics()

​track()

​track(eventName, properties?, options?)

​track(event, options?)

​flush()

​setUserId()

​identify()

​getUserId()

​setProperty()

​destroy()

​Next Steps

Config Methods

Template Methods

Types

Grain Tag Methods

init()

track()

identify()

getInstance()

isInitialized()

destroy()

Instance Methods

grain.track()

grain.identify()

grain.consent.grant()

grain.consent.revoke()

grain.consent.status()

grain.flush()

grain.destroy()

grain.isReady()

Analytics Web Methods

createGrainAnalytics()

track()

track(eventName, properties?, options?)

track(event, options?)

flush()

setUserId()

identify()

getUserId()

setProperty()

destroy()

Next Steps