Features
Identify users
Tell Flowgrid who is signed in. One call on your server when someone signs in, and one in the browser on every page load.
What identifying does
- A named person. Sessions, replays and events belong to someone you can name, instead of an anonymous visitor ID.
- Active users. Daily, weekly and monthly active users are counted by person, with their email and name.
- Feature flags. Rules like "plan is pro" read the traits you send with the identity.
- CRM matching. The email is matched to the contact in HubSpot, Salesforce or Zoho.
Visitors who never sign in can still be identified from the forms they fill in. See Passive identity.
On the server (recommended)
Call trackAuth from flowgrid-sdk/server where your sign-in completes. It identifies the person, sends the signup or login event and counts them as active, in one call. It runs for every sign-in method, including the ones that redirect to Google or GitHub.
1// lib/flowgrid-server.ts
2import { FlowGridServer, visitorIdFromCookies } from "flowgrid-sdk/server";
3
4export const fg = FlowGridServer.init({
5 webId: process.env.FLOWGRID_WEB_ID!,
6 apiKey: process.env.FLOWGRID_API_KEY!, // server key, never shipped to the browser
7});
8
9// In the handler that completes sign-in (OAuth callback, credential login):
10const result = await fg.trackAuth(
11 {
12 event: "login", // or "signup" for a new account
13 userId: user.id,
14 email: user.email,
15 name: user.name,
16 method: "google",
17 traits: { plan: user.plan, role: user.role },
18 },
19 { visitorId: visitorIdFromCookies(await cookies()) },
20);
21
22// Tells the browser the sign-in event is already sent.
23(await cookies()).set(result.marker.name, result.marker.value, {
24 maxAge: result.marker.maxAge,
25 path: "/",
26});visitorIdlinks the sign-in to the browser session it came from, so the person's visits before signing in belong to them too.- The
markercookie stops the browser call below from sending the same sign-in a second time. An auth event callback that can't write cookies can skip it; pass{ authEvents: false }tosetUserinstead.
The event names and methods are covered in Signups and logins, and the server setup in Server-side tracking.
In the browser
Call setUser wherever your app knows who is signed in. It is safe on every render: the SDK identifies each person once per page load and pings active users at most once a day. While auth is still loading, pass undefined and nothing happens. On sign-out, pass null.
1// components/FlowgridUser.tsx, mounted once in your root layout
2"use client";
3import { useEffect } from "react";
4import { useSession } from "next-auth/react";
5import { fg } from "@/lib/flowgrid";
6
7export function FlowgridUser() {
8 const { data: session } = useSession();
9
10 useEffect(() => {
11 const user = session?.user;
12 fg.setUser(user?.id, { email: user?.email, name: user?.name, plan: user?.plan });
13 }, [session]);
14
15 return null;
16}Why both
Feature flags keep traits in the page's memory, so after a reload they come from the next setUser call. The server call alone is enough for active users and CRM matching, but not for flags evaluated in the browser.
Traits
Traits are the properties you send with the identity: plan, role, company. Send the same keys from trackAuth and setUser. A feature flag rule like “plan is pro” reads them, and the flag editor suggests the keys your users have actually sent.
A visitor can change anything their browser sends. To gate a paid feature, decide it on the server, with the plan read from your own database:
1import { getServerFlags } from "flowgrid-sdk/server";
2
3const flags = await getServerFlags({
4 webId: process.env.FLOWGRID_WEB_ID,
5 context: { userId: user.id, attributes: { plan: user.plan } },
6});Never send secrets
Passwords, card numbers, tokens and anything you wouldn't show a teammate stay out of traits.
More on rules in Feature flags.
Active users
An active user is a signed-in person who used your product that day. Both calls above count them, so there is nothing more to set up. The numbers appear once identified users are active.
| Metric | What it means | Where you see it |
|---|---|---|
| Daily, weekly and monthly active users | Distinct people active in the last 1, 7 and 30 days | Active users widgets on your boards |
| Stickiness | Daily active users divided by monthly active users | Active users widgets on your boards |
| Trend | Active people per day, week or month | The Active users trend on your boards |
| Per person | Active days, last seen, email and name | Customer Intelligence and CRM contact records |
Lower-level calls
trackAuth and setUser are built from these. You rarely need them directly, and identifyUser on its own sends no sign-in event and counts nobody as active.
1// Identity only: no sign-in event, no active-user ping.
2fg.identifyUser(user.id, { email: user.email, name: user.name });
3
4// Redirect sign-ins, split around the redirect:
5fg.markLogin({ method: "google" }); // before leaving
6fg.completeAuth(user.id, { email: user.email, name: user.name }); // after returning
7
8// One active-user ping, at most one a day per person:
9fg.pingActiveUser(user.id, { email: user.email, name: user.name });