How to Integrate Bolt.new with FullStory

Before adding FullStory to your Bolt app, you need your Org ID from the FullStory dashboard. Log into app.fullstory.com, click the settings gear in the bottom-left corner, and navigate to Settings → General. Your Org ID appears near the top — it is a string like 'o-1XXXXX-na1' or a shorter alphanumeric code depending on your account region. Copy it. You have two equivalent options for installing FullStory in a Bolt app. Option 1 is the HTML snippet approach: paste a script tag into your HTML's head section. This is the simplest method and requires no npm installation. Option 2 is the @fullstory/browser npm package: install via npm and initialize in your JavaScript/TypeScript code. The npm package is preferred for Bolt because it works cleanly with TypeScript types, integrates naturally with React component lifecycle, and keeps your HTML template clean. An important FullStory behavior to understand: FullStory does not capture sessions in localhost by default — it captures sessions on your deployed domain. However, you can test that the snippet loads correctly and doesn't throw errors in the Bolt WebContainer preview. During local/preview development, FullStory will receive the initialization call but may throttle or skip recording depending on your plan settings. To enable localhost/preview recording for development, log into FullStory Settings → Privacy → and ensure your preview URL is allowed. Check the browser console for 'FullStory initialized' messages to confirm the script loaded correctly.

1// lib/fullstory.ts
2import * as FullStory from '@fullstory/browser';
3
4let initialized = false;
5
6export function initFullStory() {
7  const orgId = import.meta.env.VITE_FULLSTORY_ORG_ID;
8
9  if (!orgId) {
10    console.warn('FullStory: VITE_FULLSTORY_ORG_ID is not set');
11    return;
12  }
13
14  if (initialized) return;
15
16  FullStory.init({ orgId, devMode: import.meta.env.DEV });
17  initialized = true;
18  console.log('FullStory initialized with org:', orgId);
19}
20
21export { FullStory };
22
23// .env
24// VITE_FULLSTORY_ORG_ID=YOUR_ORG_ID_HERE

