Skip to content

API Reference

import DeaSDK
import DeaBase // for Consent, SessionInfo, JSONValue and the other shared types

There is no shared instance: create one DeaSdk and keep it. See the Quick Start.

DeaSdk

init(options:)

init(options: DeaSdkOptions)

Creates the SDK and starts a session. Capture does not begin until start(). Never throws: if the core cannot load, the instance is still created, ready is false and coreFault says why. With model updates on, it also starts a check for a newer model in the background. See Options.

Migrating to this release:

Before This release
openCore, keystore, urlProtocolClasses with a production appId: applied Ignored; sdk.option_ignored names core or attest
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 nil; 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
captureKey without the key kinds did nothing, silently It still records nothing, and logs capture.key_ignored once
A view is named by accessibilityIdentifier only view.deaTarget = "buy" names it, and wins over accessibilityIdentifier
model did not say why updates were off model.updateFault names the reason, or is nil while updates run

start

func start()

Starts global capture. Call it once, on the main thread, as early as possible. A second call does nothing. Does nothing after dispose().

Migrating to this release:

Before This release
A second start() attached the core and the integrations again, so every event was counted twice A second start() does nothing

options

let options: DeaSdkOptions

The options this instance was created with.

appKey

var appKey: String? { get }

The app key the SDK sends as X-App-Key: the appKey option, trimmed, or nil when none was given.

ready

var ready: Bool { get }

Whether the SDK is able to score. When false, capture continues but there is no score, the classification is .insufficient, and coreFault says why.

coreFault

private(set) var coreFault: String?

Why the SDK cannot score, or nil.

stopped

var stopped: StopState? { get }

With automationDetection: true: the stop the SDK is under, or nil 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 a new DeaSdk after dispose(). Nothing keeps it on the device. 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 nil. It does not throw
getProof() nil 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() completion is called 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 keychain 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

func getClassification() throws -> Classification

The one score read: waits for input already received to be scored, then reads the score, the amount of evidence behind it and the loaded model's thresholds in one snapshot, and classifies it as .human, .bot, .undetermined or .insufficient. Does not call the network. Blocks for as long as pending input takes to be scored — usually nothing — so call it before a decision, not on every frame.

Before the core loads (ready is false) it returns Classification.unloaded (.insufficient, value nil) and does not throw.

Throws: ThresholdMissing when the loaded model carries no bot threshold. See Human Scoring.

drain

func drain()

Waits until input the app has already received has been scored. getClassification() does this itself.

modelInfo

var modelInfo: ModelInfo { get }

Which model is scoring now: its version (0 for the model built into the SDK) and where it came from. See Options.

model

var model: ModelStatus { get }

The stored model that loaded, the last one the core refused, and updateFault: why updates are off, or nil while they run. See ModelStatus.

checkForModel

func checkForModel(force: Bool = false, completion: ((ModelCheck) -> Void)? = nil)

Asks DEA's model server for a newer model now, if a day has passed since the last check that got an answer; otherwise answers .notDue without a request. The SDK already checks when it is created and when the app returns to the foreground, so you do not need to call this.

Parameter Type Description
force Bool Ask even if the last check was less than a day ago. For a person pressing a button, never for a schedule
completion ((ModelCheck) -> Void)? Called with how the check ended, off the main thread

Never throws and never blocks. With modelUpdates: false, completion gets .cancelled.

modelChanges

@discardableResult
func modelChanges(_ listener: @escaping (ModelInfo) -> Void) -> () -> Void

Calls listener, off the main thread, each time a newer model starts scoring during this run. Call the returned closure to stop listening.

var consent: Consent { get }

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

setConsent

func setConsent(_ granted: Bool, remember: Bool = true)
Parameter Type Description
granted Bool Whether the user agreed
remember Bool Store the answer on the device. false keeps it for this run only

Takes effect immediately: granting starts recording, withdrawing stops it.

requestConsent

func requestConsent(
    from presenter: UIViewController,
    copy: ConsentCopy = ConsentCopy(),
    remember: Bool = true,
    completion: @escaping (Bool) -> Void
)

