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¶
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:
getProofis the one proof call,setMotionexists,motionRatehas one clamp, the model status says why updates are off, and a productionappIdignores the secondinitargument.
Before This release signContribution(claims)answers{ tuple }or{ reason, code, outcome }getProof('contribution', claims)answers aSignedProofornull; readlastProofRefusal.signContribution, and theproveProofandsignProofexports, are deprecated and still work in this releaseNo way to start motion after motionRate: 0dea.setMotion(true)A negative motionRateasked for 25 HzMotion off model()andcheckForModel()answer{ version, source }{ version, source, updateFault }:updateFaultsays why updates are offinit(config, platform)with a productionappId:platformappliedplatformignored; the SDK uses the real browser andsdk.option_ignorednamesplatformProofs and signed requests claim appId, orregistryAppIdon a productionappIdThey carry no appId(0.20.8): DEA takes the app from the browser's key.registryAppIdis deprecated and ignoredA later release turns the consent gate on by default (
requireConsentbecomestrue) and removessignContributionand theproveProofandsignProofexports.
DeaSdk¶
DeaSdk.current¶
The running instance, or null before init and after dispose().
ready¶
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¶
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¶
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.untilsaid when the stop endedStopStatecarries onlyreason. The stop lasts untilreset()or a new startThe 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 stopreset()lifts it
appId¶
The account the SDK is running as.
appKey¶
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¶
The capture profile in use, detected or pinned. profile.id is 'web-desktop' or 'web-mobile'.
getClassification¶
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¶
The evidence collected so far, or null while the scoring engine is not running: still loading,
failed to load, or waiting for consent.
model¶
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¶
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¶
Stops recording. The session is kept. See Sensitive Screens.
resume¶
Starts recording again after pause(). It does not open the consent gate, and does not start
capture while the SDK is stopped.
setMotion¶
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 andgetSessionInfo().motionreads'denied'; a latersetMotion(true)asks again. A page that never callssetMotion(true)keeps the prompt at the user's first tap.
consent¶
The user's answer: decision ('unknown', 'granted' or 'denied'), isAnswered and
isGranted. Restored from the browser at init.
setConsent¶
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¶
| 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¶
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¶
The current session id, device, motion-sensor access and SDK version.
attest¶
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¶
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¶
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¶
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¶
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¶
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 |