@dojah/deviceguard-web

Web SDK for Dojah DeviceGuard: identifies the device, returns a stable deviceId and a risk score, and tracks user actions for fraud detection.

• Zero dependencies, ~12 KB minified
• Works with bundlers (ESM/CJS) or a plain <script> tag
• Fingerprint payload is encrypted in transit when your server has payload encryption enabled
• Safe to import during SSR — only call its methods in the browser

Get an API key

You need an API key (dg_…) and your DeviceGuard endpoint URL to use the SDK. To request them, email [email protected].

The key is used in the browser, so it isn't secret. Ask support to restrict it to your domains (origin allowlist) so it can't be used from other sites.

Install

npm install @dojah/deviceguard-web

Usage

import DeviceGuard from '@dojah/deviceguard-web';

const deviceGuard = new DeviceGuard({
  apiKey: 'dg_your_api_key',
  endpoint: 'https://your-deviceguard-server.com',
});

// Get device ID
const deviceId = await deviceGuard.getDeviceId();

// Record user action
await deviceGuard.recordAction('login', {
  userId: 'user-123',
  metadata: { source: 'web' }
});

Script tag

<script src="https://cdn.jsdelivr.net/npm/@dojah/deviceguard-web/dist/deviceguard.min.js"></script>
<script>
  const deviceGuard = new DeviceGuard({ apiKey: 'dg_your_api_key', endpoint: 'https://your-deviceguard-server.com' });
  deviceGuard.getDeviceId().then((deviceId) => console.log(deviceId));
</script>

Next.js / SSR

Importing is safe on the server, but fingerprinting needs a browser — call the SDK from useEffect or a client component:

'use client';
import { useEffect } from 'react';
import DeviceGuard from '@dojah/deviceguard-web';

useEffect(() => {
  new DeviceGuard({ apiKey, endpoint }).getDeviceId().then((deviceId) => { /* … */ });
}, []);

Verify on your server

Anything from the browser can be tampered with, including a riskScore read in the browser. Before making a trust decision, look the device up from your backend:

curl -X POST https://your-deviceguard-server.com/api/device/verify \
  -H "X-API-Key: dg_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"deviceId": "<deviceId from the browser>"}'
# → { "riskScore": 12, "isBlocked": false, "isTrusted": false, ... }
# 404 if the device isn't known to your workspace

Then allow, step up (e.g. OTP), or block based on the result.

API

| Method | Returns | |---|---| | new DeviceGuard(config) | config: apiKey, endpoint, timeout (ms, default 10000), retry (default true), debug (default false) | | init(apiKey?, endpoint?) | Promise<{ deviceId, riskScore, isNewDevice, country, ipAddress, device }> | | getDeviceId() | Promise<string> — identifies first if needed | | recordAction(action, { userId?, metadata? }) | Records an action (login, signup, payment, …) and links userId to this device. action ≤ 64 chars, metadata ≤ 4KB. Returns { success, userLinked, riskScore, alerts } | | track(action, metadata?) | Older form of recordAction; a userId inside metadata is also linked | | verifyDevice() | Promise<{ isBlocked, isTrusted, riskScore, … }> | | isDeviceBlocked() | Promise<boolean> | | getRiskScore() | Promise<number \| null> | | getFingerprint() | The raw collected fingerprint |

Notes

• Requires an API key — requests without a valid key are rejected. Get one from [email protected].
• Always verify server-side. Treat the deviceId sent from the browser as a claim; look it up from your backend before making trust decisions.
• The SDK stores a random identifier in localStorage and a first-party cookie (_dg_cid) to recognise the device across visits.
• If you use a Content Security Policy, allow your DeviceGuard endpoint in connect-src.