Core methods - Grain Analytics

This page lists the core methods of Grain Tag and Analytics Web. Every signature is copied from the .d.ts files of the published packages. Read SDK reference for the import forms.

Grain Tag

Method	Returns	Does
`init(config?)`	`GrainTagInstance`	Creates the singleton and starts automatic tracking
`getInstance()`	`GrainTagInstance \| null`	Returns the singleton
`isInitialized()`	`boolean`	Tells whether `init` ran
`track(eventName, properties?)`	`void`	Sends an event
`identify(userId)`	`void`	Sets the user identity
`destroy()`	`void`	Removes the singleton
`instance.consent.grant(categories?)`	`void`	Grants consent
`instance.consent.revoke(categories?)`	`void`	Revokes consent
`instance.consent.status()`	`ConsentState \| null`	Returns the consent state
`instance.flush()`	`Promise<void>`	Sends the queue now
`instance.isReady()`	`boolean`	Tells whether the instance runs in a browser
`instance.updateDataLayerConnectors(connectors)`	`void`	Replaces the data layer connectors

The instance also has track, identify, and destroy with the same signatures as the module functions. The script build exposes init, getInstance, track, identify, and the GrainTag class on window.GrainTag.

init

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

Parameter	Type	Rule
`config`	`Partial<GrainTagConfig>`	Optional. `tenantId` is the only required field for a real instance. Read Types.

import { init } from '@grainql/tag';

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

In a browser, init creates the instance and starts automatic tracking. Outside a browser, init returns a no-op stub. If init runs a second time, it returns the existing instance and logs a warning. To start again with a new configuration, call destroy first.

getInstance

function getInstance(): GrainTagInstance | null

This function has no parameters. It returns null before init runs.

import { getInstance } from '@grainql/tag';

const grain = getInstance();
if (grain) {
  grain.track('plan_selected', { plan: 'pro' });
}

isInitialized

function isInitialized(): boolean

This function has no parameters.

import { init, isInitialized } from '@grainql/tag';

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

track

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

Parameter	Type	Rule
`eventName`	`string`	The event name. Read Name events.
`properties`	`Record<string, unknown>`	Optional key-value pairs.

import { track } from '@grainql/tag';

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

If track runs before init, the event goes into a queue. The SDK replays the queue after init.

identify

function identify(userId: string): void

Parameter	Type	Rule
`userId`	`string`	Your identifier for the user.

import { identify } from '@grainql/tag';

identify('user_123');

If identify runs before init, the call goes into the same queue as track. Read Identify users.

destroy

function destroy(): void

This function has no parameters. It removes the instance and clears the singleton. After destroy, init can run again with a new configuration.

import { destroy } from '@grainql/tag';

destroy();

grant(categories?: string[]): void

Parameter	Type	Rule
`categories`	`string[]`	Optional. Without it, the SDK grants `['necessary', 'analytics', 'functional']`.

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

grain.consent.grant(['necessary', 'analytics']);

A grant switches the identity from a daily rotating ID to a permanent ID. Read Privacy and consent.

revoke(categories?: string[]): void

Parameter	Type	Rule
`categories`	`string[]`	Optional. Without it, the SDK revokes every category.

grain.consent.revoke();

A revoke switches the identity back to a daily rotating ID.

status(): ConsentState | null

This method has no parameters. It returns null when the user made no consent decision.

const status = grain.consent.status();

if (status?.granted) {
  console.log(status.categories);
}

flush

flush(): Promise<void>

This method has no parameters. It sends every queued event now and resolves when the request is done.

await grain.flush();

isReady

isReady(): boolean

This method has no parameters. It returns true when the instance is a real instance in a browser, and false for the no-op stub.

if (grain.isReady()) {
  grain.track('app_started');
}

updateDataLayerConnectors

updateDataLayerConnectors(connectors: DataLayerConnectorConfig[]): void

Parameter	Type	Rule
`connectors`	`DataLayerConnectorConfig[]`	The full list of connectors. It replaces the current list. Read Types.

grain.updateDataLayerConnectors([
  {
    id: 'ga4',
    enabled: true,
    priority: 1,
    include_patterns: ['purchase', 'add_to_cart'],
    exclude_patterns: [],
    include_dimensions: [],
    exclude_dimensions: [],
    event_name_transform: 'snake_case',
    catch_all_unhandled: false,
    modifiers: [],
  },
]);

Analytics Web

Every method is a member of a GrainAnalytics instance. Create the instance with new GrainAnalytics(config) or createGrainAnalytics(config).

Method	Returns	Does
`track(eventName, properties?, options?)`	`Promise<void>`	Sends an event
`track(event, options?)`	`Promise<void>`	Sends a `GrainEvent` object
`identify(userId)`	`void`	Sets the user ID
`setUserId(userId)`	`void`	Sets or clears the user ID
`getUserId()`	`string \| null`	Returns the user ID that you set
`getEffectiveUserId()`	`string`	Returns the ID that goes on events
`getSessionId()`	`string`	Returns the session ID
`login(options)`	`void`	Sets the user ID, the token, or the strategy
`logout()`	`void`	Clears the user and returns to an anonymous ID
`setProperty(properties, options?)`	`Promise<void>`	Sends user properties
`flush()`	`Promise<void>`	Sends the queue now
`grantConsent(categories?)`	`void`	Grants consent
`revokeConsent(categories?)`	`void`	Revokes consent
`getConsentState()`	`ConsentState \| null`	Returns the consent state
`hasConsent(category?)`	`boolean`	Tells whether consent is granted
`onConsentChange(listener)`	`void`	Adds a consent listener
`offConsentChange(listener)`	`void`	Removes a consent listener
`destroy()`	`void`	Sends the queue and stops the client