UIKit. Shows the consent alert from presenter if the user has not answered, records the answer, and calls completion with it. With a stored answer and remember: true, calls completion at once and shows nothing.

pause

func pause()

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

resume

func resume()

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

setMotion

func setMotion(_ on: Bool)
var motion: Bool { get }

Turns the motion sensors off, or back on. Core Motion keeps running from init until dispose(), including while capture is paused; setMotion(false) stops it. While motion is off, the core receives no motion readings and scores touches with zeros in their motion values, which can change the classification. motion reads whether the sensors are on.

captureEvent

func captureEvent(_ name: String, data: [String: JSONValue]? = nil) -> Bool
Parameter Type Description
name String 1 to 64 characters
data [String: JSONValue]? Optional; at most 1024 bytes as JSON

Returns: true when recorded; false when a limit is exceeded, capture is paused, consent is missing, or the SDK is disposed. See Custom Events.

captureKey

func captureKey(
    _ keyClass: KeyClass,
    pressed: Bool = true,
    mods: Int = 0,
    repeat: Bool = false,
    field: String? = nil
)
Parameter Type Description
keyClass KeyClass The kind of key, never the character
pressed Bool false reports the release; needs .keyUp in events
mods Int Modifier keys held, as KeyMod bits. A soft keyboard reports none: 0
repeat Bool Whether the press is an automatic repeat
field String? A name for the text field typed into

Reports one keystroke. Does nothing unless .keyDown is in the events option, and, like every capture, while 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. See Report typing.

reset

func reset()

Ends the current session and starts a new one. A model the SDK downloaded stays in use. 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

var sessionInfo: SessionInfo { get }

The current session id, device and SDK version.

coreCounts

var coreCounts: CoreCounts { get }

Diagnostics: how many captured events the SDK has processed in this session. samples grows as the user interacts; use it to check that capture works.

attest

func attest() -> Attestation

Registers the device key with DEA. Cached until shortly before expiry, and renewed automatically after the first call. Answers .unsupported without a request when no appKey was given. Never throws. Blocking — call it off the main thread. See Attest.

renewAttestation

func renewAttestation() -> Attestation

Registers again now, even while the current result is valid. A failure keeps the previous valid result. Blocking.

storedAttestation

func storedAttestation() -> Attestation?

The registration this install already holds, if it is still valid, read without a network request; nil when attest() would have to register again. Reads the keychain: call it off the main thread.

forgetAttestation

func forgetAttestation()

Forgets this install's registration and any wait after refused attempts, so the next attest() registers from the start. Keeps the device key. Stops the automatic renewal until the next attest().

lastAttestation

var lastAttestation: Attestation? { get }

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

nextAttestationRefresh

var nextAttestationRefresh: Date? { get }

When the automatic renewal will next run. nil before the first attest(), and on a device that cannot keep a key.

Ads

iOS has no ad module like the Web's ads.session_opened(). getProof is the one proof call: it signs the current score into a proof for one ad event with the device key, and your app uploads it. sendProof and record are deprecated and removed in a later release. Each call asks DEA for a single-use nonce before it signs, so each one blocks: call them off the main thread. Proofs carry no appId: DEA takes the app from the device key. See Ads for the impression, click and end in order.

getProof

func getProof(
    event: ProofEvent,
    sessionId: String? = nil,
    attestation: Attestation? = nil,
    adUnit: String? = nil,
    appScopedUid: String? = nil
) -> SignedProof?

Signs one proof and returns it without sending it; your app uploads it as the Ads guide describes.

Parameter Type Description
event ProofEvent The ad event, signed as event_type
sessionId String? The ad session, signed as session_id. "" for an impression, so DEA answers with a new id; that id for the click and the end. nil signs the SDK's own session id (sessionInfo.session), which is not an ad session
attestation Attestation? Decides only the tier signed into the proof: B for a passed, unexpired registration with platformAttested, C otherwise. nil uses the registration the SDK holds
adUnit String? The ad unit, signed as ad_unit
appScopedUid String? A pseudonymous id for the user, scoped to your app, signed as app_scoped_uid

Asks DEA for the nonce, so it blocks; when DEA gives no nonce, the proof is signed without one. On a production appId without appKey it signs nothing, without a request.

