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