API Reference

import { init, DeaSdk } from '@dea/sdk';
// or '@dea/sdk/desktop', '@dea/sdk/mobile' — same API, no device detection

init returns the SDK instance; anywhere else, DeaSdk.current returns it.

Note: The package ships TypeScript declarations for everything below. Your editor shows the full types from @dea/sdk.

Functions

init

function init(config?: DeaConfig): DeaSdk

Starts the SDK and capture. Returns the running instance if one exists, and ignores the options of that later call. See Options.

Throws: TypeError when the browser does not provide crypto.randomUUID(): on a page that is not a secure context (not HTTPS or localhost), and in browsers older than the minimum versions. When the scoring engine cannot load, init does not throw; it reports the problem on error.

DeaSdk

DeaSdk.current

static get current(): DeaSdk | null

The running instance, or null before init and after dispose().

ready

ready(): Promise<void>

Resolves once the SDK has finished loading, whether it succeeded or failed. Never rejects. You do not need to wait for it before calling other methods. With requireConsent: true it resolves only after setConsent(true); see User Consent.

error

get error(): Error | null

Why the scoring engine could not load, or null. When set, capture continues but there is no score, and the classification stays 'insufficient'. A load failure is a CoreLoadError, whose reason is 'core_not_loaded', 'core_abi_mismatch' or 'core_wrong_profile' — see Troubleshooting.

appId

get appId(): string

The account the SDK is running as.

appKey

get appKey(): string | null

The app key the SDK sends to DEA, or null when a production appId was given none — then attest() fails and no ad proof is signed, without a request.

profile

get profile(): CaptureProfile

The capture profile in use, detected or pinned. profile.id is 'web-desktop' or 'web-mobile'.

getClassification

getClassification(): Classification

The one score read: the score, the evidence behind it and the loaded model's thresholds, classified as 'human', 'bot', 'undetermined' or 'insufficient' in one snapshot. Synchronous; includes the user's most recent input. The thresholds come from the loaded model only. See Human Scoring.

Throws: ThresholdMissing (with modelVersion) when the loaded model has no bot threshold.

sufficiency

sufficiency(): Sufficiency | null

The evidence collected so far, or null while the scoring engine is not running: still loading, failed to load, or waiting for consent.

model

model(): ModelState

The scoring model in use: { version, source }. version is 0 for the model built into the package; source is 'embedded', 'cache' (downloaded on an earlier visit) or 'network' (downloaded in this session). See modelUpdates.

checkForModel

checkForModel(options?: { force?: boolean }): Promise<ModelState>

Waits for ready(), then joins the model check the SDK runs at every init — or runs it, if it has not run — and resolves with the model in use once the check has ended. With { force: true } it asks DEA again. Asks nothing with modelUpdates: false.

pause

pause(): void

Stops recording. The session is kept. See Sensitive Screens.

resume

resume(): void

Starts recording again after pause(). It does not open the consent gate.

consent

get consent(): Consent

The user's answer: decision ('unknown', 'granted' or 'denied'), isAnswered and isGranted. Restored from the browser at init.

setConsent

setConsent(granted: boolean, options?: { remember?: boolean }): void

Records the answer. With requireConsent: true, true starts recording and false stops it. { remember: false } keeps the answer to this page. See User Consent.

captureEvent

captureEvent(name: string, data?: Readonly<Record<string, unknown>>): boolean

Parameter	Type	Description
name	string	1–64 characters
data	Record<string, unknown>	Optional; at most 1024 bytes as JSON

Returns: true when recorded; false when paused, waiting for consent, disposed, or the name is invalid. See Custom Events.

reset

reset(): void

Ends the current session and starts a new one. See Sessions.

getSessionInfo

getSessionInfo(): SessionInfo

The current session id, device, motion-sensor access and SDK version.

attest

attest(): Promise<Attestation>

Registers the browser's key with DEA. Cached until 60 seconds before it expires. Never throws. The SDK never calls it by itself. See Attest.

