How to Integrate Lovable with FullStory

FullStory's session recording requires a JavaScript snippet in your HTML head that loads the recording agent from FullStory's CDN. The snippet is initialized with your unique Org ID, which identifies which FullStory organization receives the recorded sessions. Log in to your FullStory account at app.fullstory.com. Click your profile icon in the top-right corner and select Settings. Under the General section, find the 'Organization ID' — a string formatted like 'ABCDE' or '123XYZ'. This is your public Org ID, safe to include in the snippet in your HTML. To get the snippet, go to Settings → Integrations → FullStory Snippet. FullStory shows the complete script tag to add to your HTML head. The snippet is an obfuscated loader script that asynchronously loads the FullStory recording agent without blocking page rendering. It sets up the global FS object on the window, which you will use for user identification and custom event tracking. In your Lovable project, ask Lovable to add the FullStory snippet to your index.html file. The snippet belongs in the HTML head section, after the meta tags but before the closing head tag. Lovable will open the index.html file in the project editor and insert the script tag. The snippet already contains your Org ID inline — there is no environment variable needed for the snippet itself, as the Org ID is publicly visible in the HTML source and is intentionally public (like a GA4 measurement ID). For the VITE_FULLSTORY_ORG_ID environment variable — add it if you want to reference the Org ID from React components for custom event calls, but the snippet initialization itself uses the hardcoded value from FullStory's generated snippet. After adding the snippet, verify it is working by opening your app in the browser, navigating a few pages, then checking FullStory → Sessions to see if a new session appears within 30-60 seconds.

1// src/types/fullstory.d.ts
2declare global {
3  interface Window {
4    FS: {
5      identify: (uid: string, userVars?: Record<string, unknown>) => void;
6      event: (eventName: string, eventProperties?: Record<string, unknown>) => void;
7      setUserVars: (userVars: Record<string, unknown>) => void;
8      getCurrentSessionURL: (now?: boolean) => string;
9      shutdown: () => void;
10      restart: () => void;
11      log: (level: string, msg: string) => void;
12    } | undefined;
13    _fs_org?: string;
14  }
15}
16
17export {};

FullStory records sessions for anonymous users by default, assigning each visitor a random FullStory-generated ID. To make sessions searchable by your users' identities — so you can find recordings for specific customers when debugging support tickets — call FS.identify() after authentication with the user's Supabase user ID. The FS.identify() function takes two arguments: a unique user ID string (use the Supabase user UUID for consistency with your other analytics tools) and an optional object of user variables. User variables are key-value pairs that appear in FullStory's session search interface and on user profiles. Include at minimum: displayName (the user's email or name for human-readable identification in the FullStory dashboard), email (for direct email-based search), and any custom attributes relevant to your debugging needs — user plan, account age, feature flags, and any other segments you want to filter sessions by. User variable names in FullStory follow a typing convention: append _str for strings, _int for integers, _bool for booleans, and _real for floating-point numbers. For example: plan_str, days_since_signup_int, is_paying_bool. Variables without a type suffix are treated as strings. Using the typed suffix convention ensures correct sorting, filtering, and aggregation in FullStory's search interface. Create a React hook or utility function that calls FS.identify() when the Supabase auth state changes to SIGNED_IN. Call FS.shutdown() when the user logs out to stop recording the session (preventing accidental recording of the next user's activity if the same browser is reused). For React apps, put the identification call in the same auth state change handler used for other analytics tools to keep all user identification logic in one place. FS.getCurrentSessionURL() is a powerful debugging tool — call it from any component to get the URL of the current FullStory recording at the exact current moment. Store this URL in your Supabase database alongside support tickets, error logs, or user-reported bugs to enable one-click access to the relevant session recording.

1// src/hooks/useFullStory.ts
2import { useEffect } from 'react';
3import { supabase } from '@/integrations/supabase/client';
4
5export function useFullStory() {
6  useEffect(() => {
7    const { data: { subscription } } = supabase.auth.onAuthStateChange(
8      async (event, session) => {
9        if (event === 'SIGNED_IN' && session?.user) {
10          const user = session.user;
11          // Fetch user plan from profiles table
12          const { data: profile } = await supabase
13            .from('profiles')
14            .select('plan, created_at')
15            .eq('id', user.id)
16            .single();
17
18          const daysSinceSignup = profile?.created_at
19            ? Math.floor((Date.now() - new Date(profile.created_at).getTime()) / 86400000)
20            : 0;
21
22          window.FS?.identify(user.id, {
23            displayName: user.email,
24            email: user.email,
25            plan_str: profile?.plan ?? 'free',
26            days_since_signup_int: daysSinceSignup,
27          });
28        }
29        if (event === 'SIGNED_OUT') {
30          window.FS?.shutdown();
31        }
32      }
33    );
34    return () => subscription.unsubscribe();
35  }, []);
36}
37
38export function trackFullStoryEvent(
39  eventName: string,
40  properties?: Record<string, unknown>
41) {
42  window.FS?.event(eventName, properties);
43}
44
45export function getFullStorySessionURL(): string | null {
46  return window.FS?.getCurrentSessionURL(true) ?? null;
47}