With the @fullstory/browser package installed and lib/fullstory.ts created, you need to call initFullStory once when your app loads. In a React app, the right place is either main.tsx (the entry point, called before React renders) or in the top-level App component using a useEffect with an empty dependency array. For Vite React apps (Bolt's default), main.tsx is the cleanest option — import and call initFullStory before ReactDOM.createRoot renders. This ensures FullStory is initialized before any user interaction can occur, so no early clicks are missed. For Next.js apps, place the initialization in a client component — for example a FullStoryProvider component rendered inside the root layout's body. Use 'use client' at the top and a useEffect hook. This is necessary because Next.js renders on the server first, and FullStory requires a browser environment (window, document) to initialize. Calling it directly in a Server Component would crash at build time. After initialization, FullStory automatically captures all click events, scroll positions, mouse movements, and DOM mutations. You do not need to instrument individual components. The session replay recording starts immediately and is viewable in the FullStory dashboard within a few seconds of your first page view on a published domain. Note: the WebContainer preview URL (the bolt.new iframe URL) is treated differently than a production domain by FullStory's recording logic — some recording features require a properly deployed URL. Deploy to Bolt Cloud or Netlify for full session capture.

1// main.tsx (Vite React)
2import React from 'react';
3import ReactDOM from 'react-dom/client';
4import App from './App';
5import './index.css';
6import { initFullStory } from './lib/fullstory';
7
8initFullStory();
9
10ReactDOM.createRoot(document.getElementById('root')!).render(
11  <React.StrictMode>
12    <App />
13  </React.StrictMode>
14);
15
16// components/providers/FullStoryProvider.tsx (Next.js)
17'use client';
18
19import { useEffect } from 'react';
20import { initFullStory } from '@/lib/fullstory';
21
22export function FullStoryProvider({ children }: { children: React.ReactNode }) {
23  useEffect(() => {
24    initFullStory();
25  }, []);
26
27  return <>{children}</>;
28}

Anonymous session replay is useful, but linking sessions to actual user accounts transforms FullStory into a customer support and debugging superpower. With user identification, you can search FullStory for 'show me all sessions from user@example.com', watch the journey of a specific user who filed a support ticket, and build segments based on user properties like plan tier or account age. FullStory's identify() function takes a unique user ID as the first argument and an optional object of user variables as the second. The user ID should be the same permanent identifier you use in your database — a UUID, a Supabase user ID, or any stable string. Do not use email as the primary identifier since users can change their email. Pass email as a user variable instead. Call identify() after your authentication state confirms a logged-in user. In a React app with Supabase Auth, this typically happens in an onAuthStateChange callback or in a useEffect that watches the session. When the user logs out, call FullStory.anonymize() to stop attributing subsequent actions to the previous user. User variables you can pass include any properties that help segment and filter sessions in the FullStory dashboard. Common examples: plan (free/pro/enterprise), accountId, signupDate, or any feature flags the user has active. These variables become searchable dimensions in FullStory's session search and user segments. The FullStory dashboard will show all sessions for a given user ID under People → Users.

1// In your auth context or auth hook
2import { FullStory } from '@/lib/fullstory';
3import { useEffect } from 'react';
4import { supabase } from '@/lib/supabase';
5
6export function useAuth() {
7  useEffect(() => {
8    const { data: { subscription } } = supabase.auth.onAuthStateChange(
9      (event, session) => {
10        if (event === 'SIGNED_IN' && session?.user) {
11          const { user } = session;
12          FullStory.identify(user.id, {
13            displayName: user.email ?? 'Unknown',
14            email: user.email ?? '',
15            plan: (user.user_metadata?.plan as string) ?? 'free',
16            createdAt: user.created_at,
17          });
18        }
19
20        if (event === 'SIGNED_OUT') {
21          FullStory.anonymize();
22        }
23      }
24    );
25
26    return () => subscription.unsubscribe();
27  }, []);
28}

FullStory's autocapture records all clicks and DOM interactions automatically, but custom events let you add business-context signals that raw DOM events cannot capture. A button click on a 'Purchase' button is captured automatically, but FullStory cannot infer whether that click succeeded, failed, or was abandoned. Custom events let you annotate the session timeline with high-level business events: 'checkout_started', 'payment_failed', 'feature_enabled', 'onboarding_completed'. Custom events in FullStory use FullStory.event(eventName, properties). Event names should be descriptive camelCase or underscore_separated strings. Properties can include any flat object of strings, numbers, or booleans — nested objects are not supported in FullStory's event schema. Property keys are case-sensitive and should be consistent across events (avoid 'planType' in one event and 'plan_type' in another). A practical pattern for Bolt apps: track key funnel steps. If your app has a signup → onboarding → activate → upgrade flow, add a FullStory event at each milestone. This creates a queryable funnel in FullStory's dashboard: 'show me all sessions where onboarding_completed fired but upgrade_initiated never fired'. These funnel insights often reveal exactly where users get stuck without needing to interpret raw click replays. Avoid over-instrumenting. Five to ten meaningful business events are more valuable than 50 low-level technical events. Focus on outcomes (completed, failed, abandoned, upgraded) rather than actions (clicked, typed, scrolled). FullStory's autocapture already handles the action layer.

1// utils/analytics.ts — centralized event tracking
2import { FullStory } from '@/lib/fullstory';
3
4export const track = {
5  signupCompleted: (method: 'email' | 'google' | 'github') => {
6    FullStory.event('signup_completed', { method });
7  },
8
9  checkoutStarted: (plan: string, priceInCents: number) => {
10    FullStory.event('checkout_started', { plan, price_cents: priceInCents });
11  },
12
13  paymentFailed: (errorCode: string, plan: string) => {
14    FullStory.event('payment_failed', { error_code: errorCode, plan });
15  },
16
17  featureFirstUse: (featureName: string) => {
18    FullStory.event('feature_first_use', { feature_name: featureName });
19  },
20
21  onboardingCompleted: (stepsCompleted: number) => {
22    FullStory.event('onboarding_completed', { steps_completed: stepsCompleted });
23  },
24};

FullStory's REST API lets you programmatically fetch session data, user session lists, and session replay URLs. This is useful for building internal support dashboards, automatically attaching FullStory replay links to support tickets in Zendesk or Intercom when a user writes in, or triggering workflows based on session signals. The FullStory REST API uses API key authentication. Generate an API key in FullStory Settings → API Keys → Create New. Give it a descriptive name ('Bolt App Backend') and copy the key immediately — it is only shown once. The base URL is https://api.fullstory.com and the primary endpoints for integration use are the Operations API for batch jobs and the Data Export API for session exports. Important: FullStory's REST API key gives full access to your session data and must never be exposed to the browser. Call the API exclusively from a Next.js API route where the key lives in process.env (server-side only). Never use VITE_FULLSTORY_API_KEY or any NEXT_PUBLIC_ prefix on this key. The most common REST API use case is fetching recent sessions for a specific user. This requires a Bolt app with Next.js (not plain Vite) for the server-side API route. When a user contacts support, pass their FullStory user ID to your API route, fetch their recent sessions, and surface the direct replay links to your support team without requiring them to log into FullStory. Note: the REST API, webhooks, and data exports require a FullStory Business or Enterprise plan — the free trial includes all features for 14 days.

1// app/api/fullstory/sessions/route.ts
2import { NextResponse } from 'next/server';
3
4export async function GET(request: Request) {
5  const { searchParams } = new URL(request.url);
6  const userId = searchParams.get('userId');
7
8  if (!userId) {
9    return NextResponse.json({ error: 'userId is required' }, { status: 400 });
10  }
11
12  const apiKey = process.env.FULLSTORY_API_KEY;
13  if (!apiKey) {
14    return NextResponse.json({ error: 'FullStory API key not configured' }, { status: 500 });
15  }
16
17  try {
18    const response = await fetch(
19      `https://api.fullstory.com/users/v1/individual/${encodeURIComponent(userId)}/sessions?limit=10`,
20      {
21        headers: {
22          Authorization: `Basic ${Buffer.from(apiKey + ':').toString('base64')}`,
23          'Content-Type': 'application/json',
24        },
25      }
26    );
27
28    if (!response.ok) {
29      const error = await response.text();
30      return NextResponse.json({ error }, { status: response.status });
31    }
32
33    const data = await response.json();
34    return NextResponse.json(data);
35  } catch (error: unknown) {
36    const e = error as { message: string };
37    return NextResponse.json({ error: e.message }, { status: 500 });
38  }
39}