Returns: the proof, or nil when nothing was signed; lastProofRefusal says why.

lastProofRefusal

var lastProofRefusal: String? { get }

Why the last getProof signed nothing, or nil before the first getProof and after a signed one. Read it right after the nil: 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.

func sendProof(
    event: ProofEvent,
    sessionId: String? = nil,
    attestation: Attestation? = nil,
    adUnit: String? = nil,
    appScopedUid: String? = nil,
    extra: [String: Any] = [:],
    update: Bool = false
) -> RecordOutcome

Signs one proof and sends it to DEA's recording service: POST /api/sessions, or PUT /api/sessions/{sessionId} with update: true. Takes the parameters of getProof, plus these two:

Parameter Type Description
extra [String: Any] Fields of your own, sent in the request body beside the proof, outside its signature. JSON values only. Never replaces the proof
update Bool Send as PUT /api/sessions/{sessionId}, the end of the ad session the impression opened

When DEA does not answer or answers with a 5xx, the SDK sends the proof again after 2, 4, 8 and 16 seconds (plus up to one second each), five sends at most, and never after the proof's 90-second lifetime. A 4xx answer is final. With every attempt failing, a call can block for about two minutes.

Returns: RecordOutcome. accepted is false, and said says why, when the classification is still .insufficient, there is no device key, the core is not running, there is no appKey (nothing is sent), DEA refused the proof, or no send got through. See Read why a proof was not recorded.

Throws: Never.

record

Deprecated. Use getProof. Removed in a later release.

func record(
    event: ProofEvent,
    sessionId: String? = nil,
    attestation: Attestation? = nil,
    adUnit: String? = nil,
    appScopedUid: String? = nil,
    extra: [String: Any] = [:],
    update: Bool = false
) -> Bool

sendProof with the same parameters, answering only accepted: true when DEA accepted the proof. Blocking.

AI Data Tasks

Your app lists the projects and answers the task page with these two members. See AI Data Tasks.

signRequest

func signRequest(
    eventType: String,
    claims: [String: Any] = [:],
    scored: Bool = false,
    sessionId: String? = nil
) -> String?
Parameter Type Description
eventType String The request: projects, fetch, consent or contribution
claims [String: Any] The request's own claims, signed as given
scored Bool true for contribution: the core adds the session's score
sessionId String? The session the score belongs to. nil 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. Call it off the main thread.

Returns: String?, the signed request, or nil when nothing was signed. After a nil, read lastRequestRefusal.

lastRequestRefusal

var lastRequestRefusal: String? { get }

Why the last signRequest signed nothing, or nil 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

func dispose()

Stops capture, the model update checks and the automatic attestation renewal, and releases the SDK. A disposed instance cannot be started again; create a new one.

ContributionPage

html

static let html: String

The AI Data Tasks page, to load into a WKWebView with ContributionHosts.apiBase as its base URL.

ContributionHosts

In DeaBase: import DeaBase beside import DeaSDK. The hosts this build of the SDK talks to, for the task page's boot message.

Constant Type Description
apiBase String DEA's API origin: the page's base URL, and the host of the project list
widgetOrigin String The origin of the task's widget
mediaOrigin String The origin of the task's images

UIKit

UIView.deaTarget

extension UIView {
    public var deaTarget: String? { get set }
}

Names the view in the stream; wins over accessibilityIdentifier. Needs import DeaBase.

SwiftUI

deaConsent

@available(iOS 15.0, *)
func deaConsent(
    _ consent: Consent,
    asking: Binding<Bool>,
    copy: ConsentCopy = ConsentCopy(),
    remember: Bool = true,
    onAnswer: @escaping (Bool) -> Void
) -> some View

A View modifier. Shows the consent alert while asking is true, records the answer on consent, and calls onAnswer. It does not check for a stored answer: set asking only when consent.isAnswered is false.

Parameter Description
consent The SDK's consent
asking Whether the alert is shown
copy The alert's text
remember Store the answer. false keeps it for this run only
onAnswer Called with the user's answer

Types

DeaSdkOptions

