Activities¶
Part of the Ads use case.
Record a human score for any bounded activity a user does in your app: a game round, a quiz, a
lesson, a video. You use the ad module with an activity id in place of the ad unit. You open a
record when the activity starts and end it when the activity ends. DEA keeps one record for each
activity, with the human score at the start and the human score at the end. On this page,
"activity" means what the user does, not an Android Activity.
| Term | Meaning |
|---|---|
| Activity | One bounded thing a user does, from its start to its end: one game round, one quiz, one lesson, one video |
| Activity id | The text that names a kind of activity, such as quiz_weekly. You choose it and pass it to the SDK |
| Record | What DEA keeps for one activity: the activity id, the human score at the start, the human score at the end, and the time |
When to use it¶
- You want a human score for each game round, quiz, lesson or video
- You want to see how many of your activities real people complete
Prerequisites¶
- The SDK is installed and initialized with your
appIdandappKey. See the Quick Start. - Your app calls
attest()once when it starts, and getsPASSED. - The upload helper of the Ads page, from its section "Upload a proof", is in your app. The samples below use it.
- DEA has registered your activity ids. See Activity ids.
Activity ids¶
| Rule | Example |
|---|---|
Letters, digits, - and _ only |
quiz_weekly |
| 50 characters at most | game_puzzle_daily |
| One id for each kind of activity, unique in your app. Do not change it after the first record | lesson_intro |
DEA registers each activity id as an ad of your app, so that its records appear under your ads. Send your DEA contact one row for each activity id:
| Field | Rule | Example |
|---|---|---|
| Activity id | The rules above | quiz_weekly |
| Name | The name people read in reports, 255 characters at most | Weekly Quiz |
DEA keeps a record whose activity id it has not registered, but does not list it under your ads.
Usage¶
Record one activity¶
Open the record when the activity starts. End it when the activity ends. Each step is two calls:
getProof signs the score, and your upload helper sends it. The comments give the order of the
calls.
import ai.dea.sdk.ClassificationResult
import ai.dea.sdk.DeaSdk
import ai.dea.sdk.attest.Verdict
import ai.dea.sdk.proof.ProofEvent
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch
import kotlinx.coroutines.sync.Mutex
import kotlinx.coroutines.sync.withLock
/** The record of one activity. Create one for each activity. */
class ActivityRecord(
private val scope: CoroutineScope,
private val activityId: String,
private val userId: String? = null, // your app user id
) {
private val lock = Mutex() // the start goes up before the end
@Volatile private var recordId: String? = null
/** Call when the activity starts. */
fun started() = queued {
val dea = DeaSdk.instance ?: return@queued
// 1. Too early to score: a start call now makes no record.
val result = runCatching { dea.getClassification().result }.getOrNull()
if (result == ClassificationResult.INSUFFICIENT) return@queued
// 2. The device key is registered. Answers at once while the last registration is valid.
if (dea.attest().verdict != Verdict.PASSED) return@queued
// 3. Sign the score at the start. The session id is empty: DEA makes the record id.
val proof = dea.getProof(
ProofEvent.AD_IMPRESSION, sessionId = "", adUnit = activityId, appScopedUid = userId,
) ?: return@queued // not signed: read dea.lastProofRefusal
// 4. Send it: POST /api/sessions. Keep the record id from the answer.
val answer = DeaUpload.send(proof)
if (answer is Upload.Accepted) {
recordId = answer.body?.optString("session_id")?.takeIf { it.isNotEmpty() }
}
}
/** Call when the same activity ends. */
fun ended() = queued {
val id = recordId ?: return@queued // the start was not recorded
recordId = null
val dea = DeaSdk.instance ?: return@queued
// 5. Sign the score at the end, with the record id.
val proof = dea.getProof(
ProofEvent.AD_ENDED, sessionId = id, adUnit = activityId, appScopedUid = userId,
) ?: return@queued
// 6. Send it: PUT /api/sessions/{id}.
DeaUpload.send(proof, update = true)
}
// attest() and getProof() block, so every step runs off the main thread, in order.
private fun queued(block: suspend () -> Unit) {
scope.launch(Dispatchers.IO) { lock.withLock { block() } }
}
}
appScope stands for a scope that lives longer than the activity's screen, such as one your
Application holds: an activity often ends as its screen closes.
Call it from your own code:
val record = ActivityRecord(appScope, "quiz_weekly", userId)
record.started() // when the activity starts
// ...
record.ended() // when the same activity ends
Pass the app user id¶
userId is your app's id for the user. The class passes it as appScopedUid to both getProof
calls, so DEA stores it on the record. Leave it out and no id is sent. See
App user ids.
Check the result¶
| Cause | What you read | What to do |
|---|---|---|
| The session was not sufficient when the activity started | getProof returns null, and lastProofRefusal is not_scored |
Nothing. The user had made too few actions before this activity |
| No device key, or the SDK core is not running | lastProofRefusal is no_key or no_core |
See Troubleshooting |
A production appId without appKey |
lastProofRefusal is app_key_missing |
Pass your appKey to the SDK |
| DEA refused the proof, or did not answer | The upload answers a 4xx, or no answer after five sends |
Check that attest() passes, and that appKey is the key issued with your appId |
| DEA accepted the start but answered no record id | The answer has no session_id |
Tell your DEA contact |
Notes¶
| Note | Why |
|---|---|
| An activity that starts before the session is sufficient has no record | The SDK signs no score before the session is sufficient, and does not keep the start to sign later. This is most often the first activity after the app starts. A missing record does not mean that the user is a bot |
Read getClassification().result before the start call. When it is INSUFFICIENT, make the start call later, when it is not |
A start call made too early makes no record, and the SDK does not try it again |
| End the record while the app is open | An end sent while the app closes can be cancelled. The record then has no score at the end |
| End a record before you open the next one | The SDK follows one open record at a time |
| Do not wait for the start call before you start the activity | When the network fails, the start call can take up to 90 seconds |
Call attest() once when the app starts |
It answers at once while the last registration is valid, so the start of an activity does not wait for it |
| For an activity of a few seconds, record one whole level or one match, not each round | Each record costs two signed proofs and two requests |
API¶
| Member | Returns | Description |
|---|---|---|
getProof(event, sessionId, attestation, adUnit, appScopedUid) |
SignedProof? |
Signs the score. ProofEvent.AD_IMPRESSION with sessionId = "" for the start, ProofEvent.AD_ENDED with the record id for the end. Blocking |
lastProofRefusal |
String? |
Why the last getProof returned null |
getClassification() |
Classification |
Read result before the start call |
attest() |
Attestation |
Registers the device key. Blocking. See Attest |