Skip to content

API Reference

import * as Dea from '@dea/react-native';
// or named imports: import {init, getClassification, deaTarget} from '@dea/react-native';

The SDK is a set of module-level functions; there is no instance to hold. Every function that talks to the SDK returns a promise. Calls that read or change the session run on the main thread in the order they are made; attest() and renewAttestation() run on a background thread. Every function except init, deaTarget, getTargetTally and onAttestationEvent rejects (error code E_DEA) until init has run, and after dispose(). getClassification() has one more error code of its own, threshold_missing.

Pass init the appKey DEA issued with your appId. See Accounts and keys and Attest.

Lifecycle

init

function init(config: DeaConfig): Promise<Started>

Starts the SDK and capture. A repeat call resolves with the running session and keeps the first call's options. Scoring problems do not reject: they resolve with ready: false and a coreFault. Rejects with an Error whose message ends is not supported on a platform other than Android or iOS. See Options.

Returns: Started

dispose

function dispose(): Promise<void>

Stops capture and releases the SDK. A later init starts a new session.

stopped

function stopped(): Promise<{ reason: string } | null>

With automationDetection: true: the stop the native 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, test builds included. The stop lasts until reset() or a new start: the app launched again, or dispose() then init. The device does not keep it. resume() and setConsent(true) do not lift it. It does not name the check that fired. See Automation detection.

Field Type Description
reason string Why the SDK stopped: automated, a sure sign of automation
While stopped What the app sees
Capture Nothing is recorded. resume() and setConsent(true) do not start it again
getClassification() insufficient, actions 0, and value, both thresholds and modelVersion null. It does not reject
getProof() null without a request; getLastProofRefusal() resolves automated
attest(), renewAttestation() verdict: 'failed', without a request. Automatic renewal stops
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 native log has automation.detected with the signal, then sdk.stopped with dea.reason: automated, in a staging or test build. After reset() lifts the stop, it has automation.started again.

Migrating to this release:

Before This release
stopped() resolved { reason, until }; until said when the stop ended { reason } only. The stop lasts until reset() or a new start
The device kept the stop, and a launch inside it started stopped Nothing keeps the stop. Every launch starts as usual
reset() did not lift the stop reset() lifts it

Human scoring

getClassification

function getClassification(): Promise<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. Includes the user's most recent touch. The thresholds come from the loaded model only. See Human Scoring.

Rejects with code threshold_missing when the loaded model has no bot threshold; the error's userInfo.modelVersion names that model, and the constant THRESHOLD_MISSING holds the code.

deaTarget

function deaTarget(
  name: string,
  bucket?: 'button' | 'link' | 'input' | 'canvas' | 'scroller',
): DeaTargetProps

Synchronous. Props to spread onto a view so the SDK can name it and tell what kind of control it is. See Name your views.

Parameter Type Description
name string A control's name, hashed on the device. Never content or personal information
bucket string The kind of control. Omit to only name the view

getTargetTally

function getTargetTally(): Promise<Record<number, number>>

Presses per TargetBucket code since init, when init was given countTargets: true; empty otherwise. Always empty with a production appId: the native SDKs refuse the counter there. Resolves an empty object before init instead of rejecting.

setConsent

function setConsent(granted: boolean): Promise<void>

Records the user's answer and stores it on the device. Takes effect immediately. See User Consent.

getConsent

function getConsent(): Promise<ConsentState>

'unknown' until the user has answered, then 'granted' or 'denied'.

Capture

pause

function pause(): Promise<void>

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

resume

function resume(): Promise<void>

Starts recording again after pause(). Does not override consent, and does not start capture while the SDK is stopped.

setMotion

function setMotion(on: boolean): Promise<void>

Starts or stops the motion sensors. false stops them and sets sensor_rate back to 0. true after motionRate 0 starts them at 50 Hz.

captureEvent

function captureEvent(name: string, data?: Record<string, unknown>): Promise<boolean>
Parameter Type Description
name string 1 to 64 characters, or the event is dropped
data Record<string, unknown> Optional; at most 1024 bytes as JSON, or the event is dropped

Resolves true when the event was recorded. See Custom Events.

Sessions

reset

function reset(): Promise<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

function getSessionInfo(): Promise<Record<string, unknown>>

The current session id, device and SDK version. See SessionInfo for the shape.

Attestation

Attestation needs the appKey passed to init, and on Android the playIntegrityProject. See Attest.

attest

function attest(): Promise<Attestation>

