FAQ
Integration
Does the snippet slow down my page?
No. The snippet is loaded withtype="module" using dynamic import(), which is non-blocking. It runs after the page is interactive and uses async browser APIs. Typical fingerprint collection takes 50–150ms and happens in the background.
Do I need cookies or localStorage?
The snippet useslocalStorage to store the VisitorID for persistent visitor tracking. If a user clears localStorage, a new VisitorID is generated on the next visit. The snippet does not use cookies.
What happens if the snippet fails to load?
If the CDN is unavailable or the user blocks the script, no fingerprint is sent and no webhook fires. Use the noscript beacon to detect JS-disabled browsers.Can I use the snippet in a mobile app WebView?
Yes. The snippet works in WebViews. Browser fingerprinting parameters are collected from the WebView’s JavaScript context. STUN/WebRTC may not work in all WebViews — in that caseStun is not checked (+30) will fire.
Webhooks
How quickly does the webhook arrive?
Typically within 0.5–1.5 seconds of the browser completing its check. The pipeline includes: fingerprint collection (~100ms) → REST submission → scoring → webhook delivery.What if my webhook endpoint is down?
ShieldLabs does not retry failed webhook deliveries. Ensure your endpoint has high availability and responds with a2xx status within 1 second.
Why does Assing not equal Assign?
Assing is the canonical field name in the webhook payload. Use it exactly as-is when verifying the HMAC signature.
Can I verify the webhook without parsing the JSON?
The HMAC is computed over the JSON serialization of theData object. You need to parse the incoming JSON and re-serialize Data to verify. Use the code examples in Webhooks.
Scoring
Why do legitimate users sometimes score above 0?
Common reasons:- VPN users: Score 15 (
Is vpn by base ip) — this is expected - Corporate proxy: Score 20–30 (
Is datacenter,Is proxy) - Strict privacy browser (Brave, Firefox Enhanced Privacy): may block WebRTC →
Stun is not checked(+30) - Mobile hotspot: may appear as datacenter IP
What score threshold should I use?
There’s no universal answer — it depends on your use case. See the threshold recommendations in Trust Score.Can I get a score for a session that already happened?
Yes, use the debug endpoint to query historical sessions byuser_hid, visitor_id, device_id, or webrtc_ip.
Privacy
Is the snippet GDPR-compliant?
Yes. The snippet collects browser environment signals, not PII. You must hash user identifiers before passing them tocheckAuthenticatedUser(). See Privacy & GDPR.