> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shieldlabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Install the JS Snippet
> Install the JavaScript snippet and start identifying your users and visitors.
The ShieldLabs snippet identifies your signed-in users and anonymous visitors in the browser. It is a single **ES module** you load by dynamic `import()` from `cdn.shieldlabs.ai`, on any site or web app that runs in a browser.
The module collects 300+ device and network signals and posts them to ShieldLabs automatically. ShieldLabs derives the Visitor ID, Device ID and Risk Score on the server and delivers them by [webhook](/setup/webhooks) and the [Server API](/api/server-api). Call `checkAuthenticatedUser` with a hashed User HID for [signed-in users](#identify-signed-in-users) and `checkAnonymous` for everyone else. You correlate the browser call with the server result by the `requestID` from the optional `onInitialized` handler.
The snippet stores a long-lived first-party id under the key **`cookieID`** in both `localStorage` and a first-party cookie. That value is sent to ShieldLabs as `cookieID` and stored server-side as the Cookie ID. The Visitor ID (one device plus one cookie) is computed on the server from the Device ID and the Cookie ID and reaches your backend with each result.
**No built-in consent gate.** Calling `checkAnonymous()`, `checkAuthenticatedUser()`, or either `forceCheck*` starts identification immediately. The module does not read your cookie banner or CMP. You control when the call runs. For SDK processing you initiate on your site, you generally act as the controller and ShieldLabs as your processor, as set out in your agreement with ShieldLabs. Confirm what applicable law requires with your own counsel. See [Cookie & Tracking Policy §2](/legal/cookie-policy). This is not legal advice.
If applicable law or your policy requires prior consent, call the snippet only after consent is granted (for example from your CMP accept callback). In your own privacy and cookie notices, include the first-party `cookieID`, the device and network signals the SDK collects, your anti-fraud purpose, and, where applicable, the legal basis you rely on. Never pass directly identifying information (such as names, email addresses, or phone numbers) as the User HID.
## Install (HTML)
Add this near the top of ``. Use `type="module"` (the snippet relies on `import.meta.url` and top-level dynamic import, so it cannot run as a classic script).
```html theme={null}
```
`publicKey` is your site's Public Key, one per registered domain. It is safe to expose in page source. In the analytics dashboard, open **Integration > Install** and select the domain: its snippets already carry the Public Key (see [API keys](/setup/keys) and the [Integration](/dashboard/integration) screen).
The `
Load the snippet directly from `https://cdn.shieldlabs.ai`. Do not self-host, mirror, bundle, or pin copies of `snippet.js` or its runtime imports: the snippet and its modules receive compatibility and security updates together. The official CDN keeps these unversioned runtime files on a short revalidation policy.
The call is fully **async and non-blocking**. Several checks run in parallel while the page renders. Each export returns nothing (`void`) and never throws. Pass `{ onInitialized }` if you need the `requestID` as soon as the check starts; omit it to fire-and-forget.
## Identify signed-in users
On every page a signed-in user loads, call `checkAuthenticatedUser` with a hashed User HID instead of `checkAnonymous`. Users, account-level risk and all four High-Risk Events are built on it. Keep `checkAnonymous` for visitors who are not signed in.
```html theme={null}
```
Always pass a **hashed or pseudonymous** id to `checkAuthenticatedUser` and `forceCheckAuthenticatedUser`. Never pass a raw email or a real account id. ShieldLabs stores this value as the User HID: the key that ties identifications to the account and on which High-Risk Events are detected. Keep it irreversible to a real identity.
[High-Risk Events](/features/high-risk-events) (Multi-accounting, Account sharing, Impossible travel and Account takeover) are detected on users and are available in the analytics dashboard, the API and webhooks.
**Integration > Install** in the analytics dashboard shows both snippets for the domain you select, one for anonymous visitors and one for authenticated users, and whether the domain is reporting.
The server computes the Visitor ID, Device ID and Risk Score. Send the `requestID` to your backend, then read the result from the [webhook](/setup/webhooks) payload or the [History API](/api/server-api) (query by `request_id`).
The flow:
1. `onInitialized` receives `{ status: "initialized", requestID }` as soon as the check starts, or `{ status: "not_initialized" }` when no check runs.
2. The snippet collects signals and posts them to `rest.shieldlabs.ai`.
3. ShieldLabs scores the identification in about 300 ms and delivers **one** webhook with the final Risk Score. When follow-up network checks run, it waits for them, at most about 10 seconds.
4. Your backend matches the webhook (or History API row) to the browser call by `requestID`, and to the account by `user_hid`.
## Framework integrations
The HTML method above works anywhere. In a framework, put the same dynamic `import()` inside a lifecycle hook so it runs once on mount. Pass your Public Key in from config or props, and the hashed User HID once the user is signed in.
```html theme={null}
```
```jsx theme={null}
import { useEffect } from 'react';
export function ShieldLabsTracker({ publicKey, hashedUserId }) {
useEffect(() => {
let cancelled = false;
async function run() {
const mod = await import(
`https://cdn.shieldlabs.ai/snippet.js?publicKey=${publicKey}`
);
if (cancelled) return;
if (hashedUserId) {
mod.checkAuthenticatedUser(hashedUserId);
} else {
mod.checkAnonymous();
}
}
run();
return () => { cancelled = true; };
}, [publicKey, hashedUserId]);
return null; // renders nothing
}
```
A client component loads the module after hydration. The `webpackIgnore` comment keeps the bundler from resolving the CDN URL, so the browser imports it directly.
```tsx components/ShieldLabsTracker.tsx theme={null}
'use client';
import { useEffect } from 'react';
const PUBLIC_KEY = process.env.NEXT_PUBLIC_SHIELDLABS_PUBLIC_KEY;
export function ShieldLabsTracker({ hashedUserId }: { hashedUserId?: string }) {
useEffect(() => {
let cancelled = false;
async function run() {
const mod = await import(
/* webpackIgnore: true */
`https://cdn.shieldlabs.ai/snippet.js?publicKey=${PUBLIC_KEY}`
);
if (cancelled) return;
if (hashedUserId) {
mod.checkAuthenticatedUser(hashedUserId);
} else {
mod.checkAnonymous();
}
}
run();
return () => { cancelled = true; };
}, [hashedUserId]);
return null;
}
```
Mount it once in the root layout (App Router). Where your session is known, pass the hashed User HID as `hashedUserId`, so signed-in users are identified with `checkAuthenticatedUser`:
```tsx app/layout.tsx theme={null}
import { ShieldLabsTracker } from '@/components/ShieldLabsTracker';
import { getHashedUserId } from '@/lib/session'; // your session helper
export default async function RootLayout({ children }: { children: React.ReactNode }) {
// the hashed User HID of the signed-in user, undefined for visitors who are not signed in
const hashedUserId = await getHashedUserId();
return (
```ts theme={null}
import { Injectable } from '@angular/core';
@Injectable({ providedIn: 'root' })
export class ShieldLabsService {
// memoize so the module loads only once across the app
private modulePromise?: Promise;
async check(publicKey: string, hashedUserId?: string) {
if (!this.modulePromise) {
this.modulePromise = import(
/* @vite-ignore */
`https://cdn.shieldlabs.ai/snippet.js?publicKey=${publicKey}`
);
}
const mod = await this.modulePromise;
if (hashedUserId) {
mod.checkAuthenticatedUser(hashedUserId);
} else {
mod.checkAnonymous();
}
}
}
```
```vue theme={null}
```
```jsx theme={null}
import { useEffect } from 'preact/hooks';
export function ShieldLabsTracker({ publicKey, hashedUserId }) {
useEffect(() => {
let cancelled = false;
async function run() {
const mod = await import(
`https://cdn.shieldlabs.ai/snippet.js?publicKey=${publicKey}`
);
if (cancelled) return;
if (hashedUserId) {
mod.checkAuthenticatedUser(hashedUserId);
} else {
mod.checkAnonymous();
}
}
run();
return () => { cancelled = true; };
}, [publicKey, hashedUserId]);
return null;
}
```
```svelte theme={null}
```
Save as `wp-content/plugins/shieldlabs-snippet/shieldlabs-snippet.php`, activate in **Plugins**, then visit any front-end page. The snippet runs from `wp_footer` as an ES module. Do not enqueue it with `wp_enqueue_script` (classic scripts cannot load the module).
**Anonymous visitors**
```php theme={null}
ID . wp_salt('auth'));
$snippet_url = 'https://cdn.shieldlabs.ai/snippet.js?publicKey=' . rawurlencode(SHIELDLABS_PUBLIC_KEY);
?>
If you use full-page cache (WP Rocket, LiteSpeed Cache, etc.), either exclude logged-in sessions from cache or use one combined plugin that picks `checkAnonymous` vs `checkAuthenticatedUser` per request. After login, call `forceCheckAuthenticatedUser` from a small inline script on the post-login page if you need an immediate re-check.
**Site-wide:** Tilda → **Site Settings** → **Code insertion** → **HTML code for insertion inside HEAD** → **Edit code**, then paste the snippet and republish.
**One page:** add block **T123** (Other → HTML) at the bottom of the page.
**Anonymous visitors**
```html theme={null}
```
**Logged-in users (Tilda Members or custom login):** pass a hashed id only. Tilda does not expose a stable member id in the page by default; set it yourself after login (`localStorage` or `window.__shieldlabsUserHid`), then run the check on member pages:
```html theme={null}
```
Tilda hosts the site, so you normally do not configure CSP yourself. After editing site HTML, use **Publish all pages** so the code appears on every page.
**Online Store → Themes → ⋯ → Edit code → `layout/theme.liquid`**: paste before ``, then **Save**.
**Anonymous visitors**
```liquid theme={null}
{% assign shieldlabs_public_key = 'YOUR_PUBLIC_KEY' %}
{% assign shieldlabs_snippet_url = 'https://cdn.shieldlabs.ai/snippet.js?publicKey=' | append: shieldlabs_public_key %}
```
**Logged-in customers:** hash the Shopify customer id; never pass email, name, or the raw numeric id.
```liquid theme={null}
{% if customer %}
{% assign user_hashed_id = customer.id | append: shop.permanent_domain | sha256 %}
{% assign shieldlabs_public_key = 'YOUR_PUBLIC_KEY' %}
{% assign shieldlabs_snippet_url = 'https://cdn.shieldlabs.ai/snippet.js?publicKey=' | append: shieldlabs_public_key %}
{% endif %}
```
**Both flows in one block** (recommended for most themes):
```liquid theme={null}
{% assign shieldlabs_public_key = 'YOUR_PUBLIC_KEY' %}
{% assign shieldlabs_snippet_url = 'https://cdn.shieldlabs.ai/snippet.js?publicKey=' | append: shieldlabs_public_key %}
```
`theme.liquid` runs on the **Online Store** only. Shopify **Checkout** is a separate host with its own strict CSP, so handle checkout with server-side checks (order webhooks, Shopify Flow or a custom app).
Memoize the import (the Angular example caches `modulePromise`) so the module loads once even if you mount the wrapper in several places. The framework wrappers are thin: they call the same CDN module as the HTML method, just from your app code instead of an inline script.
## Capturing the `requestID` with `onInitialized`
Pass `{ onInitialized }` in any framework to grab the `requestID` and hand it to your backend:
```jsx theme={null}
useEffect(() => {
let cancelled = false;
async function run() {
const mod = await import(
`https://cdn.shieldlabs.ai/snippet.js?publicKey=${publicKey}`
);
if (cancelled) return;
mod.checkAuthenticatedUser(hashedUserId, {
onInitialized: (result) => {
if (result.status !== 'initialized') return;
const requestID = result.requestID;
// forward requestID to your server, which reads the Risk Score from the
// webhook or the History API and chooses allow, step up, review or block.
fetch('/api/shieldlabs/checked', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ requestID }),
});
},
});
}
run();
return () => { cancelled = true; };
}, [publicKey, hashedUserId]);
```
Inside the five-minute window this call runs no identification, so `onInitialized` receives `{ status: "not_initialized" }` and there is no `requestID` to forward. Where a server-side decision needs a fresh result (login, checkout, a password change), call `forceCheckAuthenticatedUser` or `forceCheckAnonymous` at that moment instead.
ShieldLabs returns a Risk Score and every named risk signal on each identification, and detects High-Risk Events on your users. You choose the action for each case (allow, step up, review or block) and act on the result in your backend; [acting on results](/guides/acting-on-risk-score) walks each path.
## Next steps
Allowlist the ShieldLabs snippet hosts if your site sends a strict CSP header.
Find your domain's Public Key for the snippet, and the Private API Key and Secret Key for the server.
Receive the scored result keyed by `requestID`, one webhook per identification.
Users, devices, visitors and IPs, and the identification behind each Risk Score.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.
