コンテンツにスキップ

Activities

Part of the Ads use case.

Record a human score for any bounded activity a user does on your page: 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.

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 appId and appKey. See the Quick Start.
  • Your page calls attest() once when it loads, and gets 'passed'.
  • 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. The comments give the order of the calls.

import { DeaSdk, type AdSession } from '@dea/sdk';

let record: Promise<AdSession | null> | null = null;

/** Call when an activity starts. Do not wait for it before you start the activity. */
export function activityStarted(activityId: string, userId?: string): void {
  record = openRecord(activityId, userId).catch(() => null);
}

async function openRecord(activityId: string, userId?: string): Promise<AdSession | null> {
  const dea = DeaSdk.current;
  if (dea === null) return null; // the SDK is not initialized

  // 1. Too early to score: a start call now makes no record.
  if (dea.getClassification().result === 'insufficient') return null;

  // 2. The browser key is registered. Answers at once while the last registration is valid.
  const attestation = await dea.attest();
  if (attestation.verdict !== 'passed') return null;

  // 3. Open the record: the SDK signs the score at the start and sends it.
  //    The third argument, which carries your app user id, needs 0.26.0 or later.
  return dea.ads.session_opened(undefined, activityId, { appScopedUid: userId });
}

/** Call when the same activity ends, while the page is still open. */
export async function activityEnded(): Promise<string | null> {
  const opened = await record;
  record = null;
  if (!opened) return null; // no record: see "Check the result"

  // 4. End the record: the SDK signs the score at the end and sends it.
  opened.end();
  return opened.id; // the record's id at DEA
}

Call them from your own code:

function onQuizStarted(): void {
  activityStarted('quiz_weekly', user.id); // do not wait for it
  startQuiz();
}

function onQuizFinished(): void {
  showResult();
  void activityEnded();
}

user.id, startQuiz and showResult stand for your own code.

Pass the app user id

The second argument of activityStarted is your app's id for the user. Since 0.26.0, the SDK signs it into the start and the end of the record as appScopedUid. Leave it out and no id is sent. See App user ids.

Check the result

session_opened() resolves null without a reason. Read dea.ads.counts before and after the call, as Ads shows.

Cause What moved in dea.ads.counts What to do
The session was not sufficient when the activity started notScored Nothing. The user had made too few actions before this activity
No browser key, or the SDK core is not running refused Read dea.error
DEA refused the proof, or did not answer within 90 seconds delivery.dropped Check that attest() passes, and that appKey is the key issued with your appId
DEA accepted the proof but answered no record id delivery.sent Tell your DEA contact

The staging package also writes each attempt to the SDK log: ad.impression with a reason, and proof.rejected with the HTTP status.

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 send later. This is most often the first activity after the page loads. 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 page is open A call made while the page 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 page loads 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
ads.session_opened(undefined, activityId, { appScopedUid }) Promise<AdSession \| null> Opens the record and sends the score at the start. null when no record opened. The third argument since 0.26.0
ad.end() void Ends the record and sends the score at the end
ad.id string The record's id at DEA
ads.counts AdCounts What happened to each proof. See Ads
getClassification() Classification Read result before the start call
attest() Promise<Attestation> Registers the browser key. See Attest