FullStory Analytics Integration

This guide covers integrating FullStory session replay into the Arda Frontend Application (Next.js App Router).

Prerequisites

FullStory account access.
FullStory Organization ID (Org ID) — from Settings → General in the FullStory dashboard.

Step 1: Install

npm install @fullstory/browser

Step 2: Configure Environment Variables

Local development — add to .env.local:

NEXT_PUBLIC_FULLSTORY_ORG_ID=your_org_id_here

AWS Amplify Console (Production):

Go to the Amplify Console → Select the Arda Frontend app.
Navigate to Eco-system → Environment variables.
Add NEXT_PUBLIC_FULLSTORY_ORG_ID with the production Org ID.

Step 3: Create the FullStory Initialization Component

Create src/components/FullStoryInit.tsx:

'use client';

import { useEffect } from 'react';
import * as FullStory from '@fullstory/browser';
import { useAuth } from '@/contexts/AuthContext';

const ORG_ID = process.env.NEXT_PUBLIC_FULLSTORY_ORG_ID;

export function FullStoryInit() {
  const { user } = useAuth();

  useEffect(() => {
    if (ORG_ID) {
      FullStory.init({ orgId: ORG_ID });
    } else {
      console.warn('FullStory Org ID is missing. Analytics will not be initialized.');
    }
  }, []);

  useEffect(() => {
    if (ORG_ID && user) {
      FullStory.identify(user.id, {
        displayName: user.name,
        email: user.email,
      });
    }
  }, [user]);

  return null;
}

This component integrates with AuthContext to automatically identify logged-in users, enabling session replay correlation with specific user identities.

Step 4: Add to Root Layout

In src/app/layout.tsx, place FullStoryInit inside the AuthProvider:

import { FullStoryInit } from '@/components/FullStoryInit';

export default function RootLayout({ children }) {
  return (
    <html lang='en'>
      <body>
        <AuthProvider>
          <JWTProvider>
            <FullStoryInit />   {/* Inside AuthProvider for user context */}
            {children}
          </JWTProvider>
        </AuthProvider>
      </body>
    </html>
  );
}

Step 5: Verify

Run npm run dev.
Open the browser console — no FullStory errors should appear.
Open the Network tab and filter for fullstory. You should see requests to fs.js or rs.fullstory.com.
Log into FullStory and verify a new session appears in the “Everyone” segment.

Configuration and Best Practices

Privacy and Masking

By default FullStory captures all text. Ensure sensitive data is never recorded:

Passwords are automatically excluded.
Add the CSS class fs-mask to any HTML element containing sensitive data.
Add fs-unmask to non-sensitive inputs (e.g., search bars) if you need to see their text in recordings.

High-Priority Signals to Monitor

Create Segments or Saved Searches for:

Rage Clicks: Rapid clicking on an element — indicates user frustration or a broken UI element.
Dead Clicks: Clicks on elements that look interactive but do nothing.
Error Clicks: Clicks that result in a JavaScript console error.

Funnels and Conversion Analysis

Create funnels for key user workflows (sign-up flow, order creation) to identify drop-off points.

Custom Events

Emit custom events for major actions not captured by default:

import * as FullStory from '@fullstory/browser';

// Inside the order submission function
FullStory.event('Order Queued', {
  totalOrders: queue.length,
});

Heatmaps and Click Maps

Use “Page Insights” to view scroll maps and click maps. Scroll maps reveal whether users are reaching important calls-to-action. Click maps identify non-interactive elements being clicked.