Planning your implementation

A good ShieldLabs rollout starts with a short plan, not a snippet. ShieldLabs gives you the signals; your code decides what to do with them. This page walks the decisions to make first, so the integration goes in clean and you start acting on the Risk Score and its anonymity signals quickly. Work through five questions in order:

1. Where will you identify visitors?
2. What will you do with the Risk Score, the anonymity signals, and patterns?
3. How will you receive results reliably?
4. Where does the data and the decision live?
5. How does the snippet install, and which call do you use?

​

Pick your identification touchpoints

Identify visitors at the moments where the answer changes what you do next. Adding the check everywhere is wasteful; adding it at the decision points is where it pays off. Common high-value touchpoints:

• Signup - flag many accounts forming on one device or one local network.
• Login - recognize the returning device, spot logins from an unfamiliar one.
• Checkout and payments - score a high-value action before money moves.
• Sensitive account changes - password resets, email or payout changes, new-device approvals.

For each touchpoint, decide whether the visitor is anonymous or signed in. That choice maps directly to which snippet call you use below.

​

Decide what to do with the score

ShieldLabs returns a Risk Score from 0 to 100 plus a signals array naming every anonymity signal behind it. You write the logic that turns that into an action. There is no rules engine in the product, so the decision lives entirely in your code. Map each of the four bands the Risk Score defines (Clean 0-9, Low 10-29, Medium 30-59, High 60-100) to an action that fits the touchpoint: pass low bands through, and step up, review, or block as the score climbs. The acting on the Risk Score guide details the per-band playbook. A legitimate visitor can score high (a corporate proxy, a VPN, a privacy browser). Decide on the Risk Score plus the signals plus the action context, never the number alone. The full decision toolkit lives in Acting on the Risk Score. Patterns are a second, dashboard-only input. They point to abuse and fraud across many visits, not on one request: many accounts on one device, many devices on one account, and similar clusters. Use them to spot coordinated activity that a single score will not show.

​

Plan how you receive results

Scoring runs server-side and asynchronously: the snippet call returns a requestID right away, and the Risk Score for that check arrives a moment later (about a second). So plan for two ways to receive the result, and use both.

• Webhook (primary). ShieldLabs POSTs the scored result to your endpoint as soon as it is ready. This is the real-time path, and webhook delivery is free.
• History API (fallback). Read the same result on demand from the Server API, keyed by request_id, user_hid, device_id, and more. Each row a lookup returns bills one request, and a lookup that returns zero rows still bills one, so lean on the webhook for volume and use History where you need a guaranteed read.

Build the receiver to two rules:

• Idempotent on RequestID. Each scored identification produces one webhook: the server waits up to ~60s for optional follow-up network checks, then sends the final score once. Key your storage and your decision on RequestID so a repeat is a no-op.
• At-most-once delivery. Webhooks have no retries, so a missed POST is gone. For any decision you cannot afford to miss, fall back to the History API for a guaranteed read. The full delivery contract is on Webhooks.

​

Plan storage and where decisions live

The decision logic runs on your backend, not in ShieldLabs. Plan to store what your application needs to act and to audit later.

• Verify first. Confirm the webhook HMAC before you trust the payload, then store. Verification belongs server-side, with your secret key.
• Store the join key. Keep RequestID against your own session, user, or order so you can reconcile the asynchronous result with the action that triggered it.
• Store the evidence. Persist the score and signals you acted on. When you review a decision later, the signals are the explanation.
• Own your retention. ShieldLabs holds identification history for reads via the API; if your business needs a longer record, keep your own copy on your side and set retention to your own policy.

​

Map the install and the call

Integration is one JavaScript snippet plus your server reading the result over the API and webhooks. The snippet is an ES module loaded from the CDN. It is not an npm package and not a native mobile SDK. Full install steps are in Install the snippet. Pick the call per touchpoint: The forceCheck* calls clear the visit session and run immediately. Reach for them at the exact moment a decision is made, so the score is keyed to that action. Always pass a hashed or pseudonymous id to the authenticated calls, never a raw email or account id.

​

Plan for CSP and ad blockers

Two environment factors can stop the snippet from loading or reaching the data endpoints. Plan for both before launch.

• Content Security Policy. If your site sends a strict CSP header, allowlist the ShieldLabs snippet host and data endpoints, or the module will be blocked. The exact script-src and connect-src entries are in Content Security Policy.
• Ad blockers. Some blockers drop third-party requests, which can suppress identification for a slice of your traffic. Serving the snippet from your own subdomain reduces this.

​

Next steps