API Reference¶
Start the SDK with DeaSdk.init(context, config), then reach it anywhere with DeaSdk.instance.
Types that come from the companion library (Consent, SessionInfo, CaptureEvent, …) are in
the ai.dea.base package; attestation types are in ai.dea.sdk.attest, proof types in
ai.dea.sdk.proof, and model types in ai.dea.sdk.model.
DeaSdk¶
init¶
fun init(
context: Context,
config: DeaConfig = DeaConfig(),
targets: TargetReader = ViewTargetReader(),
): DeaSdk
Starts the SDK and capture. Returns the running instance if one exists. Never throws. Call it on
the main thread, and pass your Application: the SDK keeps the Context it is given. See
Options.
instance¶
The running instance, or null before init and after dispose().
ready¶
Whether the SDK is able to score. When false, capture continues, getClassification() answers
INSUFFICIENT, and coreFault says why.
coreFault¶
Why the SDK cannot score, or null.
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, test
channel 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. Safe from any thread. See
Automation detection.
| 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 throw |
getProof() |
null without a request; lastProofRefusal is automated |
sendProof(), record() |
Nothing signed or sent: said is automated; record() answers false |
attest(), renewAttestation() |
FAILED, without a request. Automatic renewal stops |
checkForModel() |
Answers 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 |
A staging or test build logs automation.detected with the signal, then sdk.stopped with
dea.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 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
getClassification¶
Whether the session reads as a person, a bot, or neither yet, with the score and the model's thresholds behind the answer. One snapshot: it covers every interaction so far, and its fields always agree with each other. Synchronous; safe on the main thread. See Human Scoring.
Throws: ThresholdMissing when the loaded model sets no bot threshold. When the SDK cannot
score (ready is false) it does not throw; it answers INSUFFICIENT with a null value.
consent¶
The user's current consent answer. See User Consent.
setConsent¶
| Parameter | Type | Description |
|---|---|---|
granted |
Boolean |
Whether the user agreed |
remember |
Boolean |
false keeps the answer for this launch only and stores nothing |
Takes effect immediately. Withdrawing discards anything captured but not yet processed. The session is kept either way.
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.
captureEvent¶
| Parameter | Type | Description |
|---|---|---|
name |
String |
1 to 64 characters; otherwise the event is dropped |
data |
Map<String, Any?>? |
Optional; at most 1024 bytes as JSON, or the event is dropped |
Returns: Boolean — true when the event was recorded.
See Custom Events.
captureKey¶
fun captureKey(
keyClass: KeyClass,
pressed: Boolean = true,
mods: Int = 0,
repeat: Boolean = false,
field: String? = null,
)
| Parameter | Type | Description |
|---|---|---|
keyClass |
KeyClass |
Which kind of key: KeyClass.of(character) turns a typed character into one |
pressed |
Boolean |
false reports a release. A soft keyboard has none to report; send the press alone |
mods |
Int |
Modifier keys held, as KeyMod bits; 0 on a soft keyboard |
repeat |
Boolean |
Whether the press is a key repeat |
field |
String? |
The name of the text field typed into, as for a view's target name |
Reports one key press that your app saw. The SDK sees no key events of its own, so key presses are
recorded only when your app reports them, and only their class — never the character. Records
nothing unless events includes CaptureEvent.KEY_DOWN (and
CaptureEvent.KEY_UP for releases), and nothing while capture is paused or before consent. Never
call it for a password field. Without the key kinds the key is dropped, and a test or staging
build logs capture.key_ignored once.
setMotion¶
Switches the motion sensors off, or back on, for the running app. While off, the SDK reads no
motion data and sessionInfo.device.sensorRate is 0; touch capture and the session continue.
motion says whether the sensors are on. After motionRate = 0 it starts the sensors at 50 Hz.
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.
sessionInfo¶
The current session id, device and SDK version.
modelInfo¶
Which model is scoring: its version (0 for the built-in model) and its source: EMBEDDED,
CACHE (downloaded at an earlier launch) or NETWORK (downloaded during this run). See
Model options.
model¶
The stored model that loaded, the last one the core refused, and updateFault: why updates are
off, or null while they run. See ModelStatus.
checkForModel¶
Checks DEA's model host now, if a day has passed since the last check; force = true checks
anyway. The SDK already checks at every launch and on returning to the foreground, so most apps
never call this. Never throws. Blocking — call it off the main thread. Answers with
ModelCheckOutcome.CANCELLED when model updates are off.
addModelListener¶
Calls listener each time a newer model starts scoring during this run, on a background thread.
Returns the unsubscribe.
attest¶
Registers the device key with DEA and turns on automatic renewal. Cached until near expiry. Never
throws. Blocking — call it off the main thread. Answers UNSUPPORTED without a request when no
appKey was given. See Attest.
renewAttestation¶
Registers again now. A failure keeps the registration already held. Blocking.
lastAttestation¶
The last attestation result, or null before the first attest().
storedAttestation¶
The registration this install already holds, if it is still fresh, read from storage without a
request; null otherwise. A fresh one turns on automatic renewal.
forgetAttestation¶
Forgets the stored registration and any wait after refused attempts, and stops automatic renewal. The device key is kept.
nextAttestationRefresh¶
When the registration will next be renewed automatically, in epoch seconds.
onAttestationEvent¶
Called on every automatic renewal decision: Scheduled(afterSeconds), Fired(verdict) or Idle.
Set it before the first attest().
Ads¶
Android has no ad session object. getProof is the one proof call: it signs one ad
event — the session's current score, signed with the device key — and returns the proof; your app
uploads it (see Ads). sendProof and record are deprecated and removed
in a later release. For DEA to accept a proof, pass
appKey and register the device key with
attest(). See Ads.
getProof¶
fun getProof(
event: ProofEvent,
sessionId: String? = null,
attestation: Attestation? = null,
adUnit: String? = null,
appScopedUid: String? = null,
): SignedProof?
| Parameter | Type | Description |
|---|---|---|
event |
ProofEvent |
The ad event |
sessionId |
String? |
The ad session's id, signed into the proof. "" for an impression; the id DEA answered for the click and the end. null signs the capture session's id (sessionInfo.session), which is not an ad session's id |
attestation |
Attestation? |
Sets the tier claim only: B for a PASSED registration that carried a Play Integrity token and has not expired, C otherwise. null takes the registration the SDK holds from attest() |
adUnit |
String? |
The ad unit, signed into the proof. Pass the same one for an ad's three events |
appScopedUid |
String? |
Signed into the proof as app_scoped_uid; left out when null |
Fetches a challenge from DEA and signs the event. It never sends the proof: your app uploads it as
the Ads guide describes. The proof carries the score the core holds, when
its evidence ends, how many interactions are behind it, and the model version; your app cannot set
those. It carries no appId: DEA takes the app from the device key.
Blocking: it fetches the challenge.
Refused without a request on a production appId without appKey.
Returns: SignedProof? — the proof, or null when nothing was signed. After a null, read
lastProofRefusal.
lastProofRefusal¶
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.
lastProofRefusal |
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 |
sendProof¶
Deprecated. Use
getProofand upload the proof yourself. Removed in the next minor release.
fun sendProof(
event: ProofEvent,
sessionId: String? = null,
attestation: Attestation? = null,
adUnit: String? = null,
appScopedUid: String? = null,
extra: Map<String, Any?> = emptyMap(),
update: Boolean = false,
): RecordOutcome
| Parameter | Type | Description |
|---|---|---|
event |
ProofEvent |
The ad event |
sessionId |
String? |
The ad session's id, signed into the proof. "" for an impression, so DEA opens the session and answers with its id; that id for the click and the end. null signs the capture session's id (sessionInfo.session), which is not an ad session's id |
attestation |
Attestation? |
Sets the tier claim only: B for a PASSED registration that carried a Play Integrity token and has not expired, C otherwise. null takes the registration the SDK holds from attest() |
adUnit |
String? |
The ad unit, signed into the proof. Pass the same one for an ad's three events |
appScopedUid |
String? |
Signed into the proof as app_scoped_uid; left out when null |
extra |
Map<String, Any?> |
Unsigned fields sent in the request body beside the proof. They never replace the proof or the SDK version |
update |
Boolean |
true sends the proof as an update of the ad session sessionId names, PUT /api/sessions/{sessionId}, rather than POST /api/sessions. Use it for AD_ENDED |
Fetches a challenge from DEA, signs the event, and sends the proof. The proof carries the score
the core holds, when its evidence ends, how many interactions are behind it, and the
model version; your app cannot set those. It carries no appId: DEA takes the app from the
device key. If the challenge fails, the proof is signed and sent without
DEA's nonce.
When DEA cannot be reached or answers 5xx, the proof is sent again after 2 seconds, doubling to
30, plus up to 1 second: at most five sends in all, and none after the proof expires 90 seconds
after signing. A 4xx is final. Blocking through the retries — call it off the main thread.
Refused without a request when no appKey was given. Signs nothing when the device has no key, when
the core is not running, or when the session is not sufficient yet
(getClassification().result is INSUFFICIENT): an impression declared then is not recorded. The
click is not checked against the user's touches.
Returns: RecordOutcome — whether DEA accepted the proof, the proof, and what DEA or the SDK
said. See Ads: Find out why a proof was not accepted.
record¶
Deprecated. Use
getProof. Removed in a later release.
fun record(
event: ProofEvent,
sessionId: String? = null,
attestation: Attestation? = null,
adUnit: String? = null,
appScopedUid: String? = null,
extra: Map<String, Any?> = emptyMap(),
update: Boolean = false,
): Boolean
The same send as sendProof, with the same parameters. Blocking.
Returns: Boolean — true when DEA accepted the proof. To read DEA's session id after an
impression, use sendProof.
AI Data Tasks¶
Your app lists the projects and answers the task page with these two members. See AI Data Tasks.
signRequest¶
fun signRequest(
eventType: String,
claims: Map<String, Any?> = emptyMap(),
scored: Boolean = false,
sessionId: String? = null,
): String?
| Parameter | Type | Description |
|---|---|---|
eventType |
String |
The request: projects, fetch, consent or contribution |
claims |
Map<String, Any?> |
The request's own claims, signed as given |
scored |
Boolean |
true for contribution: the core adds the session's score |
sessionId |
String? |
The session the score belongs to. null signs the capture session's id |
Signs a request of the AI Data Tasks routes with the device
key, and returns the compact JWS to send as h_proof. The SDK adds the standard claims and
event_type; claims are signed as given. With scored, the core adds the session's score, and
nothing is signed while the session is not sufficient. Your app calls it for the project list
(projects) and to answer the task page's signRequest and signContribution calls.
Blocking: it fetches a challenge first.
Returns: String?, the signed request, or null when nothing was signed. After a null, read
lastRequestRefusal.
lastRequestRefusal¶
Why the last signRequest signed nothing, or null after a signed one. It is a short text, not a
code. It contains -33 while the session is not
sufficient yet. The next signRequest overwrites it.
dispose¶
Stops capture, drops anything not yet processed, and releases the SDK.
DeaConsentDialog¶
show¶
fun show(
activity: Activity,
sdk: DeaSdk? = DeaSdk.instance,
copy: ConsentCopy = ConsentCopy(),
remember: Boolean = true,
ask: Boolean = true,
onResult: (Boolean) -> Unit = {},
)
| Parameter | Type | Description |
|---|---|---|
activity |
Activity |
A showing activity to attach the dialog to |
sdk |
DeaSdk? |
The SDK to record the answer on |
copy |
ConsentCopy |
The dialog's text |
remember |
Boolean |
false clears the stored answer, asks on every call, and keeps each answer for this launch only |
ask |
Boolean |
false reads the stored answer without showing anything |
onResult |
(Boolean) -> Unit |
Called on the main thread with the answer |
Shows the consent dialog unless an answer is stored, and records the answer. Call it on the main thread. See User Consent.
ContributionPage¶
In ai.dea.sdk.contribution.
html¶
The AI Data Tasks page, to load into a WebView with
ContributionHosts.API_BASE as its base URL. Read from the SDK's assets once per process.
Throws: IOException when the page is missing from the SDK's assets.
ContributionHosts¶
In ai.dea.base. The hosts this build of the SDK talks to, for the task page's boot message.
| Constant | Type | Description |
|---|---|---|
API_BASE |
String |
DEA's API origin: the page's base URL, and the host of the project list |
WIDGET_ORIGIN |
String |
The origin of the task's widget |
MEDIA_ORIGIN |
String |
The origin of the task's images |
Functions¶
View.deaTarget¶
Declares what a view is: its name, and which kind of control it is. Overrides what the SDK would
infer. See Options: targets.
Types¶
DeaConfig¶
See Options.
registryAppId is deprecated and ignored since 0.20.8:
proofs carry no appId.
Migrating to this release:
Before This release debugprints to Logcat in every buildOnly in a testchannel buildProofs claim registryAppId,appIdor the development idProofs 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 proofgetProofreturnsnull;lastProofRefusalisapp_key_missingsendProof(...)signs and sendsgetProof(...), then the upload in the Ads guide;sendProofstill works in this release, and is removed in a later releasesetMotion(true)aftermotionRate = 0did nothing;motionreadtrueIt starts the sensors at 50 Hz; motionreadsfalseuntil thencaptureKeywithout the key kinds did nothing, silentlyIt still records nothing, and logs capture.key_ignoredoncemodeldid not say why updates were offmodel.updateFaultnames the reason, or isnullwhile updates run
Classification¶
| Field | Type | Description |
|---|---|---|
result |
ClassificationResult |
The answer |
value |
Double? |
The session's score, 0 to 1; null exactly when result is INSUFFICIENT |
actions |
Int |
Interactions behind value; the result stays INSUFFICIENT until there are as many as the loaded model asks for, 8 for the built-in model |
botThreshold |
Double? |
Below this, a sufficient session is a bot. The loaded model's; null when the SDK cannot score |
humanThreshold |
Double? |
At or above this, a sufficient session is a person. The loaded model's; null when the model sets none |
modelVersion |
Int? |
The model the thresholds come from, 0 for the built-in one; null when the SDK cannot score |
The thresholds come from the loaded model only. No account setting and no built-in constant changes them.
ClassificationResult¶
Checked in this order:
| Value | When |
|---|---|
INSUFFICIENT |
No core, the SDK is stopped, or fewer actions than the loaded model asks for. value is null |
HUMAN |
value at or above humanThreshold |
BOT |
value below botThreshold |
HUMAN |
No humanThreshold, and value at or above botThreshold |
UNDETERMINED |
value between the two thresholds |
Migrating to this release:
Classification.sufficientis gone, andClassificationResulthas a fourth value.
Before This release c.sufficient == falsec.result == ClassificationResult.INSUFFICIENTc.valuewhile not sufficient: a numbernullClassificationResulthas three valuesFour: handle INSUFFICIENTin every exhaustivewhenNo humanThreshold,valueat or abovebotThreshold:UNDETERMINEDHUMAN
ThresholdMissing¶
Thrown by getClassification() when the loaded model sets no bot threshold — a model file older
than thresholds. modelVersion names it. There is no fallback threshold: catch it and treat the
session as undetermined.
Consent¶
| Member | Type | Description |
|---|---|---|
decision |
ConsentDecision |
UNKNOWN, GRANTED or DENIED |
isAnswered |
Boolean |
Whether the user has answered |
isGranted |
Boolean |
Whether the user agreed |
forget() |
Unit |
Clears the stored answer so the user is asked again |
onChange(listener) |
() -> Unit |
Calls listener with the new decision when it changes; returns the unsubscribe |
Consent() |
constructor | An answer kept for this launch only |
Consent(store) |
constructor | An answer kept in your own ConsentStore |
Consent.granted() |
Consent |
An answer that is already yes |
ConsentStore¶
Where a Consent keeps its answer. write(ConsentDecision.UNKNOWN) means the answer was
forgotten.
ConsentCopy¶
The consent dialog's text: title, body, recorded, notRecorded, recordedLabel,
notRecordedLabel, closing, accept, decline. Every field has an English default. See
User Consent.
CaptureEvent¶
POINTER, SCROLL, MOTION, LIFECYCLE, CUSTOM, KEY_DOWN, KEY_UP. The default,
CAPTURE_EVENTS, is the first five. See Options: events.
KeyClass¶
LETTER, DIGIT, SPACE, DELETE, NAVIGATION, MODIFIER, OTHER (punctuation, Enter and
anything else). KeyClass.of(char: String) classifies a typed character as LETTER, DIGIT,
SPACE or OTHER.
TargetBucket¶
UNKNOWN, BUTTON, LINK, INPUT, SCROLLER, CANVAS, BACKGROUND.
SessionInfo¶
| Field | Type | Description |
|---|---|---|
session |
String |
Current session id, a UUID |
device |
DeviceRecord |
Current device information |
sdk.version |
String |
SDK version |
sdk.core |
String |
Which core build is running; none when the SDK cannot score |
startedAt |
Long |
When the session started, Unix milliseconds |
DeviceRecord¶
| Field | Type | Description |
|---|---|---|
surface |
Surface |
Screen size in dp (width, height) |
pixelRatio |
Double |
Physical pixels per dp |
rotation |
Int |
Screen rotation: 0, 90, 180 or 270 |
maxTouchPoints |
Int |
How many touches the screen declares it can follow at once |
sensorRate |
Int |
The requested motion rate, in Hz, once motion data has arrived; 0 before that and while motion is off |
os |
Int |
Operating system code |
runtime |
Int |
SDK runtime code |
ModelInfo¶
| Field | Type | Description |
|---|---|---|
version |
Int |
The model's version; 0 for the built-in model |
source |
ModelSource |
EMBEDDED, CACHE or NETWORK |
ModelStatus¶
| Field | Type | Description |
|---|---|---|
running |
String? |
The stored version that loaded, or null for the built-in model |
lastRefusal |
ModelRefusal? |
The last model the core refused: its version and the core's answer. null when none was refused |
updateFault |
String? |
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_context |
No modelDirectory and no Context to find the default folder |
ModelCheck¶
| Field | Type | Description |
|---|---|---|
outcome |
ModelCheckOutcome |
NOT_DUE, UNCHANGED, NOT_PUBLISHED, NOT_SUPPORTED, LOADED, REFUSED, FAILED or CANCELLED |
detail |
String? |
What went wrong, when something did |
Attestation¶
| Field | Type | Description |
|---|---|---|
supported |
Boolean |
Whether the SDK could register: false when no key could be created, or no appKey was given |
verdict |
Verdict |
PASSED, FAILED or UNSUPPORTED |
platformAttested |
Boolean |
Whether a Play Integrity token went with an accepted registration |
platformTokenSpent |
Boolean |
Whether this attempt obtained a Play Integrity token, whatever DEA answered |
integrity |
String? |
DEA's reading of the device's integrity, when DEA returned one |
expiresAt |
Long? |
Expiry, epoch seconds |
kid |
String? |
Key identifier |
tier |
String? |
Trust tier assigned by DEA |
backing |
String? |
Where the key is kept: strongbox, tee or software |
detail |
String? |
Why the SDK did not register, or what DEA or the network answered when it failed |
ProofEvent¶
| Value | wire |
The event |
|---|---|---|
AD_IMPRESSION |
ad.impression |
The ad is on screen |
AD_CLICK |
ad.click |
The ad was clicked |
AD_ENDED |
ad.ended |
The ad is gone |
wire is the event_type signed into the proof. There are no other values.
RecordOutcome¶
| Field | Type | Description |
|---|---|---|
accepted |
Boolean |
Whether DEA accepted the proof |
signed |
SignedProof? |
The proof that was signed, or null when nothing was |
isSigned |
Boolean |
Whether signed is not null |
said |
String? |
DEA's answer as it came, or why DEA was never reached or did not accept |
sessionId |
String? |
The session_id in DEA's answer, or null when it named none. After an impression, the ad session's id: pass it to the click and the end |
SignedProof¶
| Member | Type | Description |
|---|---|---|
proof |
String |
The compact JWS, header.payload.signature, signed with the device key (ES256) |
score |
Double |
The score signed into the proof, 0 to 1 |
evidenceAt |
Long |
When the evidence behind score ends, epoch seconds |
windows |
Int |
How many scored interactions are behind score |
sessionId |
String |
The session_id signed into the proof |
event |
ProofEvent |
The event signed into the proof |
modelVersion |
Int? |
The version of the model that produced score, 0 for the built-in one; null when the proof carries none |
composedBy |
ProofSource |
Who composed what was signed: CORE for every proof DeaSdk signs |
composedBytes |
Int? |
How many bytes were signed |
header |
JSONObject? |
The signed header, decoded: alg, typ, kid |
claims |
JSONObject? |
The signed claims, decoded |
signature |
String? |
The signature segment, base64url |
score, evidenceAt, windows and modelVersion are read back out of the signed claims.
StopState¶
What stopped answers while the SDK is stopped.
| Field | Type | Description |
|---|---|---|
reason |
String |
Why the SDK stopped: automated, a sure sign of automation |