Skip to main content

​
JavaScript SDK

The ShieldLabs SDK is a JavaScript module loaded via CDN. It collects 30+ browser signals via MixVisit, sends an encrypted payload to rest.shieldlabs.ai, and triggers WebRTC in parallel. Your server receives the Trust Score via webhook. Only publicKey is configurable via the CDN URL query string.

​
Loading the SDK

<script type="module">
  const mod = await import('https://cdn.shieldlabs.ai/snippet.js?publicKey=YOUR_PUBLIC_KEY');
  mod.checkAnonymous();
</script>
The snippet uses type="module" and dynamic import() — supported in all modern browsers.

​
Methods

​
checkAnonymous(callback?)

Fingerprints the current session for an anonymous user. Sends a new fingerprint on every call. 
const mod = await import('https://cdn.shieldlabs.ai/snippet.js?publicKey=YOUR_PUBLIC_KEY');
mod.checkAnonymous();

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

​
checkAuthenticatedUser(userHashedId, callback?)

Same as checkAnonymous but associates the check with a hashed user ID. Pass a stable SHA-256 hash — never raw PII. 
const userId = await sha256(currentUser.id);
mod.checkAuthenticatedUser(userId, (ip, requestId) => {
  sessionStorage.setItem('shield_request_id', requestId);
});

​
forceCheckAnonymous(callback?)

Clears sessionStorage and sends a fresh fingerprint. Use before high-risk actions. 
mod.forceCheckAnonymous();

​
forceCheckAuthenticatedUser(userHashedId, callback?)

Clears sessionStorage and sends a fresh authenticated check. 
mod.forceCheckAuthenticatedUser(userId, (ip, requestId) => {
  fetch('/api/pre-checkout', {
    method: 'POST',
    body: JSON.stringify({ requestId }),
  });
});
checkAnonymous and checkAuthenticatedUser share the same implementation — only userHID differs ("anonymous" vs your hash).

​
Callback parameters

Optional callback: (ip: string, requestId: string) => void
ParameterTypeDescription
ipstringClient IP returned by REST gateway
requestIdstringUUID of this check — matches webhook RequestID
The callback fires after the REST POST completes, not when the webhook arrives. See SDK Events.

​
Avoiding duplicate checks

The SDK does not cache checks automatically. To avoid sending multiple fingerprints:
  • Call once on app init (SPA)
  • Re-call only when the authenticated user changes
  • Use forceCheck* only at high-risk moments (checkout, withdrawal)

​
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 — callback timing vs webhook
  • Advanced — noscript beacon, hashing, force check patterns