Browser fingerprinting SDK docs

DigitalFingerprint is a visitor identification platform delivered as a JavaScript SDK. Use it when you need a persistent visitor ID across cleared cookies, VPNs, and many private-browsing scenarios — without trusting fraud fields returned to the browser. Start with install, then wire Events GET before signup, checkout, or other high-value actions.

1. 01

   Install the SDK

   Install @digitalfingerprintjs/client from npm, load cdn.digitalfingerprintjs.com, or import the Google Tag Manager template — then init with your public browser key (pk_…).

2. 02

   Identify in the browser

   POST browser signals to https://api.digitalfingerprintjs.com/api/identify. Production keys return a slim payload; store eventId on your backend.

3. 03

   Enrich server-side

   Fetch authoritative smart signals via GET /api/events/:eventId with a secret server key (sk_…). Attach account/order metadata after identify with PATCH /api/events/:eventId (linkedId/tags). Optionally GET /api/drn/:originId for global device reputation. Never trust fraud fields from the client.

Download the tag template, import it under GTM Templates, create a DigitalFingerprint tag with your public key (pk_…), and trigger on Initialization. Allowlist your website hostname on the key.

window.dataLayer.push(function () {
  if (this.get("DigitalFingerprintResult")) {
    const result = this.get("DigitalFingerprintResult");
    console.log(result.originId, result.eventId);
  }
});

Import rules presets from the console Limiter or via POST /api/management/v1/api-keys project setup. Fraud vs analytics posture is expressed through rules presets and Events GET confidence gating , not per-key assignment forks.

// Your backend: authoritative enrichment (never trust browser fraud fields)
const rulesetId = process.env.ORIGINID_RULESET_ID; // optional, from /dashboard/rules
const apiBase = "https://api.digitalfingerprintjs.com";
const url = rulesetId
  ? `${apiBase}/api/events/${eventId}?ruleset_id=${rulesetId}`
  : `${apiBase}/api/events/${eventId}`;
const res = await fetch(url, {
  headers: { Authorization: `Bearer ${ORIGINID_API_KEY}` }
});
const event = await res.json();
// event.identification.confidence, event.smartSignals, event.ruleAction

?format=fingerprint returns Fingerprint-compatible JSON (confidence 0–1). Native JSON uses scale 0–100. ?include=raw adds raw signal blobs when PERSIST_RAW_SIGNALS=true. Rate limits: default 600/min per API key, 1000/min per organization. Native Events JSON may include deviceReputation; the Fingerprint Accept export omits it — use GET /api/drn/:originId instead. After identify, PATCH /api/events/:eventId with linkedId / tags (full replace when tags present; secret key only).

Query by the public originId from identify. When the same device was minted under two IDs (e.g. hardware overlap without strong stable+recall agreement), DRN aggregates suspect scores and timestamps across the cluster. Response fields: canonicalOriginId, clusterOriginIds, suspectScore.minimum/maximum (30-day window), timestamps.

const res = await fetch(
  "https://api.digitalfingerprintjs.com/api/drn/" + encodeURIComponent(originId),
  { headers: { Authorization: "Bearer " + process.env.ORIGINID_SECRET_KEY } },
);
const reputation = await res.json();

Body: { "email": "user@example.com", "visitorId": "<originId>" }. The request field is named visitorId for API compatibility, pass your originId value. Returns duplicate risk score and reasons. Separate from linkedId on identify.

Suspect score and risk level live on the event root (suspectScore, riskLevel, riskBreakdown) with breakdown dimensions: network, reputation, integrity, automation, identity, environment, trust.

Full Smart Signals reference ↑

Install the SDK, call identify, send eventId to your backend, then GET /api/events/:eventId with a secret sk_… key before you allow, challenge, or block. Never trust browser slim fields for fraud decisions. Example thresholds below are illustrative only — tune them in your policy; they are not product defaults. Optional: apply the same rules to webhook identify.succeeded payloads.

VPN and proxy friction examples remain optional while hosted IP intelligence runs in vendor mode (fixture-backed until live minFraud credentials).

Register HTTPS endpoints in the dashboard (Developer → Webhooks). Envelope type identify.succeeded with data matching Events GET. Delivery is at-least-once with up to 5 retries; dedupe on webhook id within 72 hours.

