This quickstart adds Trace to a React app with @trace-id/sdk-react. You wrap the app in a provider, identify the visitor when they submit a form, and send the eventId to your backend for verification.
Before you start
You need a running Trace server and a public key (pk_...) whose allowed origins include your app's URL (for example http://localhost:5173). The quick start guide covers both.
- 1
Install the SDK
npm install @trace-id/sdk-reactpnpm add @trace-id/sdk-reactyarn add @trace-id/sdk-reactbun add @trace-id/sdk-react - 2
Add the provider
Wrap your app once, near the root. The provider creates a single client for every component below it.
TSX// main.tsx import { createRoot } from 'react-dom/client'; import { IdentifyProvider } from '@trace-id/sdk-react'; import App from './App'; createRoot(document.getElementById('root')!).render( <IdentifyProvider apiKey={import.meta.env.VITE_TRACE_PUBLIC_KEY} endpoint={import.meta.env.VITE_TRACE_ENDPOINT}> <App /> </IdentifyProvider>, );.envVITE_TRACE_PUBLIC_KEY=pk_... VITE_TRACE_ENDPOINT=https://id.example.com - 3
Identify on submit
useVisitorDatareturns{ data, error, isLoading, getData }. Withimmediate: falsenothing runs until you callgetData, which is what you want for a form.TSX// SignupForm.tsx import { useVisitorData } from '@trace-id/sdk-react'; export function SignupForm() { const { getData, isLoading } = useVisitorData({ immediate: false }); async function onSubmit(e: React.FormEvent<HTMLFormElement>) { e.preventDefault(); const form = new FormData(e.currentTarget); const result = await getData({ tags: { action: 'signup' } }); // null if Trace is unavailable await fetch('/api/signup', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ ...Object.fromEntries(form), eventId: result?.eventId }), }); } return ( <form onSubmit={onSubmit}> <input name="email" type="email" required /> <button disabled={isLoading}>Create account</button> </form> ); }getDatanever throws. On failure it resolvesnulland setserror, anIdentifyErrorwith acodesuch astimeoutororigin_not_allowed.Show the visitor id while you build
Leave
immediateat its default (true) on a test page and renderdata?.visitorId. Open the page in a private window: the id stays the same. - 4
Verify on your server
Never act on what the browser sends. Your backend fetches the event with a secret key: