JavaScript

​

Before you start

​

Get your credentials

​

Install the SDK

npm install @shieldlabs-ai/js

​

Add the integration

import { load, type LoadOptions } from '@shieldlabs-ai/js';

const options: LoadOptions = { publicKey: import.meta.env.VITE_SHIELDLABS_PUBLIC_KEY };

// Start loading the agent now, but do not await it here: the form must keep working when the
// agent cannot load (a content blocker, a network error).
load(options).catch(() => {}); // handled in the submit handler

const form = document.querySelector<HTMLFormElement>('#signup')!;
form.addEventListener('submit', async (event) => {
  event.preventDefault();
  let requestId: string | null = null;
  try {
    // load() again: it returns the loaded agent at once, waits for a load that is still running
    // and tries again after a failed one.
    const agent = await load(options);
    ({ requestId } = await agent.identify());
  } catch {
    // No identification: send the signup anyway. Your server treats it as unverified.
  }
  await fetch('/api/signup', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email: form.email.value, requestId }),
  });
});

Keep the page alive after identify() resolves. The agent posts the identification right after it hands over the request ID. Keep the page open until your own request has been sent, and do not navigate away the moment identify() resolves (for example with location.href = ... in its then callback): the agent’s post may not have gone out yet. For classic full-page form posts, start the identification early with identifyOnInteraction() (see the guide).

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