Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.firstflow.app/llms.txt

Use this file to discover all available pages before exploring further.

import { useFirstflow } from "@firstflow/react";
useFirstflow() returns the Firstflow platform instance. Must be called inside a component that is a descendant of FirstflowProvider.

​
Usage

import { useFirstflow } from "@firstflow/react";

function SettingsPage() {
  const firstflow = useFirstflow();

  async function handleLogin(user: User) {
    firstflow.setUser({
      id: user.id,
      email: user.email,
      traits: { plan: user.plan },
    });
  }

  function handleLogout() {
    firstflow.setUser(null);
    firstflow.reset();
  }

  function handleCheckout() {
    firstflow.analytics.track("checkout_completed", { value: 99 });
  }
}

​
Instance

​
setUser(user)

Update the current user identity and traits. Call this after login, after a plan upgrade, or any time user traits change that affect experience targeting. 
firstflow.setUser({
  id: "user_123",
  email: "user@example.com",
  traits: {
    plan: "pro",
    role: "admin",
    signedUpAt: "2024-01-01",
  },
});

// Clear the user (e.g., after logout)
firstflow.setUser(null);

​
reset()

Clears the current user, segment memberships, frequency records, and cached config. Call after logout to ensure the next user starts fresh. 
firstflow.reset();

​
refreshConfig()

Force a re-fetch of agent config from the API, bypassing the 5-minute cache. 
await firstflow.refreshConfig();

​
analytics.track(event, properties?)

Track a custom event. Custom events can trigger experiences configured with the custom_event trigger type in the Dashboard. 
firstflow.analytics.track("feature_used", { featureName: "export" });
​
event
string
required
Event name. Must match the event name configured on the experience trigger.
​
properties
Record<string, unknown>
Optional event properties. Stored alongside the event for analytics.

​
analytics.identify(userId, traits)

Identify the current user with traits. An alternative to passing user to FirstflowProvider — useful when user data is available asynchronously. 
firstflow.analytics.identify("user_123", { plan: "pro" });

​
survey.submit(options)

Submit survey answers programmatically, outside the normal widget flow. 
firstflow.survey.submit({
  experienceId: "exp_abc",
  answers: {
    nps_score: 9,
    open_feedback: "Great product",
  },
});
​
experienceId
string
required
The ID of the survey experience to submit answers for.
​
answers
Record<string, unknown>
required
Map of question ID to answer value.