Registers the device key with DEA and resolves the result; the first call turns on automatic renewal. Without an appKey, with a production appId, resolves at once with verdict: 'unsupported', supported: false and a detail that starts with no appKey, without contacting DEA, and automatic renewal does not start.

renewAttestation

function renewAttestation(): Promise<Attestation>

Registers again now, even while the current result is still valid, and re-plans automatic renewal. A refusal keeps the registration already held. Without an appKey, the same answer as attest().

getLastAttestation

function getLastAttestation(): Promise<Attestation | null>

The last registration result, without attesting again. null before the first attest().

getNextAttestationRefresh

function getNextAttestationRefresh(): Promise<number | null>

When the next automatic renewal is scheduled, in epoch seconds, or null when none is planned.

onAttestationEvent

function onAttestationEvent(listener: (event: AttestationEvent) => void): EventSubscription

Calls listener with every decision automatic renewal makes. Synchronous; call remove() on the returned subscription to stop. Subscribe before the first attest(), which schedules the first renewal.

Ads

getProof is the one proof call: it signs one ad event with the device key on Android or iOS, and your app uploads the proof. See Ads. sendProof() and record() are deprecated and removed in a later release, with the RecordOutcome type.

getProof

function getProof(event: ProofEvent, options?: ProofOptions): Promise<SignedProof | null>

event is 'ad.impression', 'ad.click' or 'ad.ended'. options takes sessionId ('' for an impression, then the id DEA answered), adUnit and appScopedUid. Signs on the native SDK and never uploads. Resolves null when nothing was signed; read getLastProofRefusal.

getLastProofRefusal

function getLastProofRefusal(): Promise<string | null>

Why the last getProof signed nothing, or null before the first getProof and after a signed one. Read it right after the null: the next getProof overwrites it. The values are the native SDK's:

Value Why
no_core dispose() was called, or no core is loaded
app_key_missing A production appId without appKey. Refused on the device, without a request
no_key The device has no key to sign with
automated Automation detection stopped the SDK: see stopped. reset() lifts the stop
not_scored The session is not sufficient yet (core code -33)
core_not_initialised, core_bad_argument, claims_invalid, claim_reserved, claim_missing, proof_too_large, core_panic The core refused the claims: codes -1, -2, -30, -31, -32, -34, -99. A code outside that list is claims_invalid
key_sign_failed The device key did not sign
claim_score_missing The composed claims lack h_score, h_ts or h_wc
answer_mismatch The composed claims name another session, event or key
claim_model_version_invalid The composed h_mv is not a whole number at or above 0

AI Data Tasks

See AI Data Tasks. The package has no signRequest in JavaScript: your app signs task requests through a native module that calls the native SDK, as that page shows.

CONTRIBUTION_PAGE_HTML

const CONTRIBUTION_PAGE_HTML: string

The task page, to load into a WebView with the apiBase of getContributionHosts() as its base URL.

getContributionHosts

getContributionHosts(): Promise<ContributionHosts>

