JavaScript Quickstart

Build a small JavaScript page that identifies a visitor when they click a button. You will see the Request ID on the page and open the completed result in the analytics dashboard.

Before you start

You need a modern browser, a code editor and a website domain you can deploy to. The npm example uses a JavaScript project with a build tool, such as Vite. For a website without a build tool, use the CDN snippet. You can also explore results in the Playground before setting up a project.

1. Create a ShieldLabs account and get your API key

Start Free to create a ShieldLabs account, or sign in.
In the analytics dashboard, open Integration > Domains and add your website’s hostname.
Select the domain and open Integration > API keys.
Copy the Public Key. You will replace PUBLIC_API_KEY in step 4 with this value.

Register your test domain too if it differs from production. Domain verification is automatic once identification traffic arrives; see Domains.

2. Set up your project

If you already have a JavaScript project, continue to step 3. Otherwise, create a plain JavaScript app with Vite using a Node.js version supported by Vite:

npm create vite@latest shieldlabs-quickstart -- --template vanilla
cd shieldlabs-quickstart
npm install

Open the project in your code editor. Replace index.html with this page:

index.html

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>ShieldLabs identification</title>
  </head>
  <body>
    <main>
      <h1>Identify a visitor</h1>
      <button id="identify" type="button">Run identification</button>
      <p id="result" role="status">Ready to identify.</p>
    </main>
    <script type="module" src="/src/main.js"></script>
  </body>
</html>

3. Install the SDK

Run this in the project folder:

npm install @shieldlabs-ai/js

yarn add @shieldlabs-ai/js

pnpm add @shieldlabs-ai/js

4. Initialize ShieldLabs and identify a visitor

Replace src/main.js with the following code. Replace PUBLIC_API_KEY with the Public Key from step 1.

src/main.js

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

const options = { publicKey: 'PUBLIC_API_KEY' };
const button = document.querySelector('#identify');
const output = document.querySelector('#result');

button.addEventListener('click', async () => {
  button.disabled = true;
  output.textContent = 'Starting identification…';

  try {
    const agent = await load(options);
    const { requestId } = await agent.identify();
    output.textContent = `Request ID: ${requestId}`;
  } catch {
    output.textContent = 'Identification could not start. Check your setup and try again.';
  } finally {
    button.disabled = false;
  }
});

load() loads the browser agent. identify() starts a new check and returns its Request ID. Each click starts a new identification and counts toward your plan usage. Keep the page open while the browser sends the check.

5. Run the page and view the result

Run npm run dev to preview the page locally.
Build with npm run build and deploy the dist folder to the HTTPS domain registered in step 1.
Open that website and click Run identification. The page displays a Request ID.
In the analytics dashboard, open Analytics > Identifications, find the Request ID and open its identification card.
Review the Risk Score, risk signals and device and network details.

Use the registered domain to test the identification. Localhost can display a Request ID even when the check is rejected for an unregistered hostname. The completed result is available asynchronously; allow it to appear in the analytics dashboard.

6. Identify signed-in users

For authenticated activity, pass a stable pseudonymous account ID supplied by your backend:

const agent = await load(options);
const { requestId } = await agent.identify({
  userId: 'PSEUDONYMOUS_USER_ID',
});

Use the same value for the same account. This links its identifications and supports detection of multi-accounting, account sharing and takeovers. Accounts and identifications explains user linking.

7. Send the Request ID to your backend

In your application, send the requestId with the signup, login or checkout action. For example, after your backend implements /api/signup:

async function submitSignup(email) {
  let requestId = null;
  try {
    const agent = await load(options);
    ({ requestId } = await agent.identify());
  } catch {
    // The backend handles this action as unverified.
  }

  return fetch('/api/signup', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email, requestId }),
  });
}

/api/signup belongs to your application. Follow the Node.js guide or choose another server SDK to retrieve the identification with your Private API Key and validate it before processing the action. Keep the page open until your request has been sent. For forms that navigate on submission, start identification on interaction.

Troubleshooting

The module does not load: check your connection, content blockers and Content Security Policy.
The Request ID has no result: check the registered hostname and Public Key, and keep the page open while the check is sent.
The result is pending or unavailable: handle that state on your backend; use the server SDK’s bounded retrieval helper.

Next steps

JavaScript API reference: method options, return values and errors.

Node.js backend

Retrieve results and handle your protected action.

Signed webhooks

Receive completed results on your server.

JavaScript SDK reference

Options, background checks and form helpers.

Playground

Explore identification and risk results.

Getting started

Account and domains

Browser integration

Server integration

Billing and usage

Troubleshooting

Help

JavaScript Quickstart

Before you start

1. Create a ShieldLabs account and get your API key

2. Set up your project

3. Install the SDK

4. Initialize ShieldLabs and identify a visitor

5. Run the page and view the result

6. Identify signed-in users

7. Send the Request ID to your backend

Troubleshooting

Next steps

Node.js backend

Signed webhooks

JavaScript SDK reference

Playground

​Before you start

​1. Create a ShieldLabs account and get your API key

​2. Set up your project

​3. Install the SDK

​4. Initialize ShieldLabs and identify a visitor

​5. Run the page and view the result

​6. Identify signed-in users

​7. Send the Request ID to your backend

​Troubleshooting

​Next steps

Node.js backend

Signed webhooks

JavaScript SDK reference

Playground

Before you start

1. Create a ShieldLabs account and get your API key

2. Set up your project

3. Install the SDK

4. Initialize ShieldLabs and identify a visitor

5. Run the page and view the result

6. Identify signed-in users

7. Send the Request ID to your backend

Troubleshooting

Next steps