React

Identify visitors in a React app with @trace-id/sdk-react.

10 minutes

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. 1

    Install the SDK

    npm install @trace-id/sdk-react
  2. 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>,
    );
    .env
    VITE_TRACE_PUBLIC_KEY=pk_...
    VITE_TRACE_ENDPOINT=https://id.example.com
  3. 3

    Identify on submit

    useVisitorData returns { data, error, isLoading, getData }. With immediate: false nothing runs until you call getData, 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>
      );
    }

    getData never throws. On failure it resolves null and sets error, an IdentifyError with a code such as timeout or origin_not_allowed.

    Show the visitor id while you build

    Leave immediate at its default (true) on a test page and render data?.visitorId. Open the page in a private window: the id stays the same.

  4. 4

    Verify on your server

    Never act on what the browser sends. Your backend fetches the event with a secret key:

Next steps

Suggest an edit

Spotted something wrong or unclear? Tell us on GitHub and we will fix it.