Skip to content

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 core cannot load, init does not throw; it reports the problem on error.

Migrating to this release: getProof is the one proof call, setMotion exists, motionRate has one clamp, the model status says why updates are off, and a production appId ignores the second init argument.

Before This release
signContribution(claims) answers { tuple } or { reason, code, outcome } getProof('contribution', claims) answers a SignedProof or null; read lastProofRefusal. signContribution, and the proveProof and signProof exports, are deprecated and still work in this release
No way to start motion after motionRate: 0 dea.setMotion(true)
A negative motionRate asked for 25 Hz Motion off
model() and checkForModel() answer { version, source } { version, source, updateFault }: updateFault says why updates are off
init(config, platform) with a production appId: platform applied platform ignored; the SDK uses the real browser and sdk.option_ignored names platform
Proofs and signed requests claim appId, or registryAppId on a production appId They carry no appId (0.20.8): DEA takes the app from the browser's key. registryAppId is deprecated and ignored

A later release turns the consent gate on by default (requireConsent becomes true) and removes signContribution and the proveProof and signProof exports.

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 core could not load, or null. When set, capture continues but there is no score, and the classification stays 'insufficient'; model updates, automation detection and proofs stop too. A load failure is a CoreLoadError, whose reason is 'core_not_loaded', 'core_abi_mismatch' or 'core_wrong_profile' — see Troubleshooting.

stopped

get stopped(): StopState | null

With automationDetection: true: the stop the SDK is under, or null while it runs. The first sure sign of automation stops every SDK operation at once, on every account and build. The stop lasts until reset() or a new start: a page load, or dispose() then init. The browser does not keep it. resume() and setConsent(true) do not lift it. It does not name the check that fired. See Automation detection.

While stopped What the page sees
Capture Nothing is recorded. resume() and setConsent(true) do not start it again
getClassification() { result: 'insufficient', value: null, actions: 0, botThreshold: null, humanThreshold: null, modelVersion: null }
sufficiency() null
getProof() null without a request; lastProofRefusal is 'automated'
ads.session_opened() null: no ad proof is signed, and ads.counts.refused moves
attest() verdict 'failed', without a request
checkForModel() The model in use, without a request
Integrations Nothing more is sent. What was sent before the stop stays sent
reset() Lifts the stop and starts a new session. See reset
dispose() As always

The staging package logs automation.detected with the signal, then sdk.stopped with reason automated. After reset() lifts the stop, it logs automation.started again.

Migrating to this release:

Before This release
stopped.until said when the stop ended StopState carries only reason. The stop lasts until reset() or a new start
The browser kept the stop, and a page load inside it started stopped Nothing keeps the stop. Every page load starts as usual
reset() did not lift the stop reset() lifts it

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, getProof() returns null with lastProofRefusal 'app_key_missing', 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, updateFault }. 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). updateFault is null while updates run, or says why they are off: 'no_core', 'disabled', 'no_storage' or 'consent_pending' — see ModelState and Troubleshooting. 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, as a ModelState with updateFault. With { force: true } it asks DEA again, unless a check is in flight at that moment, which it joins instead of asking twice. Asks nothing with modelUpdates: false (updateFault is 'disabled'), and waits for setConsent(true) while the consent gate is closed (updateFault is 'consent_pending' until then).

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, and does not start capture while the SDK is stopped.

setMotion

setMotion(on: boolean): void

Turns motion capture on or off. true starts the devicemotion listener at motionRate, or at 50 Hz when motionRate is 0; while motion is already on it does nothing. false stops the listener: getSessionInfo().motion reads 'off' and device.sensor_rate goes back to 0. The classification is then computed without motion. Works at any time, before or after the user consents.

Note: On iPhone and iPad, setMotion(true) asks the browser for motion permission at once, and the browser shows its own prompt. Call it from a tap handler: outside one, the browser refuses and getSessionInfo().motion reads 'denied'; a later setMotion(true) asks again. A page that never calls setMotion(true) keeps the prompt at the user's first tap.

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. On a stopped SDK it also lifts the stop: capture, proofs, model updates and automation detection start again. If automation goes on, the SDK stops again. 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.

getProof

getProof(event: 'contribution', options: ContributionClaims): Promise<SignedProof | null>

