Configuration methods

Remote configuration is an Analytics Web feature. Every method on this page is a member of a GrainAnalytics instance. Every configuration value is a string. Read Remote configuration for the cache-first model.

Method	Returns	Reads from
`getConfig(key)`	`string \| undefined`	Cache, then `defaultConfigurations`
`getAllConfigs()`	`Record<string, string>`	Cache, then `defaultConfigurations`
`getConfigAsync(key, options?)`	`Promise<string \| undefined>`	Cache, then the API
`getAllConfigsAsync(options?)`	`Promise<Record<string, string>>`	Cache, then the API
`fetchConfig(options?)`	`Promise<RemoteConfigResponse \| null>`	The API
`preloadConfig(immediateKeys?, properties?)`	`Promise<void>`	The API, into the cache
`addConfigChangeListener(listener)`	`void`
`removeConfigChangeListener(listener)`	`void`

Every example below starts from this instance.

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

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

getConfig

getConfig(key: string): string | undefined

Parameter	Type	Rule
`key`	`string`	The configuration key.

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

The method returns without a request. It returns the cached value, then the value in defaultConfigurations, then undefined. It starts a background refresh.

getAllConfigs

getAllConfigs(): Record<string, string>

This method has no parameters. It returns every cached key merged with defaultConfigurations, without a request.

const configs = grain.getAllConfigs();

getConfigAsync

getConfigAsync(key: string, options?: RemoteConfigOptions): Promise<string | undefined>

Parameter	Type	Rule
`key`	`string`	The configuration key.
`options`	`RemoteConfigOptions`	Optional. Read the field table under `RemoteConfigOptions` below.

const value = await grain.getConfigAsync('hero_text', {
  properties: { plan: 'premium', location: 'US' },
});

If the cache holds the key and forceRefresh is not true, the promise resolves from the cache. Otherwise the client calls the API.

getAllConfigsAsync

getAllConfigsAsync(options?: RemoteConfigOptions): Promise<Record<string, string>>

Parameter	Type	Rule
`options`	`RemoteConfigOptions`	Optional.

const configs = await grain.getAllConfigsAsync({ forceRefresh: true });

fetchConfig

fetchConfig(options?: RemoteConfigOptions): Promise<RemoteConfigResponse | null>

Parameter	Type	Rule
`options`	`RemoteConfigOptions`	Optional.

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

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

The method always calls the API and returns the full response. It resolves to null when the request fails.

preloadConfig

preloadConfig(immediateKeys?: string[], properties?: Record<string, string>): Promise<void>

Parameter	Type	Rule
`immediateKeys`	`string[]`	Optional. The keys to load. Without it, the client loads every key.
`properties`	`Record<string, string>`	Optional. User properties for personalization.

await grain.preloadConfig(['hero_text', 'button_color']);

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

Call preloadConfig at application start, before the first render. After it resolves, getConfig returns the loaded values without a request.

addConfigChangeListener

addConfigChangeListener(listener: ConfigChangeListener): void

Parameter	Type	Rule
`listener`	`(configurations: Record<string, string>) => void`	Runs with the full configuration object after every cache update.

const listener = (configurations) => {
  console.log(configurations);
};

grain.addConfigChangeListener(listener);

The listener runs after a background refresh, after a manual fetchConfig or forceRefresh, and after every other cache update.

removeConfigChangeListener

removeConfigChangeListener(listener: ConfigChangeListener): void

Parameter	Type	Rule
`listener`	`ConfigChangeListener`	The same function reference that you passed to `addConfigChangeListener`.

grain.removeConfigChangeListener(listener);

When the component unmounts, remove the listener. Remove it before destroy too.

RemoteConfigOptions

interface RemoteConfigOptions {
  immediateKeys?: string[];
  properties?: Record<string, string>;
  userId?: string;
  forceRefresh?: boolean;
  currentUrl?: string;
}

Field	Type	Meaning
`immediateKeys`	`string[]`	The keys that the API must resolve in this response.
`properties`	`Record<string, string>`	User properties. The dashboard rules match on them.
`userId`	`string`	Overrides the user ID for this request.
`forceRefresh`	`boolean`	`true` skips the cache and calls the API.
`currentUrl`	`string`	The page URL that the API uses for URL-scoped rules.

RemoteConfigResponse

interface RemoteConfigResponse {
  userId: string;
  snapshotId: string;
  configurations: Record<string, string>;
  isFinal: boolean;
  qualifiedSegments: string[];
  qualifiedRuleSets: string[];
  timestamp: string;
  isFromCache: boolean;
  autoTrackingConfig?: {
    interactions: Array<{
      eventName: string;
      description: string;
      selector: string;
      priority: number;
      label: string;
    }>;
    sections: Array<{
      sectionName: string;
      description: string;
      sectionType: string;
      selector: string;
      importance: number;
    }>;
  };
}

Field	Type	Meaning
`userId`	`string`	The user ID that the API resolved the values for.
`snapshotId`	`string`	The identifier of the configuration snapshot.
`configurations`	`Record<string, string>`	The configuration values.
`isFinal`	`boolean`	`false` when more values can arrive in a later response.
`qualifiedSegments`	`string[]`	The segments that the user matched.
`qualifiedRuleSets`	`string[]`	The rule sets that the user matched.
`timestamp`	`string`	The time of the response.
`isFromCache`	`boolean`	`true` when the values came from the local cache.
`autoTrackingConfig`	object	The interactions and sections that the dashboard defined for automatic tracking. Optional.

SDK reference

Query API

getConfig

getAllConfigs

getConfigAsync

getAllConfigsAsync

fetchConfig

preloadConfig

addConfigChangeListener

removeConfigChangeListener

RemoteConfigOptions

RemoteConfigResponse

​getConfig

​getAllConfigs

​getConfigAsync

​getAllConfigsAsync

​fetchConfig

​preloadConfig

​addConfigChangeListener

​removeConfigChangeListener

​RemoteConfigOptions

​RemoteConfigResponse

getConfig

getAllConfigs

getConfigAsync

getAllConfigsAsync

fetchConfig

preloadConfig

addConfigChangeListener

removeConfigChangeListener

RemoteConfigOptions

RemoteConfigResponse