Remote configuration

A remote configuration is a set of keys and string values that you create in the dashboard and read in your code. When you change a value in the dashboard, every client receives the new value at its next refresh, without a deploy. Only Analytics Web (@grainql/analytics-web) reads remote configuration. Grain Tag has no remote configuration.

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

const grain = createGrainAnalytics({
  tenantId: 'your-tenant-id',
  defaultConfigurations: {
    hero_text: 'Welcome',
    chat_enabled: 'true'
  }
});

const heroText = grain.getConfig('hero_text');

Every value is a string (Record<string, string>). A flag is the string 'true' or 'false', and a number is a string that you parse. When this page and the TypeScript types of the published package disagree, the types win.

The cache-first flow

Analytics Web never waits for the network to answer a read. One read goes through these steps.

Answer from cache or defaults

getConfig returns the value from the cache in localStorage. In Node.js the cache is in memory. If the cache holds no value, getConfig returns the value from defaultConfigurations. If neither holds the key, it returns undefined.

Fetch in the background

The read starts a background request to the API. The API applies the rules of the tenant and returns the values for this client.

Update the cache and notify listeners

When the response arrives, Analytics Web writes the values to the cache and calls every change listener with the full set of values. The next getConfig returns the new value.

Without defaultConfigurations, the first getConfig on a new browser returns undefined until the first response arrives. Set a default for every key that the UI reads on first paint.

Read a value

The synchronous methods answer from the cache and defaults. Use them in a component body and in event handlers.

const heroText = grain.getConfig('hero_text');
const all = grain.getAllConfigs();

The asynchronous methods answer from the cache first and then wait for the API when the cache holds nothing. With forceRefresh: true they skip the cache and wait for the API.

const heroText = await grain.getConfigAsync('hero_text');
const fresh = await grain.getConfigAsync('hero_text', { forceRefresh: true });
const all = await grain.getAllConfigsAsync({ properties: { plan: 'premium' } });

fetchConfig sends one request to the API and returns the full response, or null when the request fails. It also updates the cache.

const response = await grain.fetchConfig({
  immediateKeys: ['hero_text', 'chat_enabled'],
  properties: { plan: 'premium' }
});

if (response) {
  console.log(response.configurations, response.snapshotId, response.qualifiedSegments);
}

Method	Returns	Waits for the network
`getConfig(key)`	`string \| undefined`	No
`getAllConfigs()`	`Record<string, string>`	No
`getConfigAsync(key, options?)`	`Promise<string \| undefined>`	Only when the cache holds nothing, or with `forceRefresh`
`getAllConfigsAsync(options?)`	`Promise<Record<string, string>>`	Only when the cache holds nothing, or with `forceRefresh`
`fetchConfig(options?)`	`Promise<RemoteConfigResponse \| null>`	Yes
`preloadConfig(immediateKeys?, properties?)`	`Promise<void>`	Yes

Options

getConfigAsync, getAllConfigsAsync, and fetchConfig accept a RemoteConfigOptions object.

Option	Type	What it does
`immediateKeys`	`string[]`	The keys that the API returns first.
`properties`	`Record<string, string>`	User properties that the rules in the dashboard evaluate for this request.
`userId`	`string`	The user ID for this request. It replaces the ID that `setUserId` set.
`forceRefresh`	`boolean`	Skip the cache and wait for the API.
`currentUrl`	`string`	The page URL that the rules evaluate.

The response of fetchConfig holds these fields.

Field	Type	Meaning
`configurations`	`Record<string, string>`	The values for this client.
`snapshotId`	`string`	The ID of the configuration snapshot that the API served.
`qualifiedSegments`	`string[]`	The segments that matched this client.
`qualifiedRuleSets`	`string[]`	The rule sets that matched this client.
`isFinal`	`boolean`	`false` when the API can still return more values.
`isFromCache`	`boolean`	`true` when the values came from the cache.
`userId`	`string`	The user ID that the API evaluated.
`timestamp`	`string`	The time of the response.

Read Personalization for the properties option in a full example.

Preload at startup

preloadConfig waits for the API one time, then every getConfig answers from the cache. Call it after setUserId so that the API evaluates the rules for the right user. With no immediateKeys, it loads every key.

grain.setUserId('user_123');
await grain.preloadConfig(['hero_text', 'chat_enabled']);

const heroText = grain.getConfig('hero_text');

Listen for changes

A change listener receives the full set of values each time the cache updates. The cache updates after a background fetch, after a manual refresh, and after fetchConfig.

const listener = (configurations: Record<string, string>) => {
  document.getElementById('hero').textContent = configurations.hero_text;
};

grain.addConfigChangeListener(listener);
grain.removeConfigChangeListener(listener);

Remove the listener when the component unmounts or before you call destroy(). In React, useConfig and useAllConfigs register the listener for you and update the component when the value changes. Read useConfig.

Refresh and cache options

Three options of GrainConfig control the refresh timer and the cache.

const grain = createGrainAnalytics({
  tenantId: 'your-tenant-id',
  configRefreshInterval: 120000,
  configCacheKey: 'my_app_config',
  enableConfigCache: true
});

Option	Default	Where	What it does
`configRefreshInterval`	`300000` ms	`GrainConfig`	Time between background refreshes. `0` turns the timer off.
`configCacheKey`	`'grain_config'`	`GrainConfig`	The `localStorage` key of the cache.
`enableConfigCache`	`true`	`GrainConfig`	`false` turns the cache off. Every read then waits for the API.
`defaultConfigurations`	none	`GrainConfig`	The values that a read returns before the first response.

Read Configuration options for the other options.

Create a configuration in the dashboard

Open grainql.com/dashboard.
Open Dashboard > Remote Config.
Create a configuration key and set its default value.
If a segment of users must receive a different value, add a rule.
Publish.

A published change reaches a client at its next refresh, or at its next read that waits for the API.

Rules for the client

Set a default for every key that the UI reads before the first response.
Compare values as strings. 'true' is a string, not a boolean.
Call preloadConfig after setUserId when a user-specific value must be correct on first paint.
Do not put a secret in a configuration value. With authStrategy: 'NONE', anyone who holds the tenant alias can read every value.

Read Feature flags and A/B tests for the two common uses. Read Configuration methods for the signatures.

Start here

Install without code

Install with code

Track events

Dashboard

Guides

React

Advanced

Remote configuration

The cache-first flow

Read a value

Options

Preload at startup

Listen for changes

Refresh and cache options

Create a configuration in the dashboard

Rules for the client

​The cache-first flow

​Read a value

​Options

​Preload at startup

​Listen for changes

​Refresh and cache options

​Create a configuration in the dashboard

​Rules for the client

The cache-first flow

Read a value

Options

Preload at startup

Listen for changes

Refresh and cache options

Create a configuration in the dashboard

Rules for the client