Personalization

Personalization returns a different configuration value to each user, based on the properties of that user. Your code sends the properties. A rule in the dashboard evaluates them and returns the matching value. Personalization uses Analytics Web (@grainql/analytics-web). Grain Tag has no remote configuration. Read Remote configuration for the cache-first flow.

The two inputs

A rule reads properties from two places.

Input	Method	Where the values live	When to use it
Stored user properties	`setProperty(properties, { userId? })`	On the user profile in Grain, for every later request	Properties that change rarely: plan, country, signup date.
Request properties	The `properties` option of `getConfigAsync`, `getAllConfigsAsync`, `fetchConfig`, `useConfig`, and `useAllConfigs`	In one request only	Properties that the page computes: days since signup, login count.

setProperty converts every value to a string. The properties option accepts only strings (Record<string, string>), so convert a number with toString() before you pass it. Rules compare strings. Read User properties. Set the user ID before you set properties, so that the properties attach to the right user.

import { useEffect } from 'react';
import { useGrainAnalytics } from '@grainql/analytics-web/react';

function App({ user }) {
  const grain = useGrainAnalytics();

  useEffect(() => {
    grain.setUserId(user.id);
    grain.setProperty({
      plan: user.plan,
      country: user.country,
      signup_date: user.signupDate
    });
  }, [user, grain]);

  return <AppContent />;
}

Read Identify users for setUserId.

A message by plan

The rule reads one property and returns one string per plan.

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

function Hero({ plan }: { plan: string }) {
  const { value: message } = useConfig('hero_message', {
    properties: { plan }
  });

  return <h1>{message}</h1>;
}

In the dashboard, create the key hero_message with the default value Welcome. Then add one rule per plan: if plan equals premium, return Welcome back, premium member. A user with no matching rule receives the default.

A price by country

Two keys share the same property. Each key has its own rules.

function Pricing({ country }: { country: string }) {
  const { value: currency } = useConfig('currency', { properties: { country } });
  const { value: price } = useConfig('monthly_price', { properties: { country } });

  return <p>{currency}{price} per month</p>;
}

Rules in the dashboard: if country equals US, currency returns $ and monthly_price returns 29. If country equals GB, currency returns £ and monthly_price returns 24. The price is a string. Parse it before you compute with it. A computed number goes in the request as a string. The rule compares it as a number.

function Dashboard({ loginCount }: { loginCount: number }) {
  const { value: showTutorial } = useConfig('show_tutorial', {
    properties: { login_count: loginCount.toString() }
  });

  return (
    <>
      {showTutorial === 'true' && <Tutorial />}
      <MainContent />
    </>
  );
}

Rule in the dashboard: if login_count is less than 5, show_tutorial returns true. The default value is false.

Feature access by plan

The value is not a flag but a label, so the code can show a different state for each label.

function AdvancedAnalytics({ plan }: { plan: string }) {
  const { value: access } = useConfig('analytics_access', {
    properties: { plan }
  });

  if (access !== 'granted') {
    return <UpgradePrompt />;
  }

  return <AnalyticsDashboard />;
}

Rule in the dashboard: if plan equals premium or enterprise, analytics_access returns granted. The default value is denied. Read Feature flags for the flag form of this pattern.

Rules for the client

Set a default value for every personalized key. A user with no matching rule, and a client with no response yet, both receive the default.
Send only the properties that a rule reads. A property that no rule reads has no effect on the value.
Send only properties that the user consented to. Read Privacy and consent.
Test every rule with one user per branch: one per plan, one per country, one per side of a numeric limit.
To measure whether a personalized value converts better than the default, run it as an A/B test. Read A/B tests.

Start here

Install without code

Install with code

Track events

Dashboard

Remote configuration

Guides

React

Advanced

The two inputs

A message by plan

A price by country

Feature access by plan

Rules for the client

​The two inputs

​A message by plan

​A price by country

​A tutorial by login count

​Feature access by plan

​Rules for the client

The two inputs

A message by plan

A price by country

A tutorial by login count

Feature access by plan

Rules for the client