React

​

Before you start

​

Get your credentials

​

Install the SDK

npm install @shieldlabs-ai/react @shieldlabs-ai/js

​

Add the integration

# .env
VITE_SHIELDLABS_PUBLIC_KEY=0123456789abcdef0123456789abcdef

// main.tsx
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { ShieldLabsProvider } from '@shieldlabs-ai/react';
import { SignupForm } from './SignupForm';

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <ShieldLabsProvider publicKey={import.meta.env.VITE_SHIELDLABS_PUBLIC_KEY}>
      <SignupForm />
    </ShieldLabsProvider>
  </StrictMode>,
);

// SignupForm.tsx
import type { SyntheticEvent } from 'react';
import { useIdentify } from '@shieldlabs-ai/react';

export function SignupForm() {
  const { identify, isLoading } = useIdentify();

  async function onSubmit(event: SyntheticEvent<HTMLFormElement>) {
    event.preventDefault();
    const email = new FormData(event.currentTarget).get('email');
    // null when there is no identification (the reason is in `error`). The signup goes out anyway,
    // and your server treats it as unverified.
    const result = await identify();
    await fetch('/api/signup', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email, requestId: result?.requestId ?? null }),
    });
  }

  return (
    <form onSubmit={onSubmit}>
      <input name="email" type="email" required />
      <button disabled={isLoading}>Sign up</button>
    </form>
  );
}

Keep the page alive after identify() resolves. The agent posts the identification right after it hands over the request ID. Sending your request with fetch(), as above, keeps the page open. If you navigate right after the submit (a full-page form post or a redirect), start the identification early instead (see Protect a form ).

Test on a registered domain. ShieldLabs records identifications only for the domains registered in your account. On localhost the page still receives a requestId, but the identification is rejected with 401 and your backend never finds it. Test on a development domain with its own keys, as described in Environments.

​

Test the complete flow

1. Run the application on the registered HTTPS domain with its Public Key.
2. Trigger the protected form once and check that a Request ID is sent to your own backend.
3. Retrieve that same ID using a server SDK or locate it in the analytics dashboard.
4. Test a missing ID and an agent load failure: your backend must treat the action as unverified.

​

Troubleshooting

• No History row: confirm the registered domain, credential/environment match and that the browser remained open while collectors posted.
• Missing or pending verdict: scoring is asynchronous. The server helper waits within a bounded budget; handle a missing result and API errors explicitly.
• Authentication error: use the Private API Key for History, not a Public Key, Management Secret Key or MCP OAuth token.
• Invalid webhook signature: verify the original raw bytes with the endpoint’s full signing secret, before trusting parsed JSON.

​

Next steps

• Runnable example
• SDK reference and changelog
• Identification flow
• Server API
• Webhook setup
• Content Security Policy