FullStory's session replay becomes exponentially more valuable when you can search for sessions by what users did, not just who they are. Custom events allow you to mark specific moments in a user's session — completing onboarding, hitting an error, starting a checkout flow — making those sessions searchable and groupable in FullStory's analysis tools. Custom FullStory events use the FS.event() function with an event name string and an optional properties object. Event names in FullStory use title case by convention (like 'Checkout Started' or 'Error Encountered'). Property values support the same type suffix convention as user variables: _str, _int, _bool, _real. For example, FS.event('Feature Used', { feature_name_str: 'Export', item_count_int: 25, success_bool: true }). The most valuable custom events to add are: error states (when a user encounters a JavaScript error, API failure, or validation error — include the error message as a property), frustration-prone flows (the steps in your app where you suspect friction exists — add events at entry, progress, and exit so you can find incomplete sessions), and conversion milestones (signup completion, subscription upgrade, first key action — so you can compare the session recordings of users who convert versus users who abandon). FS.setUserVars() updates the current user's profile variables at any point during the session without re-identifying them. Use this to update the user's plan after a subscription upgrade — call FS.setUserVars({ plan_str: 'pro' }) immediately after the upgrade completes so subsequent sessions show the correct plan. For error tracking, add a global error handler that sends error information to FullStory as a custom event so all JavaScript errors generate searchable FullStory events alongside the session recording context. This connects the session replay directly to the error occurrence.

1// Add to src/App.tsx useEffect for global error tracking
2useEffect(() => {
3  function handleUnhandledRejection(event: PromiseRejectionEvent) {
4    const sessionUrl = window.FS?.getCurrentSessionURL(true);
5    console.error('Unhandled rejection:', event.reason, 'Session:', sessionUrl);
6    window.FS?.event('Unhandled Error', {
7      error_type_str: 'UnhandledPromiseRejection',
8      error_message_str: String(event.reason),
9      page_url_str: window.location.pathname,
10    });
11  }
12  window.addEventListener('unhandledrejection', handleUnhandledRejection);
13  return () => window.removeEventListener('unhandledrejection', handleUnhandledRejection);
14}, []);

FullStory's Data Export API provides programmatic access to session data, user data, and event data for building dashboards outside of FullStory's own interface. This API requires an API key (different from the Org ID) and is available on Business and Enterprise plans. The API key must be stored in Cloud → Secrets and used only from the Edge Function — never in client-side code. To get your FullStory API key, go to Settings → Integrations → API Keys in your FullStory account. Click 'Create API Key', give it a name like 'Lovable Integration', and copy the generated key. Store it as FULLSTORY_API_KEY in Lovable Cloud Secrets. FullStory's Data Export API uses GraphQL for flexible querying. The GraphQL endpoint is https://api.fullstory.com/graphql/v2. Authentication uses the Authorization header with your API key as 'Basic [base64(api_key:)]'. The colon after the key with an empty password is required — FullStory uses HTTP Basic auth format with the API key as the username. Useful GraphQL queries for a UX dashboard: sessionsV2 (query sessions by time range, user segment, or event criteria), eventCountsV2 (aggregate event counts for rage clicks, dead clicks, and custom events over time), and usersV2 (query user profiles by custom variable values). The Data Export API is designed for data warehouse integration and bulk exports, so it has different rate limits than the session recording API — check FullStory's documentation for current limits on your plan. For most Lovable dashboard use cases, the most practical approach is to use FullStory's Data Export to populate a Supabase table with aggregated metrics on a schedule, then query the Supabase table for dashboard rendering rather than calling the FullStory API on every page load. RapidDev's team can help design the optimal data export and caching architecture for complex FullStory-powered dashboards in your Lovable app.

1// supabase/functions/fullstory-data/index.ts
2import { serve } from 'https://deno.land/std@0.168.0/http/server.ts';
3
4const corsHeaders = {
5  'Access-Control-Allow-Origin': '*',
6  'Access-Control-Allow-Headers': 'authorization, x-client-info, apikey, content-type',
7};
8
9serve(async (req) => {
10  if (req.method === 'OPTIONS') return new Response('ok', { headers: corsHeaders });
11
12  try {
13    const apiKey = Deno.env.get('FULLSTORY_API_KEY');
14    if (!apiKey) {
15      return new Response(JSON.stringify({ error: 'FULLSTORY_API_KEY not configured' }), {
16        status: 500, headers: { ...corsHeaders, 'Content-Type': 'application/json' },
17      });
18    }
19
20    // FullStory uses Basic auth with API key as username and empty password
21    const credentials = btoa(`${apiKey}:`);
22    const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
23
24    const query = `
25      query GetSessionStats($start: String!) {
26        sessionsV2(filters: { createdTime: { greaterThanOrEqual: $start } }) {
27          totalCount
28        }
29      }
30    `;
31
32    const response = await fetch('https://api.fullstory.com/graphql/v2', {
33      method: 'POST',
34      headers: {
35        'Authorization': `Basic ${credentials}`,
36        'Content-Type': 'application/json',
37      },
38      body: JSON.stringify({ query, variables: { start: sevenDaysAgo } }),
39    });
40
41    const data = await response.json();
42    return new Response(JSON.stringify(data), {
43      headers: { ...corsHeaders, 'Content-Type': 'application/json' },
44    });
45  } catch (error) {
46    return new Response(JSON.stringify({ error: String(error) }), {
47      status: 500, headers: { ...corsHeaders, 'Content-Type': 'application/json' },
48    });
49  }
50});