Skip to main content

​
JavaScript SDK

The ShieldLabs SDK is a JavaScript module loaded via CDN. It collects 30+ browser signals, sends them to the ShieldLabs pipeline, and delivers a Trust Score to your server via webhook.

​
Loading the SDK

<script type="module">
  const mod = await import('https://cdn.shieldlabs.ai/snippet.js?publicKey=YOUR_PUBLIC_KEY');
  // now use mod.checkAnonymous() or mod.checkAuthenticatedUser()
</script>
The snippet is loaded with type="module" — it uses dynamic import() which is supported in all modern browsers.

​
Methods

​
checkAnonymous(callback?)

Fingerprints the current session for an anonymous (not logged in) user. Uses session caching — if the session has not changed since the last check, the request is skipped. 
const mod = await import('https://cdn.shieldlabs.ai/snippet.js?publicKey=YOUR_PUBLIC_KEY');
mod.checkAnonymous();

// With callback:
mod.checkAnonymous((ip, requestId) => {
  console.log('Check started. IP:', ip, '| RequestID:', requestId);
});

​
checkAuthenticatedUser(userHashedId, callback?)

Fingerprints the session for a known user. Pass a stable, hashed identifier — never the raw user ID or email. Uses session caching — skipped if session unchanged. 
const userId = await sha256(currentUser.id); // hash on your side
mod.checkAuthenticatedUser(userId);

// With callback:
mod.checkAuthenticatedUser(userId, (ip, requestId) => {
  // Store requestId to correlate with incoming webhook
  sessionStorage.setItem('shield_request_id', requestId);
});

​
forceCheckAnonymous(callback?)

Same as checkAnonymous() but ignores the session cache — always sends a fresh fingerprint. 
// Use after a suspicious action, e.g. failed login attempts
mod.forceCheckAnonymous();

​
forceCheckAuthenticatedUser(userHashedId, callback?)

Same as checkAuthenticatedUser() but always sends a fresh fingerprint. 
// Use before high-risk actions
mod.forceCheckAuthenticatedUser(userId, (ip, requestId) => {
  fetch('/api/pre-checkout', {
    method: 'POST',
    body: JSON.stringify({ requestId }),
  });
});

​
Callback parameters

All methods accept an optional callback (ip: string, requestId: string) => void:
ParameterTypeDescription
ipstringThe client’s detected IP address
requestIdstringUUID of this check — matches RequestID in the webhook
Use the requestId to correlate the browser check with the incoming webhook on your server.

​
Session caching

checkAnonymous and checkAuthenticatedUser cache the last session state. A new fingerprint is only sent when:
  • The user opens a new browser tab
  • The session ID changes
  • A different userHashedId is passed
Use the force* variants to bypass caching for specific high-risk moments (checkout, withdrawal, login).

​
Framework examples

'use client';
import { useEffect } from 'react';

export function ShieldTracker({ publicKey, userHashedId }) {
  useEffect(() => {
    let cancelled = false;
    (async () => {
      const mod = await import(
        `https://cdn.shieldlabs.ai/snippet.js?publicKey=${publicKey}`
      );
      if (cancelled) return;
      userHashedId
        ? mod.checkAuthenticatedUser(userHashedId)
        : mod.checkAnonymous();
    })();
    return () => { cancelled = true; };
  }, [publicKey, userHashedId]);
  return null;
}

​
Next steps

  • SDK Events — browser-side events emitted during the check
  • Advanced — noscript beacon, hashing user IDs, force check patterns