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¶
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¶
Stops capture and releases the SDK. A later init starts a new session.
stopped¶
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 };untilsaid when the stop ended{ reason }only. The stop lasts untilreset()or a new startThe 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 stopreset()lifts it
Human scoring¶
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. 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¶
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.
Consent¶
setConsent¶
Records the user's answer and stores it on the device. Takes effect immediately. See User Consent.
getConsent¶
'unknown' until the user has answered, then 'granted' or 'denied'.
Capture¶
pause¶
Stops recording. The session is kept. See Sensitive Screens.
resume¶
Starts recording again after pause(). Does not override consent, and does not start capture
while the SDK is stopped.
setMotion¶
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¶
| 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¶
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 and SDK version. See SessionInfo for the shape.
Attestation¶
Attestation needs the appKey passed to init, and on Android the playIntegrityProject. See
Attest.
attest¶
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¶
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¶
The last registration result, without attesting again. null before the first attest().
getNextAttestationRefresh¶
When the next automatic renewal is scheduled, in epoch seconds, or null when none is planned.
onAttestationEvent¶
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¶
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¶
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¶
The task page, to load into a WebView with the apiBase of getContributionHosts() as its base
URL.
getContributionHosts¶
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¶
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,modelUrlOverrideare not inDeaConfigIn DeaConfig, passed to the native SDK on Android and iOSdebugprints to Logcat in every buildOnly in a testchannel buildProofs claim the development id ( registryAppIdwas not inDeaConfig)Proofs carry no appId(0.20.8): DEA takes the app from the device key.registryAppIdis deprecated and ignoredgetProofsigns on a productionappIdwithoutappKey, and DEA refuses the proofgetProofresolvesnull;getLastProofRefusal()resolvesapp_key_missingsendProof(...)signs and sendsgetProof(...), then the upload in the Ads guide;sendProofstill works in this release, and is removed in a later releaseOn Android, initrejected withE_DEAwhen the core library lacked a JNI exportinitresolves{ ready: false, coreFault }No setMotionsetMotion(on)getModel()did not say why updates were offIt resolves updateFault: the reason, ornullwhile 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.sufficientis gone, andClassificationResulthas a fourth value.
Before This release c.sufficient === falsec.result === 'insufficient'c.valuewhile not sufficient: a numbernullClassificationResulthas three valuesFour: handle 'insufficient'in everyswitchNo humanThreshold,valueat or abovebotThreshold:'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.