What you will build
A regional price needs a matching unmasked connection. This is an illustrative application policy, not a default rule that ShieldLabs applies to every customer.Run the starting application
You need Node.js 22 or later. The starter runs without ShieldLabs keys; the final version needs a registered HTTPS hostname and matching keys. Clone the public tutorial repository, then start this standalone application:The completed application uses browser SDK
1.1.0 and Node SDK 1.3.0. Its browser helper reads result.identificationId; requestId is the tutorial application’s own submitted field. Its server reads a domain-scoped identification card and requires available risk and signal states before applying the action policy. An unavailable state is not a clean score or a negative signal. See History for the response contract.Add the integration
Stop the starter server. Follow these changes, then run the complete implementation from thefinal branch.
1
1. Prepare the keys and HTTPS hostname
The Get the public domain UUID for this hostname using
.env copied from starter contains no key entries yet. Add the three lines below with this domain’s real values:GET /api/v1/domains with the Private API Key, or OAuth MCP shieldlabs_list_domains. Copy its id into SHIELDLABS_DOMAIN_ID; do not substitute the hostname.Register the app’s hostname in Integration > Domains. Put its matching Public Key and Private API Key in the private regional-pricing/.env as SHIELDLABS_PUBLIC_KEY and SHIELDLABS_API_KEY. Resolve that hostname through GET /api/v1/domains with the Private API Key, or OAuth MCP shieldlabs_list_domains, and set its public UUID as SHIELDLABS_DOMAIN_ID. Serve this app through HTTPS on that registered hostname. The Private API Key stays on the server; a customer key does not automatically authorize localhost.2
2. Identify the action in the browser
The protected page loads the locally served JS SDK. In Only the Identification ID goes to the server; the browser does not supply the risk result.
public/index.js, each action takes a fresh Identification ID and sends it with the action. requestId is this application’s payload field; the browser helper reads result.identificationId from the SDK:3
3. Verify the identification on the server
server/shieldlabs.js uses @shieldlabs-ai/node and the Private API Key to find that exact Identification ID in History. The action route passes it to server/pricing.js, where verifyIdentification(identificationId) rejects missing, stale, replayed, automated or unusable checks before this scenario’s rule is applied.4
4. Apply the regional discount rule
This excerpt from
server/pricing.js shows the decision’s core:server/pricing.js first rejects masked connections and timezone mismatch, then compares the selected country with the verified public-IP country. A selected form value alone never grants a regional discount.5
5. Run the completed application
From the repository root, compare the two versions and start the final app:A fresh clone has the remote
origin/final ref even before its local final branch exists. Open the completed app through the registered HTTPS hostname. The Node server listens on 127.0.0.1:3000 behind your reverse proxy.Follow the integration code
The completed source is in the regional-pricing application. Read these files in order:- Browser helper: loads the installed SDK, serializes checks and returns an Identification ID.
- Server verification: reads real History, checks the matching ID, waits within a bounded budget for pending results and rejects unusable or replayed checks.
- Scenario decision: applies this app’s rule using the verified identification and stores its sample state.
Try the completed application
- Select the country matching your actual connection and request a sample regional price.
- Select a different country with a fresh Identification ID. The app keeps the list price because the observed IP country does not match.
- The VPN/proxy and Tor branches are covered by local tests; do not change your real network just to force them.
DEMO_ALLOW_RESET=1 to repeat the exercise. These controls are for a disposable demonstration, not production authorization.
Check your result
In DevTools Network, inspect the /api/regional-price request and copy itsrequestId. Look up each Identification ID in History and compare public_ip.country, detection_flags and connection_type with the decision. This tutorial does not make a purchase. Run npm run check and npm test from regional-pricing to exercise failure cases locally without making more identifications.
For a real run, obtain fresh Identification IDs in the browser and confirm their Device IDs and signals in History. If identification returns HTTP 429, stop and respect the returned retry guidance; the status alone does not establish exhausted plan volume. A cookie change does not prove that the Device ID changed: compare the History rows.