Identify users

Every event carries a user ID. Until your code sets one, the ID is anonymous, and the SDK generates it. After identify, every later event carries the ID from your own system, and the dashboard shows the events of one user as one journey.

Methods

Method	SDK	What it does
`identify(userId)`	Grain Tag	Sets the user ID for every later event. A call before `init` is queued and replayed after `init`.
`identify(userId)`	Analytics Web	Sets the user ID for every later event.
`setUserId(userId)`	Analytics Web	Same as `identify`. `setUserId(null)` clears the user ID and returns to an anonymous ID.
`getUserId()`	Analytics Web	Returns the user ID that your code set, or `null`.
`getEffectiveUserId()`	Analytics Web	Returns the ID that the next event carries: your user ID, or the anonymous ID.
`login({ userId?, authToken?, authStrategy? })`	Analytics Web	Sets the user ID. With `authToken`, it also switches the client to `JWT` authentication.
`logout()`	Analytics Web	Clears the user ID, resets `authStrategy` to `NONE`, and returns to an anonymous ID.

Grain Tag

Grain Tag has one method. Call it after the user logs in.

GrainTag.identify('user_8f3a2c1b');
GrainTag.track('dashboard_viewed');

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

identify('user_8f3a2c1b');
track('dashboard_viewed');

Grain Tag has no method that clears the user ID. Read Track an event.

Analytics Web

Set the user ID

identify and setUserId do the same thing for a string. Use the one that reads better in your code.

grain.identify('user_8f3a2c1b');
grain.track('dashboard_viewed');
grain.track('report_generated');

When your code knows the user at construction time, pass userId in the configuration. The first event then carries it.

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

grain.track('app_opened');

Log in and log out

login sets the user ID and the authentication in one call. logout reverses both.

grain.login({ userId: 'user_8f3a2c1b' });

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

grain.logout();
grain.track('logged_out');

Option	Effect
`userId`	Sets the user ID.
`authToken`	Stores the token as the `authProvider`. If `authStrategy` is `NONE`, changes it to `JWT`.
`authStrategy`	Overrides the strategy: `NONE`, `SERVER_SIDE`, or `JWT`.

After logout, authStrategy is NONE, the authProvider is removed, and events carry an anonymous ID. Read Authentication.

Read the ID

const userId = grain.getUserId();
const effectiveUserId = grain.getEffectiveUserId();

getUserId returns null for an anonymous visitor. getEffectiveUserId always returns a string. Use it when you need the ID that Grain stores on the next event.

Anonymous IDs

When no user ID is set, Analytics Web generates one. The consent mode decides which kind.

Consent mode	Anonymous ID	Lifetime
`COOKIELESS`	Daily rotating ID, prefix `daily_`	One calendar day. The SDK stores no cookie for it.
`GDPR_STRICT` before `grantConsent()`	Daily rotating ID	One calendar day.
`GDPR_STRICT` after `grantConsent()`	Permanent ID, a UUID v4	Stored in a cookie or `localStorage` until `revokeConsent()`.
`GDPR_OPT_OUT`	Permanent ID, a UUID v4	Stored in a cookie or `localStorage` until `revokeConsent()`.

The daily rotating ID is computed from the date, the tenant alias, and a random seed. Two visits on different days get different IDs. Grain Tag uses the same two kinds of ID. Its auto consent mode is cookieless. Read Privacy and consent. Events before identify keep their anonymous ID. Only the events after the call carry your user ID.

grain.track('landing_page_viewed');
grain.track('signup_button_clicked');

grain.identify('user_8f3a2c1b');
grain.track('account_created');

Page loads

The SDK does not store your user ID across page loads. Your authentication system owns the session, so Grain does not keep a second copy. On every load, set the ID from your own session.

const currentUser = getCurrentUser();

if (currentUser) {
  grain.setUserId(currentUser.id);
} else {
  grain.setUserId(null);
}

Servers

On a server, one client serves many users. Set the user ID before each request, and flush the event inside the request.

app.post('/api/action', async (req, res) => {
  grain.setUserId(req.user.id);
  await grain.track('api_action_performed', { endpoint: '/api/action' }, { flush: true });
  res.sendStatus(200);
});

In a serverless function, create one client per invocation. Two requests then cannot share a user ID.

export async function handler(event) {
  const grain = createGrainAnalytics({
    tenantId: 'your-tenant-id',
    userId: event.userId,
  });

  await grain.track('function_ran', {}, { flush: true });
  return { statusCode: 200 };
}

Read Node.js and servers.

React

GrainProvider takes userId in its config. When the value changes, the provider updates the client.

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

function App() {
  const { user } = useAuth();

  return (
    <GrainProvider config={{ tenantId: 'your-tenant-id', userId: user?.id }}>
      <YourApp />
    </GrainProvider>
  );
}

Read React hooks.

Rules for the client

Use an ID that does not change: a database ID or a UUID. An email address changes, and a session ID changes on every session.
Set the user ID on every page load, before the first event. The SDK does not store it.
If the user logs out, call logout() or setUserId(null). Otherwise the next user’s events go to the previous user.
Do not switch between many user IDs from one client. Grain rate-limits a source that sends many distinct IDs. Read Security.
With JWT authentication, the user ID must equal the subject of the token. The API rejects an event with a different ID.
On a server, set the user ID before each request, or create one client per request.

After you identify a user, you can store attributes on the user. Read User properties.

Start here

Install without code

Install with code

Track events

Dashboard

Remote configuration

Guides

React

Advanced

Methods

Grain Tag

Analytics Web

Set the user ID

Log in and log out

Read the ID

Anonymous IDs

Page loads

Servers

React

Rules for the client

​Methods

​Grain Tag

​Analytics Web

​Set the user ID

​Log in and log out

​Read the ID

​Anonymous IDs

​Page loads

​Servers

​React

​Rules for the client

Methods

Grain Tag

Analytics Web

Set the user ID

Log in and log out

Read the ID

Anonymous IDs

Page loads

Servers

React

Rules for the client