ads

get ads(): AdModule

The ad verification module. See Ads.

dispose

dispose(): void

Stops capture, drops anything not yet processed or sent, and releases the SDK.

AdModule

session_opened

session_opened(surface?: Element | (() => Rect | null), adUnit?: string): Promise<AdSession | null>

The ad is on screen. Signs and sends the impression and resolves with the ad session the DEA service opened, or null when none could be opened, which is always the case while the classification is 'insufficient': the impression is then not recorded. surface is the element the ad renders into, or a function that returns its rectangle in viewport pixels. See Find out why no ad session opened.

counts

readonly counts: AdCounts

Proofs signed, refused, notScored (the classification was still 'insufficient'), unwitnessed clicks, and delivery (sent, dropped, pending).

AdSession

Member	Type	Description
id	string	The ad session's id, made by the DEA service
click()	() => boolean	The ad was clicked. Refused when a watched element was never touched, after a first click, or after end()
end()	() => void	The ad is gone. Sends the end of the ad session

Types

SessionInfo

Field	Type	Description
session	string	Current session id
device	DeviceRecord	Current device information: viewport size (surface), pixel_ratio, rotation, max_touch_points, sensor_rate, and more
identity	DeviceIdentity	os_version and model, when the browser reports them through User-Agent Client Hints; null otherwise
motion	'off' \| 'unsupported' \| 'pending' \| 'denied' \| 'granted'	Motion-sensor access
sdk.version	string	SDK version
sdk.core	string	Scoring engine build

Classification

Field	Type	Description
result	ClassificationResult	The answer
value	number \| null	The human score, from 0 to 1. null exactly when result is 'insufficient'
actions	number	How many scored actions value is based on, at most 64. For "N more actions"
botThreshold	number \| null	The model's bot threshold. null before a model loads
humanThreshold	number \| null	The model's human threshold. null when the model sets none
modelVersion	number \| null	The model the thresholds come from; 0 for the one built in. null before a model loads

ClassificationResult

Value	When
'insufficient'	The scoring engine is not running yet, or there are too few actions: fewer than 20, or only one input type (pointer, wheel, keyboard), on a desktop; fewer than 8 on a phone. value is null, and no proof is signed
'human'	value at or above humanThreshold. When humanThreshold is null: value at or above botThreshold
'bot'	value below botThreshold
'undetermined'	value between the two thresholds

The rows are checked in that order, and 'insufficient' comes first: a score only counts once there are enough actions behind it.

Sufficiency

Field	Type	Description
durationMs	number	Session duration so far
actions	number	Interactions collected
pointer	number	Pointer interactions
wheel	number	Wheel interactions
key	number	Keyboard interactions
sufficient	boolean	Whether these are enough actions to classify the session — see Evidence

Attestation

Field	Type	Description
supported	boolean	Whether a key could be created
verdict	'passed' \| 'failed' \| 'unsupported'	The outcome
expiresAt	number \| null	Expiry, epoch seconds
kid	string \| null	Key identifier
tier	string \| null	Trust tier assigned by DEA

AdCounts

Field	Type	Description
signed	number	Proofs signed
refused	number	Proofs not signed: no appKey, no browser key, or the scoring engine is not running or refused
notScored	number	Proofs not signed because the classification was still 'insufficient'
unwitnessed	number	Clicks refused because nothing touched the watched element
delivery	{ sent: number; dropped: number; pending: number }	Proofs DEA accepted, gave up on, and still being sent

ModelState

Field	Type	Description
version	number	The model's version; 0 for the one built into the package
source	'embedded' \| 'cache' \| 'network'	Where it came from

ThresholdMissing

An Error thrown by getClassification() when the loaded model has no bot threshold. modelVersion names the model.

CoreLoadError

The Error on dea.error when the scoring engine could not load. reason is 'core_not_loaded', 'core_abi_mismatch' or 'core_wrong_profile'.