This guide explains how to add Fullview (session replay and AI agent) to a React or Next.js app. Fullview’s docs use plain HTML/JavaScript; here we adapt that for a component-based app and keep identity in sync with your auth state.
Fullview should load early, before your app. Use the Next.js Script component so the script is injected into the document and runs at the right time.
In your root layout (e.g. app/layout.tsx):
import Script from 'next/script'
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
<Script
src="https://install.eu1.fullview.io"
data-org="YOUR_ORG_ID"
strategy="beforeInteractive"
/>
{children}
</body>
</html>
)
}- Replace
YOUR_ORG_IDwith your Fullview organization ID. strategy="beforeInteractive"loads the script in the initial HTML and runs it before your app, which is what Fullview expects from a “head” script.
In pages/_document.tsx, add the script inside <Head>:
import { Html, Head, Main, NextScript } from 'next/document'
export default function Document() {
return (
<Html lang="en">
<Head>
<script
async
src="https://install.eu1.fullview.io"
data-org="YOUR_ORG_ID"
/>
</Head>
<body>
<Main />
<NextScript />
</body>
</Html>
)
}In public/index.html, add inside <head>:
<script async src="https://install.eu1.fullview.io" data-org="YOUR_ORG_ID"></script>Fullview identifies users via the global window.$fvIdentity. You must set it when the user signs in and update it when they sign out or when their attributes change (e.g. role, email).
Set window.$fvIdentity to an object with at least id and name:
| Property | Required | Type | Description |
|---|---|---|---|
id |
Yes | string | Unique user identifier |
name |
Yes | string | User's display name |
email |
No | string | User's email |
disableReplaysForUser |
No | boolean | Disable session replays for this user |
disableAiAgentForUser |
No | boolean | Disable AI agent for this user |
env |
No | string | Environment (e.g. production, staging) for segmentation |
roles |
No | string[] | Roles for segmentation |
| Custom fields | No | primitive | Any [key: string]: primitive for custom data |
When the user signs out, remove the identity (e.g. delete window.$fvIdentity) so Fullview treats the session as anonymous.
Use a client component that reads your auth state and updates window.$fvIdentity in a useEffect. Place it inside your auth provider so it has access to the current user.
Example (Next.js App Router with a generic auth context):
'use client'
import { useEffect } from 'react'
import { useAuth } from '@/lib/contexts/auth-context' // your auth hook
export function FullviewIdentity({ children }: { children: React.ReactNode }) {
const { user } = useAuth()
useEffect(() => {
if (typeof window === 'undefined') return
if (!user) {
delete window.$fvIdentity
return
}
window.$fvIdentity = {
id: String(user.id),
name: [user.firstName, user.lastName].filter(Boolean).join(' ') || user.email || 'Unknown',
email: user.email,
env: process.env.NODE_ENV ?? 'production',
roles: user.roles ?? [],
// add any custom fields your app needs
}
}, [user])
return <>{children}</>
}Then wrap your app with this component inside your auth provider:
// e.g. in app/providers.tsx or layout
<AuthProvider>
<FullviewIdentity>
{children}
</FullviewIdentity>
</AuthProvider>Whenever user changes (sign in, sign out, or attribute updates), window.$fvIdentity is updated or cleared. No manual calls are needed.
To avoid TypeScript errors and get autocomplete, extend the Window interface. For example in types/fullview.d.ts:
export interface FullviewIdentity {
id: string
name: string
email?: string
disableReplaysForUser?: boolean
disableAiAgentForUser?: boolean
env?: string
roles?: string[]
[key: string]: string | number | boolean | string[] | undefined
}
declare global {
interface Window {
$fvIdentity?: FullviewIdentity
}
}
export {}To avoid sending data from development or staging, only set identity in production:
useEffect(() => {
if (typeof window === 'undefined') return
if (process.env.NODE_ENV !== 'production') {
delete window.$fvIdentity
return
}
// ... set window.$fvIdentity from user
}, [user])You can use the same check before loading the Fullview script if you want to disable the SDK entirely outside production (e.g. conditionally render the Next.js Script only when process.env.NODE_ENV === 'production').
- Fullview script added (head /
beforeInteractivein root layout). -
data-orgset to your Fullview organization ID. - A client component updates
window.$fvIdentityfrom your auth state (user object). - Identity is set on sign-in and cleared on sign-out.
- Identity is updated when user attributes change (e.g. role, name, email).
- (Optional) Identity and/or script only run in production.
- (Optional) TypeScript declaration for
window.$fvIdentityadded.
1. Install SDK (in head):
<script async src="https://install.eu1.fullview.io" data-org="YOUR_ORG_ID"></script>2. Identify users:
window.$fvIdentity = {
id: 'USER_ID', // Required - string - unique user identifier
name: 'USER_NAME', // Required - string - user's name
email: '[email protected]', // Optional - string - user's email
disableReplaysForUser: false, // Optional - boolean - disables replays for the user
disableAiAgentForUser: false, // Optional - boolean - disables AI agent for the user
env: 'USER_ENV', // Optional - string - used for segmentation
roles: ['USER_ROLE'], // Optional - string[] - used for segmentation
customField: 'USER_CUSTOM_DATA', // Optional - custom fields
};- Update
window.$fvIdentitywhenever the user signs up, signs in, or changes attributes. - Replace placeholder values with your real user data.
This document translates those steps into a React/Next.js–friendly setup.