Features
Feature Usage
See which features your users actually use, complete, or abandon — without building custom analytics infrastructure. It's one plain event: fg.track("feature_usage", { featureId, featureName }). Drop it wherever a feature is used; add an action when you want to distinguish viewed / used / completed / abandoned.
Overview
Feature usage events let you answer questions like:
- What percentage of users tried the export feature this week?
- How many users started onboarding but never finished it?
- Which feature has the highest abandonment rate?
Note
Every example below imports a shared fg instance that you initialize once with FlowGrid.init({ webId, apiKey }) — shown in the next section. See the SDK Quickstart for the full setup.
Track a feature
Initialize once, then track. Call FlowGrid.init({ webId, apiKey }) a single time (e.g. in lib/flowgrid.ts) and export the instance — every later fg.track(...) reuses it:
1import { FlowGrid } from "flowgrid-sdk";
2
3// Initialize the SDK ONCE and reuse this instance everywhere.
4export const fg = FlowGrid.init({
5 webId: process.env.NEXT_PUBLIC_FLOWGRID_WEB_ID!, // treat like a private key
6 apiKey: process.env.NEXT_PUBLIC_FLOWGRID_API_KEY!, // treat like a private key
7 autoTrack: {
8 replay: true,
9 engagement: true,
10 performance: true,
11 },
12});With that in place, call fg.track("feature_usage", { featureId, featureName }) wherever a feature is used. featureId and featureName are the only required fields:
1import { fg } from "@/lib/flowgrid";
2
3// One call wherever the feature is used.
4fg.track("feature_usage", {
5 featureId: "ai-agent-builder",
6 featureName: "AI Agent Builder",
7});
8
9// Add an action to distinguish completion / abandonment:
10fg.track("feature_usage", { featureId: "ai-agent-builder", featureName: "AI Agent Builder", action: "completed" });
11fg.track("feature_usage", { featureId: "ai-agent-builder", featureName: "AI Agent Builder", action: "abandoned" });
12
13// Optional: a category to group features.
14fg.track("feature_usage", { featureId: "ai-agent-builder", featureName: "AI Agent Builder", category: "Automation" });
15
16// Script-tag installs:
17// FlowGrid.track("feature_usage", { featureId: "ai-agent-builder", featureName: "AI Agent Builder" });Note
It routes through the unified fg.track() pipeline — same routing, consent, and transport as every other event. No hidden state, no lifecycle derivation: you send exactly what you call.
Helpers
Tired of repeating the id and name? Bind the feature once with fg.defineFeature(id, name) and call the verb that describes what happened. Each verb maps to a lifecycle stage the dashboard funnel understands — a viewed feature is Discovered, a used one is Adopted:
1import { fg } from "@/lib/flowgrid";
2
3// Bind id + name (+ optional category) once.
4const agent = fg.defineFeature("ai-agent-builder", "AI Agent Builder", { category: "Automation" });
5
6agent.viewed(); // action: "viewed" → Discovered + Viewed
7agent.used({ model: "opus" }); // action: "used" → Adopted
8agent.completed(); // action: "completed" → Completed
9agent.abandoned(); // action: "abandoned" → Abandonment
10
11// One-offs without binding — same verbs on fg.features:
12fg.features.viewed("report-builder", "Report Builder");
13fg.features.used("report-builder", "Report Builder");Note
These are thin, explicit wrappers over fg.track("feature_usage", …) — no hidden state. Script-tag installs get the same: FlowGrid.defineFeature("id", "Name").used().
Actions
action is an optional property on a feature_usage event that tells the dashboard what kind of usage this was. It defaults to used:
| Action | When |
|---|---|
| viewed | Visitor opened / looked at the feature |
| used | Visitor actually used the feature (default) |
| completed | Visitor finished the feature's job successfully |
| abandoned | Visitor started but gave up |
1// Default — counts as "used":
2fg.track("feature_usage", { featureId: "report-builder", featureName: "Report Builder" });
3
4// Set an action plus any extra properties you want to attach:
5fg.track("feature_usage", {
6 featureId: "report-builder", featureName: "Report Builder",
7 action: "completed", reportType: "revenue", dateRange: "30d",
8});Note
userId and category are optional for feature usage — FlowGrid defaults userId to the visitor and category to "general", so it works for anonymous visitors with no extra fields. Pass them only to attribute usage to a known user or to group features.
Activation tracking
Track the new-user journey — signup, onboarding steps, and the first meaningful action (the "aha" moment) — with these fg.track() events.
| Event | Required props | Tracks |
|---|---|---|
| signup_completed | { userId, method, source? } | New user registered |
| onboarding_completed | { userId, totalTimeSpent, stepsCompleted } | All onboarding steps finished |
| first_action | { userId, actionName, timeSinceSignup } | "Aha" moment — first meaningful action |
1import { fg } from "@/lib/flowgrid";
2
3// Record when the account was created so durations are computed, not guessed.
4const signupAt = Date.now();
5const elapsedSeconds = () => Math.round((Date.now() - signupAt) / 1000);
6
7await fg.track("signup_completed", { userId, method: "email" });
8
9// All onboarding steps finished
10await fg.track("onboarding_completed", { userId, totalTimeSpent: elapsedSeconds(), stepsCompleted });
11
12// First meaningful action — the "aha" moment
13await fg.track("first_action", { userId, actionName: "first_event_received", timeSinceSignup: elapsedSeconds() });