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.

​
Nothing renders in FirstflowWidget

Work through this checklist in order:
1

Check experience status

In the Dashboard, verify the experience status is active. Draft experiences are never returned by the SDK.
2

Verify config is loading

Open browser DevTools → Network. Filter for config. You should see a GET /agents/your-agent-id/config request returning 200.If it returns 401: your API key is wrong or expired. If it returns 404: the agent ID doesn’t exist.
3

Check trigger conditions

chat_opens fires once per session. If you refreshed after it already fired, it won’t fire again until the session resets. Open a new incognito window to test.after_user_message requires the user to send a message. custom_event requires calling firstflow.analytics.track("your-event-name").
4

Check frequency limits

If set to once, the SDK records the show in localStorage and won’t show again. Clear frequency records to reset:
Object.keys(localStorage)
  .filter((k) => k.startsWith("ff_exp_"))
  .forEach((k) => localStorage.removeItem(k));
Then reload the page.
5

Check audience targeting

If the experience is not set to Everyone, verify:
  • You’re passing a user prop to FirstflowProvider
  • The user’s traits match the configured segment or rules
  • For segment-based audience, the user’s segment membership is being returned in the config response
6

Check device targeting

If set to desktop or mobile, verify the user agent matches. Device detection uses navigator.userAgent.

​
Config fetch errors

401 Unauthorized Your API key is invalid, expired, or doesn’t belong to the specified agent’s organization.
  1. Check the API key in Dashboard → Agent → Settings → API Keys
  2. Verify agentId matches the agent the key was created for
  3. Rotate the key and update your environment variable
404 Not Found The agent ID doesn’t exist or the agent was deleted. Provider shows fallback indefinitely The config fetch likely failed silently. Add an onError handler to surface the error: 
<FirstflowProvider
  agentId="..."
  apiKey="..."
  onError={(err) => console.error("[Firstflow config error]", err)}
>

​
useFirstflow must be used within FirstflowProvider

The component calling useFirstflow() is not a descendant of FirstflowProvider. Common causes:
  • The provider is inside a route that doesn’t wrap the component using the hook
  • Multiple React instances in the bundle (common with monorepos or CDN-loaded React)
Verify the component tree: FirstflowProvider must be an ancestor of every component that calls useFirstflow() or uses FirstflowWidget.

​
Experiences appear but look wrong

CSS conflicts The SDK injects its own scoped CSS. If your app’s global styles override * or common class names, they may bleed in. Scope your overrides or use the CSS custom properties: 
/* Override via custom properties instead of targeting SDK classes */
:root {
  --ff-accent-color: #your-brand-color;
}
Wrong color scheme Force the appearance mode if OS detection isn’t correct: 
<FirstflowWidget appearance="light">

​
Survey questions don’t appear

  • Confirm the experience type is Survey (not Tour or Announcement)
  • Confirm questions are configured in the flow editor (add message nodes with survey question types)
  • If using node trigger conditions, verify the conditions are met for the user

​
Analytics events missing from Dashboard

Events are batched and processed with a 1–2 minute delay. If events are still missing:
  1. Check the Network tab for track requests to api.firstflow.app
  2. Verify the provider has loaded config before analytics.track() is called
  3. Check for CORS errors — your domain must be allowed in the Dashboard settings
Custom events not triggering experiences The custom_event trigger fires when the event name exactly matches the configured value. Event names are case-sensitive. 
// Dashboard: event name = "checkout_completed"
firstflow.analytics.track("checkout_completed"); // ✓ matches
firstflow.analytics.track("Checkout_Completed"); // ✗ no match

​
Performance

Config fetch adds latency to app startup Use the Next.js SDK with getFirstflowConfig() to prefetch server-side. For React apps, the config is cached in memory — subsequent mounts within 5 minutes are instant. Large bundle size The SDK tree-shakes. Only import components you use: 
// ✓ Only bundles what you import
import { FirstflowProvider, FirstflowWidget } from "@firstflow/react";

// ✗ Imports everything
import * as Firstflow from "@firstflow/react";

​
React Native

Metro can’t resolve @firstflow/react-native 
// metro.config.js
const path = require("path");
config.resolver.extraNodeModules = {
  ...config.resolver.extraNodeModules,
  "@firstflow/react-native": path.resolve(
    __dirname,
    "node_modules/@firstflow/react-native"
  ),
};
Frequency resets on every app launch AsyncStorage is not installed or not linked. Install it and run pod install for iOS: 
npm install @react-native-async-storage/async-storage
cd ios && pod install

​
Getting help

  1. Check the Dashboard for agent status, active experiences, and analytics
  2. Review the FAQ for common questions
  3. Open your browser’s Network tab and look for api.firstflow.app requests
  4. Check the browser console for SDK error messages