Field Type Default Description
appId String — Your DEA appId
requireConsent Bool true Record nothing until the user agrees
consent Consent? nil (stored in UserDefaults) Where the consent answer is kept
appKey String? nil Your DEA appKey, sent as X-App-Key. Needed for Attest and Ads
registryAppId String? nil Deprecated and ignored since 0.20.8: proofs carry no appId
onLog ((LogEntry) -> Void)? nil Never called by the production build
modelDirectory URL? nil (Application Support) Where downloaded models are kept
modelUpdates Bool true Check for and download newer models
modelTimeout TimeInterval 30 Seconds one model request may take
events [CaptureEvent] CaptureEvent.pointerKinds Input kinds to capture
idleMotionMs Int 3000 Motion reading interval while nobody touches the screen
motionRate Int 50 Motion sensor rate to request, in Hz; at least 25
touchMarginMs Int 200 Full-rate motion around each touch, in ms

The remaining fields are reserved. See Options.

DeaSdkError

Deprecated and never thrown: init(options:) does not throw. A reserved integrations option set with a production appId is ignored.

Classification

Field Type Description
result ClassificationResult The answer
value Double? The human score, from 0 to 1. nil exactly when result is .insufficient
actions Int How many interactions value stands on. For "N more actions" while .insufficient
botThreshold Double? The loaded model's bot threshold. nil before a model loads
humanThreshold Double? The loaded model's human threshold. nil when the model sets none, and then every reading at or above botThreshold is .human
modelVersion Int? The model the thresholds come from; 0 for the built-in one. nil before a model loads

Classification.unloaded is the value returned before the core loads.

ClassificationResult

Checked in this order:

Case When
.insufficient The core or model is not loaded, the SDK is stopped, or the session has fewer actions than the model asks for (8 with the built-in model). value is nil
.human value at or above humanThreshold
.bot value below botThreshold
.human humanThreshold is nil, and value is at or above botThreshold
.undetermined value at or above botThreshold and below humanThreshold

The thresholds come from the loaded model only. Nothing in your account or in the SDK overrides them.

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

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

ThresholdMissing

An Error. Thrown by getClassification() when the loaded model carries no bot threshold.

Field Type Description
modelVersion Int The model that carries none

ModelInfo

Field Type Description
version Int The model's version; 0 for the model built into the SDK
source ModelSource .embedded (built in), .cache (downloaded earlier, read at launch) or .network (downloaded during this run)

ModelStatus

Field Type Description
running String? The stored version that loaded, or nil for the built-in model
lastRefusal ModelStatus.Refusal? The last model the core refused: its version and the core's answer. nil when none was refused
updateFault String? Why updates are off, or nil 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 to false
no_storage No folder to keep a model in: the modelDirectory you passed, or Application Support, could not be opened

ModelCheck

Field Type Description
outcome ModelCheckOutcome How the check ended — see below
refusal ModelLoad? What the core said, when it refused the file
detail String? Why the check failed or was cancelled
ModelCheckOutcome Meaning
.loaded A newer model was downloaded and is scoring now
.unchanged Nothing newer is published
.notPublished DEA has published no model this SDK can download
.notSupported A newer model is published, but this SDK version cannot read it
.notDue Less than a day since the last answered check, and force was false
.refused The core refused the downloaded file. The running model is unchanged
.failed No usable answer: offline, a timeout, an unexpected status, or a file that does not match the published size or checksum
.cancelled Model updates are not running, or the SDK was disposed

From DeaBase.

Member Type Description
decision ConsentDecision .unknown, .granted or .denied
isAnswered Bool Whether the user has answered
isGranted Bool Whether the user agreed
set(_:remember:) Void Records an answer. Same as DeaSdk.setConsent
forget() Void Clears the stored answer so the user is asked again
onChange(_:) () -> Void Calls the listener with the new decision when it changes; call the returned closure to stop
init(store:decision:) Builds a Consent over a ConsentStore — see Options
Consent.granted() Consent An already-granted answer, not stored

ConsentStore

From DeaBase. A protocol with read() -> ConsentDecision and write(_ decision: ConsentDecision). Implementations: DefaultsConsentStore (in UserDefaults, the default) and MemoryConsentStore (this run only).