// Verify X-OriginID-Signature on incoming webhook POST
const rawBody = await request.text();
const header = request.headers.get("X-OriginID-Signature") ?? "";
const t = header.match(/t=(\d+)/)?.[1];
const v1 = header.match(/v1=([a-f0-9]+)/)?.[1];
if (!t || !v1 || Math.abs(Date.now() / 1000 - Number(t)) > 300) {
  return new Response("stale", { status: 401 });
}
const expected = hmacSha256Hex(signingSecret, `${t}.${rawBody}`);
if (!timingSafeEqual(v1, expected)) {
  return new Response("invalid", { status: 401 });
}

Use ?format=fingerprint on identify and Events GET for adapter-compatible JSON. Map visitor_id → originId; confidence is 0–100 in native JSON and 0–1 in Fingerprint export.

// Migration: Fingerprint-compatible JSON on Events GET
const res = await fetch(
  `https://api.digitalfingerprintjs.com/api/events/${eventId}?format=fingerprint`,
  { headers: { Authorization: `Bearer ${SECRET_KEY}` } }
);
const fp = await res.json();
// fp.visitor_id → originId; fp.confidence.score is 0–1

Browser traffic posts to https://api.digitalfingerprintjs.com/api/identify. Your backend fetches enrichment from https://api.digitalfingerprintjs.com/api/events/:eventId with the same secret API key. Do not POST identify to the marketing apex; digitalfingerprintjs.com/api/* is GET-only.

• Public browser key (pk_…) on identify; secret server key (sk_…) on Events GET
• Browser SDK endpoint: https://api.digitalfingerprintjs.com/api/identify (not marketing apex; apex /api/* is GET 301 only)
• Install via npm @digitalfingerprintjs/client or official CDN cdn.digitalfingerprintjs.com
• Before production traffic (optional): Settings → Subdomains for first-party identify proxy; allowlist site hostname (SITE_ORIGIN)
• Allowed hostnames configured on each public API key (site host required when using a first-party proxy)
• No platform ORIGINID_SECRET / signingSecret in frontend JS (public keys use platform-managed integrity)
• Slim response verified; no smartSignals in browser payloads
• Backend tested: identify → eventId → GET /api/events/:eventId (and PATCH linkedId/tags when needed) with secret key
• Optional: GET /api/drn/:originId for global device reputation (secret key)
• Confidence thresholds migrated (Fingerprint 0–1 → OriginID 0–100)
• Sensitive actions use identifyOnDemand: true + Events GET (not cached browser identify)
• Production security review checklist completed

• NewGoogle Tag Manager

  Import DigitalFingerprint template.tpl into GTM — Start and identify without redeploying your site. Results push to dataLayer as DigitalFingerprintResult (do not send originId to Google Analytics).

• NewGlobal device reputation (DRN)

  GET /api/drn/:originId and Events deviceReputation — Fingerprint-style cluster rollups across orgs while metrics stay per-tenant.

• NewWeb Bot Auth verification

  bot_info.verified and bot_info.spoofed on Events GET with RFC 9421 Ed25519 signature validation for AI agents and search bots.

• NewHosted identify platform

  Fully managed identify, Events API, and console at api.digitalfingerprintjs.com with no infrastructure to deploy on your side.

• UpdateConfidence v2

  Confidence v2 on all new visits: merge false-positive risk scale, linkConfidence, fusion penalties, high-activity cap.

• BreakingSDK 1.0: default clientToken seeding

  SDK auto-seeds first-party clientToken on init (Fingerprint parity). bootstrapToken config removed.

• UpdateLimiter on identify

  Enabled rulesets auto-enforce on POST /api/identify; Events GET supports inline ?ruleset_id evaluation.

• UpdateRules presets

  Importable Analytics & marketing, Signup & fraud protection, and Shared & corporate devices ruleset templates.

• UpdateProduction trust model

  Production API keys default to slim browser responses; fraud fields via Events GET or webhooks.

• InfoDigitalFingerprint branding

  Public product name DigitalFingerprint; SDK class OriginID (@digitalfingerprintjs/client); visitor identifier originId.