Configuration options

Grain Tag takes a GrainTagConfig object in init(). Analytics Web takes a GrainConfig object in createGrainAnalytics() or new GrainAnalytics(). This page lists every option of both. When this page and the TypeScript types of the published package disagree, the types win.

Grain Tag

The hosted script at https://tag.grainql.com/v4/your-tenant-id.js calls init() with the tenant alias for you. Pass a GrainTagConfig to init() from the npm package @grainql/tag, or to window.GrainTag.init() to override the injected values.

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

init({
  tenantId: 'your-tenant-id',
  consentMode: 'opt-in',
  debug: true
});

Option	Type	Default	What it does
`tenantId`	`string`	required	The tenant alias from the dashboard.
`apiUrl`	`string`	`https://clientapis.grainql.com`	The base URL of the Grain API that receives events.
`debug`	`boolean`	`false`	Writes tag activity to the browser console.
`version`	`string`	set by the hosted script	The tag version string. The hosted script sets this value.
`consentMode`	`'auto' \| 'opt-in' \| 'opt-out'`	`'auto'`	How the tag handles consent before it stores an identifier.
`enablePageViews`	`boolean`	`true`	Turns automatic page view events on or off.
`enableHeatmaps`	`boolean`	`true`	Turns click and scroll heatmap collection on or off.
`enableSnapshots`	`boolean`	`true`	Turns DOM snapshot capture on or off.
`enableRescue`	`boolean`	`true`	Turns rescue campaigns defined in the dashboard on or off.
`enableDataLayer`	`boolean`	`false`	Turns the data layer connectors on or off.
`batchSize`	`number`	`50`	The number of queued events that starts a send.
`flushInterval`	`number`	`5000`	The time in milliseconds between automatic sends.
`retryAttempts`	`number`	`3`	The number of times the tag resends a failed request.

Read Privacy and consent for the consent modes.

Analytics Web

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

const grain = createGrainAnalytics({
  tenantId: 'your-tenant-id',
  authStrategy: 'SERVER_SIDE',
  secretKey: process.env.GRAIN_SECRET_KEY,
  batchSize: 50,
  flushInterval: 5000,
  defaultConfigurations: {
    hero_text: 'Welcome'
  }
});

Option	Type	Default	What it does
`tenantId`	`string`	required	The tenant alias from the dashboard.
`apiUrl`	`string`	`https://clientapis.grainql.com`	The base URL of the Grain API.
`authStrategy`	`'NONE' \| 'SERVER_SIDE' \| 'JWT'`	`'NONE'`	The authentication strategy for every request.
`secretKey`	`string`	none	The secret key for `SERVER_SIDE`. Never put it in browser code.
`authProvider`	`{ getToken(): Promise<string> \| string }`	none	The object that returns a token for `JWT`.
`userId`	`string`	none	The user ID for every event. `setUserId()` changes it later.
`batchSize`	`number`	`50`	The number of queued events that starts a send.
`flushInterval`	`number`	`5000`	The time in milliseconds between automatic sends. `0` turns automatic sends off.
`retryAttempts`	`number`	`3`	The number of times the SDK resends a failed request.
`retryDelay`	`number`	`1000`	The first delay in milliseconds between attempts. Each attempt doubles it.
`maxEventsPerRequest`	`number`	`160`	The largest number of events in one request.
`debug`	`boolean`	`false`	Writes batching, sends, responses, and errors to the console.
`defaultConfigurations`	`Record<string, string>`	`{}`	Configuration values that `getConfig` returns before the first fetch.
`configCacheKey`	`string`	`'grain_config'`	The `localStorage` key of the configuration cache.
`configRefreshInterval`	`number`	`300000`	The time in milliseconds between configuration refreshes. `0` turns refreshes off.
`enableConfigCache`	`boolean`	`true`	Reads and writes the configuration cache in `localStorage`.
`consentMode`	`'COOKIELESS' \| 'GDPR_STRICT' \| 'GDPR_OPT_OUT'`	`'COOKIELESS'`	How the SDK handles consent before it stores an identifier.
`waitForConsent`	`boolean`	`false`	Holds events in a queue until the user grants consent.
`disableAutoProperties`	`boolean`	`false`	Stops the SDK from adding automatic properties to events.
`allowedProperties`	`string[]`	none (keep all)	The names of the automatic properties that the SDK keeps.
`enableHeartbeat`	`boolean`	`true`	Turns the session heartbeat event on or off.
`heartbeatActiveInterval`	`number`	`120000`	The heartbeat interval in milliseconds while the user is active.
`heartbeatInactiveInterval`	`number`	`300000`	The heartbeat interval in milliseconds while the user is inactive.
`enableAutoPageView`	`boolean`	`true`	Turns automatic page view events on or off.
`stripQueryParams`	`boolean`	`true`	Removes the query string from page URLs before the SDK sends them.
`stripHash`	`boolean`	`false`	Removes the hash from page URLs before the SDK sends them.
`enableHeatmapTracking`	`boolean`	`true`	Turns click and scroll heatmap collection on or off.

Set a value in defaultConfigurations for every configuration key that the page needs before the first fetch. Read Remote configuration for the cache. Use a different configCacheKey for each instance when one page runs two Analytics Web instances. Two instances with the same key overwrite each other in localStorage. Read Authentication for authStrategy, secretKey, and authProvider. Read Automatic properties for the properties that disableAutoProperties and allowedProperties control.

Values by environment

Read the environment at start and pass different values to one configuration object.

const production = process.env.NODE_ENV === 'production';

const grain = createGrainAnalytics({
  tenantId: 'your-tenant-id',
  authStrategy: production ? 'JWT' : 'NONE',
  authProvider: production ? jwtAuthProvider : undefined,
  debug: !production,
  batchSize: production ? 50 : 10,
  flushInterval: production ? 5000 : 1000
});

Environment	`batchSize`	`flushInterval`	`retryAttempts`	Reason
High-traffic site	`100`	`10000`	`5`	Fewer requests. Events arrive later.
Real-time dashboard	`10`	`1000`	`2`	Events arrive sooner. More requests.
Serverless function	`1`	`0`	`1`	The function ends before a timer fires. Send each event with `flush: true`.

Read Performance for what each value costs.

Start here

Install without code

Install with code

Track events

Dashboard

Remote configuration

Guides

React

Advanced

Grain Tag

Analytics Web

Values by environment

​Grain Tag

​Analytics Web

​Values by environment

Grain Tag

Analytics Web

Values by environment