ConsentCopy

Field Type Description
title String Alert title
body String Explanation
recorded [String] What is recorded; empty hides the section
notRecorded [String] What is never recorded; empty hides the section
recordedLabel String Heading for recorded
notRecordedLabel String Heading for notRecorded
closing String Closing sentence
accept String Accept button
decline String Decline button

Every field has an English default; pass only the ones you change.

SessionInfo

From DeaBase.

Field Type Description
session String Current session id, a UUID
device DeviceRecord Current device information
sdk.version String SDK version
sdk.core String Core build
startedAt Int When the session started, Unix milliseconds

DeviceRecord

From DeaBase.

Field Type Description
runtime Runtime .ios
os OperatingSystem Operating system
surface Surface Screen size in points (width, height)
pixelRatio Double Pixels per point
rotation Int Screen rotation: 0, 90, 180 or 270
maxTouchPoints Int Simultaneous touches the screen supports
sensorRate Int The motion rate requested, in Hz, once motion data has arrived; 0 until then

CaptureEvent

From DeaBase. The input kinds the events option lists: .pointerDown, .pointerMove, .pointerUp, .pointerCancel, .wheel, .keyDown, .keyUp. CaptureEvent.pointerKinds is the first five.

KeyClass

From DeaBase. The kind of key captureKey reports: .letter, .digit, .space, .delete, .navigation, .modifier, .other. KeyClass.of(_ character: String) classes one typed character as .letter (any script), .digit, .space or .other.

JSONValue

From DeaBase. A value in a captureEvent payload: .null, .bool, .int, .double, .string, .array([JSONValue]), .object([String: JSONValue]). String, integer, floating-point and Boolean literals convert automatically.

CoreCounts

Counted per session: reset() starts them again.

Field Type Description
samples Int Captured events that produced scored input
skipped Int Events accepted without producing scored input at that moment: custom events, lifecycle changes, scrolling and hover, and input held briefly to keep events in order
rejected Int Events refused. Above zero is a bug worth reporting to DEA
faults Int Internal errors the SDK recovered from
dropped Int Events skipped because the device could not keep up

Attestation

Field Type Description
supported Bool Whether a key could be created and an appKey was given
verdict Attestation.Verdict .passed, .failed or .unsupported
platformAttested Bool Whether an App Attest token went up with the key and DEA accepted it
platformTokenSpent Bool Whether this attempt used an App Attest attestation, whatever the result
expiresAt Int? Expiry, epoch seconds
kid String? Key identifier
tier String? Trust tier assigned by DEA
integrity String? DEA's reading of the device's integrity, when its answer carries one
backing String? Where the key is kept: secure_enclave or software
detail String? Why attestation did not pass

StopState

public struct StopState {
    let 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

ProofEvent

The ad event a proof records, signed as event_type.

Case rawValue When
.adImpression ad.impression The ad is on screen
.adClick ad.click The ad was clicked
.adEnded ad.ended The ad is gone

RecordOutcome

What sendProof returns.

Field Type Description
accepted Bool Whether DEA accepted the proof
signed SignedProof? The proof that was signed, or nil when nothing was
isSigned Bool Whether a proof was signed
said String? What DEA answered, or why nothing was signed or sent. nil when DEA accepted the proof with an empty answer
sessionId String? The session_id in DEA's answer, or nil when it named none. An accepted impression carries the ad session's id here; send the click and the end with it

SignedProof

What getProof returns, and RecordOutcome.signed. The fields are copies of what was signed, read back from the proof.

Field Type Description
proof String The proof, a compact JWS: header.payload.signature
score Double The human score signed into it, h_score
evidenceAt Int When the evidence behind the score ends, epoch seconds, h_ts
windows Int How many actions the score stands on, h_wc
modelVersion Int? The model that scored, h_mv; 0 for the one built into the SDK
sessionId String The session_id signed into it
event ProofEvent The event signed into it
header [String: Any]? The decoded header: alg, typ, kid
claims [String: Any]? The decoded claims, as signed
signature String? The signature segment, base64url

sdkVersion

let sdkVersion: String

The SDK version, the same as sessionInfo.sdk.version.