Signs one proof for the current session and resolves with it, or with null when nothing was signed — then lastProofRefusal says why. The core composes the proof from the claims in options and the score it holds for this session, and the browser's key signs it. The proof carries no appId: DEA takes the app from the browser's key. getProof never uploads: your page attaches proof to the request that submits the answer. event is 'contribution' (TaskEventType.Contribution); any other value answers null with lastProofRefusal 'claim_missing'. Never rejects.

Parameter Type Description
event 'contribution' The event the proof is for
options ContributionClaims item_id, artifact_hash and an optional srv_nonce

Returns: SignedProof, or null. null early in a session is the normal answer: the session is not sufficient yet, and lastProofRefusal is 'not_scored'.

import { DeaSdk } from '@dea/sdk';

const dea = DeaSdk.current!;
const signed = await dea.getProof('contribution', { item_id: itemId, artifact_hash: artifactHash });
if (signed === null) {
  console.warn('Nothing signed:', dea.lastProofRefusal); // 'not_scored': ask the user to keep going
} else {
  await submitAnswer(itemId, { proof: signed.proof }); // your own request to DEA's task service
}

itemId, artifactHash and submitAnswer stand for your own code. Ad proofs are signed and sent by ads, which is the one place the SDK sends a proof.

lastProofRefusal

get lastProofRefusal(): string | null

Why the last getProof() answered null, or null before the first call and after a signed one. Read it right after the null: the next getProof() overwrites it.

Value Why nothing was signed
'not_scored' The session is not sufficient yet: too few actions behind the score. Try again after more input
'app_key_missing' A production appId with no appKey
'no_key' The browser could not create or open its signing key: IndexedDB refused, or no Web Crypto
'no_core' The core is not running: it failed to load (error is set), dispose() was called, or no input has been captured yet
'automated' Automation detection stopped the SDK: see stopped. reset() lifts the stop
'claim_missing' event is not 'contribution', or a required claim is missing, mistyped or unknown
'claims_invalid', 'claim_reserved', 'proof_too_large' The core refused the claims
'core_not_initialised', 'core_bad_argument', 'core_panic' The core could not compose the proof
'key_sign_failed' The browser's key did not sign
'claim_score_missing', 'claim_model_version_invalid', 'answer_mismatch' The composed proof does not match what was asked: no score, a bad model version, or another session, event or key

The staging package logs each refusal as proof.not_signed with the same value in reason, except after dispose().

ads

get ads(): AdModule

The ad verification module. It signs and sends its own ad proofs; it is the one place the SDK sends a proof. 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,
  options?: AdSessionOptions, // since 0.26.0
): 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. adUnit and, since 0.26.0, options.appScopedUid are signed into the impression, the click and the end. 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 Core 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, the SDK is stopped, 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

AdSessionOptions

Since 0.26.0.

Field Type Description
appScopedUid string, optional Your app's id for the user, 1 to 128 characters. Signed into the impression, the click and the end; left out when absent. See App user ids

AdCounts

Field Type Description
signed number Proofs signed
refused number Proofs not signed: no appKey, no browser key, the SDK is stopped, 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
updateFault string \| null null while updates run. Otherwise why they are off, the first that holds: 'no_core' (the core failed to load), 'disabled' (modelUpdates: false), 'no_storage' (no IndexedDB to keep a model in, or it could not be read), 'consent_pending' (the consent gate is closed)

Computed when read; an update that just ran leaves it null.

ContributionClaims

Field Type Description
item_id string The task item the answer is for, as DEA's task service named it
artifact_hash string sha256(JCS(artifact)), lowercase hex: the answer, bound into the signature
srv_nonce string Optional. A browser session takes none

SignedProof

What getProof resolves with. The same field names as the Flutter, Android, iOS and React Native SignedProof.

Field Type Description
proof string The signed proof, a compact JWS. Send this
score number The human score signed into it, from 0 to 1
evidenceAt number When the score was read, Unix seconds
windows number How many scored actions the score is based on
modelVersion number \| null The model that scored; 0 for the one built in
sessionId string The session the proof is for
event 'contribution' The event the proof is for
composedBy 'core' Who composed the claims: always the core on the Web
composedBytes number The length of the signed input

decodeProof(proof), exported by the package, reads the proof's header and claims (jti among them) back without verifying it.

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 core could not load. reason is 'core_not_loaded', 'core_abi_mismatch' or 'core_wrong_profile'.

StopState

What stopped answers while the SDK is stopped.

Field Type Description
reason 'automated' Why the SDK stopped: automation detection found a sure sign of automation