Skip to content

API Reference

import ai.dea.sdk.ClassificationResult
import ai.dea.sdk.DeaConfig
import ai.dea.sdk.DeaSdk

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

val instance: DeaSdk?

The running instance, or null before init and after dispose().

ready

val ready: Boolean

Whether the SDK is able to score. When false, capture continues, getClassification() answers INSUFFICIENT, and coreFault says why.

coreFault

val coreFault: String?

Why the SDK cannot score, or null.

stopped

val stopped: StopState?

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.until said when the stop ended StopState carries only reason. 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

getClassification

fun getClassification(): Classification

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.

val consent: Consent

The user's current consent answer. See User Consent.

setConsent

fun setConsent(granted: Boolean, remember: Boolean = true)
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

fun pause()

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

resume

fun resume()

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

captureEvent

fun captureEvent(name: String, data: Map<String, Any?>? = null): Boolean
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

fun setMotion(on: Boolean)
val motion: Boolean

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

fun 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

val sessionInfo: SessionInfo

The current session id, device and SDK version.

modelInfo

val modelInfo: 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

val model: ModelStatus

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

fun checkForModel(force: Boolean = false): ModelCheck

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

fun addModelListener(listener: (ModelInfo) -> Unit): () -> Unit

Calls listener each time a newer model starts scoring during this run, on a background thread. Returns the unsubscribe.

attest

fun attest(): Attestation

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

fun renewAttestation(): Attestation

Registers again now. A failure keeps the registration already held. Blocking.

lastAttestation

val lastAttestation: Attestation?

The last attestation result, or null before the first attest().

storedAttestation

fun storedAttestation(): Attestation?

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

fun forgetAttestation()

Forgets the stored registration and any wait after refused attempts, and stops automatic renewal. The device key is kept.

nextAttestationRefresh

val nextAttestationRefresh: Long?

When the registration will next be renewed automatically, in epoch seconds.

onAttestationEvent

var onAttestationEvent: ((AttestRefresher.Event) -> Unit)?

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

val lastProofRefusal: String?

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 getProof and 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

val lastRequestRefusal: String?

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

fun 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

fun html(context: Context): String

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

fun View.deaTarget(name: String? = null, bucket: TargetBucket? = null)

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
debug prints to Logcat in every build Only in a test channel build
Proofs claim registryAppId, appId or the development id 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 returns null; lastProofRefusal is 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
setMotion(true) after motionRate = 0 did nothing; motion read true It starts the sensors at 50 Hz; motion reads false until then
captureKey without the key kinds did nothing, silently It still records nothing, and logs capture.key_ignored once
model did not say why updates were off model.updateFault names the reason, or is null while 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.sufficient is gone, and ClassificationResult has a fourth value.

Before This release
c.sufficient == false c.result == ClassificationResult.INSUFFICIENT
c.value while not sufficient: a number null
ClassificationResult has three values Four: handle INSUFFICIENT in every exhaustive when
No humanThreshold, value at or above botThreshold: UNDETERMINED HUMAN

ThresholdMissing

class ThresholdMissing(val modelVersion: Int) : Exception

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.

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

interface ConsentStore {
    fun read(): ConsentDecision
    fun write(decision: ConsentDecision)
}

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

data class StopState(val reason: String)

What stopped answers while the SDK is stopped.

Field Type Description
reason String Why the SDK stopped: automated, a sure sign of automation