Every example below starts from this instance.

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

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

track

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

Parameter	Type	Rule
`eventName`	`string`	The event name.
`properties`	`Record<string, unknown>`	Optional key-value pairs.
`event`	`GrainEvent`	An object with `eventName`, and optional `userId`, `properties`, and `timestamp`.
`options.flush`	`boolean`	Optional. `true` sends the event now instead of with the next batch.

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

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

Read Track an event for batching and delivery.

identify

identify(userId: string): void

Parameter	Type	Rule
`userId`	`string`	Your identifier for the user. Every later event carries it.

grain.identify('user_123');

setUserId

setUserId(userId: string | null): void

Parameter	Type	Rule
`userId`	`string \| null`	Your identifier for the user. `null` clears it.

grain.setUserId('user_123');
grain.setUserId(null);

getUserId

getUserId(): string | null

This method has no parameters. It returns null when no user ID is set.

const userId = grain.getUserId();

getEffectiveUserId

getEffectiveUserId(): string

This method has no parameters. It returns the user ID that you set, or the anonymous ID that the client generated. The anonymous ID is a daily rotating ID in cookieless mode and a permanent ID after consent. Read Identify users.

const id = grain.getEffectiveUserId();

getSessionId

getSessionId(): string

This method has no parameters. The session ID is in memory only before consent and persistent after consent.

const sessionId = grain.getSessionId();

login(options: LoginOptions): void

Parameter	Type	Rule
`options.userId`	`string`	Optional. Sets the user ID.
`options.authToken`	`string`	Optional. Sets the JWT and switches `authStrategy` to `JWT`.
`options.authStrategy`	`AuthStrategy`	Optional. Overrides the strategy: `'NONE'`, `'SERVER_SIDE'`, or `'JWT'`.

grain.login({ userId: 'user_123', authToken: 'eyJhbGciOi...' });

logout

logout(): void

This method has no parameters. It clears the user ID and the token. Later events use the anonymous ID again.

grain.logout();

setProperty

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

Parameter	Type	Rule
`properties`	`Record<string, unknown>`	Key-value pairs. The client converts every value to a string.
`options.userId`	`string`	Optional. Sends the properties for this user instead of the current user.

await grain.setProperty({ plan: 'premium', location: 'US' });

await grain.setProperty({ status: 'active' }, { userId: 'user_456' });

Limit	Value	Where
Properties per request	4	`setProperty`

Read User properties.

flush

flush(): Promise<void>

This method has no parameters. It sends every queued event now. Call it before a page navigation, before a serverless function returns, and before the application closes.

await grain.flush();

grantConsent

grantConsent(categories?: string[]): void

Parameter	Type	Rule
`categories`	`string[]`	Optional. For example `['analytics', 'functional']`.

grain.grantConsent(['analytics', 'functional']);

A grant switches the identity from a daily rotating ID to a permanent ID. Read Privacy and consent.

revokeConsent

revokeConsent(categories?: string[]): void

Parameter	Type	Rule
`categories`	`string[]`	Optional. Without it, the client revokes every category.

grain.revokeConsent();

getConsentState

getConsentState(): ConsentState | null

This method has no parameters. It returns null when the user made no consent decision.

const state = grain.getConsentState();

hasConsent

hasConsent(category?: string): boolean

Parameter	Type	Rule
`category`	`string`	Optional. Without it, the client reports the general consent.

if (grain.hasConsent('analytics')) {
  grain.setUserId('user_123');
}

onConsentChange

onConsentChange(listener: (state: ConsentState) => void): void

Parameter	Type	Rule
`listener`	`(state: ConsentState) => void`	Runs after every grant and revoke.

const listener = (state) => {
  console.log(state.granted, state.categories);
};

grain.onConsentChange(listener);

offConsentChange

offConsentChange(listener: (state: ConsentState) => void): void

Parameter	Type	Rule
`listener`	`(state: ConsentState) => void`	The same function reference that you passed to `onConsentChange`.

grain.offConsentChange(listener);

destroy

destroy(): void

This method has no parameters. It sends the queued events, removes the event listeners, stops the timers, and stops the configuration refresh. When the application unmounts, call it.

grain.destroy();

​Grain Tag

​init

​getInstance

​isInitialized

​track

​identify

​destroy

​consent.grant

​consent.revoke

​consent.status

​flush

​isReady

​updateDataLayerConnectors

​Analytics Web

​track

​identify

​setUserId

​getUserId

​getEffectiveUserId

​getSessionId

​login

​logout

​setProperty

​flush

​grantConsent

​revokeConsent

​getConsentState

​hasConsent

​onConsentChange

​offConsentChange

​destroy

Grain Tag

init

getInstance

isInitialized

track

identify

destroy

consent.grant

consent.revoke

consent.status

flush

isReady

updateDataLayerConnectors

Analytics Web

track

identify

setUserId

getUserId

getEffectiveUserId

getSessionId

login

logout

setProperty

flush

grantConsent

revokeConsent

getConsentState

hasConsent

onConsentChange

offConsentChange

destroy