The hosts the native SDK was built with, for the task page's boot message: apiBase (DEA's API origin, the page's base URL and the host of the project list), widgetOrigin (the origin of the task's widget) and mediaOrigin (the origin of the task's images). Needs no init.

Model updates

getModel

function getModel(): Promise<Record<string, unknown>>

Which model is scoring, from the native SDK. Resolves an object with three keys:

Key Type Description
running string \| null The stored version that loaded, or null for the built-in model
lastRefusal { version, answer }, optional The last model the core refused. Absent when none was refused
updateFault string \| null Why updates are off, or null while they run
updateFault Means
no_core The core did not load, so there is nothing to load a model into
disabled You set modelUpdates: false
no_storage iOS: no folder to keep a model in
no_context Android: no modelDirectory and no Context

Types

DeaConfig

Field Type Description
appId string Required. The appId DEA issued for this app
requireConsent boolean? Default true
consent boolean? An answer your app already has
motionRate number? Android only. Motion samples per second
appKey string? The appKey DEA issued with appId. Required for attestation
playIntegrityProject number? Android only. The Google Cloud project number DEA issued for Play Integrity. Required for attestation on Android
countTargets boolean? Count presses per bucket for getTargetTally(); no effect with a production appId
debug boolean? Android only. Logs to Logcat, with an SDK build of the test channel only
events CaptureEvent[]? The input kinds to capture. Unset or empty keeps the native default
idleMotionMs number? One motion reading every this many milliseconds while nobody touches the screen; 0 keeps every reading. Default 3000
touchMarginMs number? Full-rate motion for this many milliseconds before and after each touch. Default 200
registryAppId string? Deprecated and ignored since 0.20.8: proofs carry no appId
modelUpdates boolean? Model update checks. Default true
modelDirectory string? Absolute path of the folder that keeps a downloaded model. Unset takes the native default
modelTimeoutMs number? The time limit of one model request, in milliseconds. Default 30000
modelUrlOverride string? Reserved for DEA's own tooling. Ignored with a production appId

See Options.

Migrating to this release:

Before This release
events, idleMotionMs, touchMarginMs, registryAppId, modelUpdates, modelDirectory, modelTimeoutMs, modelUrlOverride are not in DeaConfig In DeaConfig, passed to the native SDK on Android and iOS
debug prints to Logcat in every build Only in a test channel build
Proofs claim the development id (registryAppId was not in DeaConfig) Proofs carry no appId (0.20.8): DEA takes the app from the device key. registryAppId is deprecated and ignored
getProof signs on a production appId without appKey, and DEA refuses the proof getProof resolves null; getLastProofRefusal() resolves app_key_missing
sendProof(...) signs and sends getProof(...), then the upload in the Ads guide; sendProof still works in this release, and is removed in a later release
On Android, init rejected with E_DEA when the core library lacked a JNI export init resolves { ready: false, coreFault }
No setMotion setMotion(on)
getModel() did not say why updates were off It resolves updateFault: the reason, or null while updates run

CaptureEvent

'pointerDown', 'pointerMove', 'pointerUp', 'pointerCancel', 'wheel'. An input kind to capture. On Android the four pointer kinds are captured together.

Started

Field Type Description
ready boolean false means the SDK captures but cannot score
coreFault string \| null Why scoring could not start
modelRunning string \| null A label for a stored model the SDK loaded, or null. Android does not report a model downloaded over the air here; getClassification().modelVersion always names the model that is scoring
sdkVersion string SDK version

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. 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, and then every value at or above botThreshold is 'human'
modelVersion number \| null The model the thresholds come from; 0 for the one built in. null before a model loads

ClassificationResult

Checked in this order:

Value When
'insufficient' Scoring or the model not loaded, the SDK is stopped, or fewer actions than the model asks for (8 with the built-in model). value is null, and no proof can be signed
'human' value at or above humanThreshold
'bot' value below botThreshold
'human' humanThreshold is null, and value at or above botThreshold
'undetermined' value at or above botThreshold and below humanThreshold

Migrating to this release: Classification.sufficient is gone, and ClassificationResult has a fourth value.

Before This release
c.sufficient === false c.result === 'insufficient'
c.value while not sufficient: a number null
ClassificationResult has three values Four: handle 'insufficient' in every switch
No humanThreshold, value at or above botThreshold: 'undetermined' 'human'

ConsentState

'unknown', 'granted', 'denied'.

DeaTargetProps

Field Type Description
nativeID string The name, read on Android
testID string The name, read on iOS
accessibilityRole 'button' \| 'link' \| 'search' \| 'image' \| 'scrollbar', optional The kind of control; absent when bucket is omitted

TargetBucket

The codes getTargetTally() is keyed by: unknown 0, button 1, link 2, input 3, scroller 4, canvas 5, background 6.

SessionInfo

getSessionInfo() resolves an object of this shape:

Field Type Description
session string Current session id, a UUID
sdk.version string SDK version
sdk.core string Core build
device.runtime number 3 on Android, 4 on iOS
device.os number 1 Android, 2 iOS
device.surface {width, height} Screen size in logical pixels
device.pixelRatio number Physical pixels per logical pixel
device.rotation number Screen rotation: 0, 90, 180 or 270
device.maxTouchPoints number Simultaneous touches the screen supports
device.sensorRate number The motion rate requested, in Hz, once motion samples are arriving; 0 until the first sample arrives, and on a device that delivers none

Attestation

Field Type Description
supported boolean Whether a key could be created
verdict 'passed' \| 'failed' \| 'unsupported' The outcome
platformAttested boolean Whether Play Integrity or App Attest vouched for the device
expiresAt number \| null Expiry, epoch seconds
kid string \| null Key identifier
tier string \| null Trust tier assigned by DEA
backing string \| null Where the key is kept
detail string \| null Why attestation failed

AttestationEvent

type Other fields Meaning
'scheduled' afterSeconds, nextRefresh A renewal is scheduled
'fired' verdict, nextRefresh A renewal ran
'idle' nextRefresh Nothing to renew

nextRefresh is epoch seconds, or null.