広告¶
インプレッションやクリックが実在の人物によるものであることを広告パートナーに証明します。Android では、広告が 画面に表示されたとき、クリックされたとき、消えたときにアプリが SDK に伝えます。SDK はそのたびに セッションの現在のスコアに端末キーで署名し、 証明を DEA の記録サービスに送信します。
SDK は広告の要求、描画、ラップを行いません。それは引き続きアプリの広告スタックの役割です。
注: Android には広告セッションオブジェクトがありません。 代わりに低レベルの証明呼び出し
sendProof、record、getProofがあり、アプリが広告セッションの id を保持し、 各イベントを自分で宣言します。Web SDK との比較を参照してください。
使いどころ¶
- 広告枠を販売しており、購入者に検証済みの人間のトラフィックを示したいとき
- 各インプレッション、クリック、広告の終了に、それが発生したセッションのスコアで署名したいとき
Web SDK との比較¶
Web SDK の広告モジュールはより多くの処理を担います。Android では次のとおりです。
| Web | Android |
|---|---|
ads.session_opened(surface?, adUnit?) がインプレッションを送信し、AdSession で解決する |
sendProof(ProofEvent.AD_IMPRESSION, sessionId = "") がインプレッションを送信する。RecordOutcome の sessionId は自分で保持する |
ad.click() |
sendProof(ProofEvent.AD_CLICK, sessionId = id) |
ad.end() |
sendProof(ProofEvent.AD_ENDED, sessionId = id, update = true) |
| 監視対象の要素に何も触れていないクリックは拒否される | 確認されない。アプリが宣言すればクリックは署名される |
広告セッションごとにクリックは 1 回、end() の後はなし |
強制されない。アプリが決める |
ads.counts |
各呼び出しの RecordOutcome |
証明はバックグラウンドで送信され、click() と end() は即座に戻る |
各呼び出しは DEA が応答するか配信を断念するまでブロックする。メインスレッド以外で呼び出す |
前提条件¶
- SDK がインストールされ、
appIdとappKeyで初期化されている。クイックスタートを参照して ください。appKeyがないと、sendProofとrecordは何も署名・送信しません。 - 端末キーが登録されている。最初の広告の前に
attest()を呼び出してPASSEDを得て ください。SDK は自動ではキーを登録せず、DEA は署名したキーが同じアプリの下に登録されている場合にのみ証明を 受け付けます。登録がなくても SDK は署名しますが、その証明はティアCを主張します。Bを主張するのは、Play Integrity トークンを伴うPASSEDの登録があり、それが期限切れ でない場合だけです。
使い方¶
1 つの広告のイベントを送信する¶
広告セッションは次の順序で 3 つの証明を取ります。
- インプレッション。
sessionIdは空にします。DEA が広告セッションを開き、その id を返します。id はRecordOutcome.sessionIdとして届きます。sessionIdを省略しないでください。デフォルトは取得セッションの id(sessionInfo.session)であり、広告セッションの id ではありません。 - クリック(ある場合)。DEA が返した id を使います。
- 終了。同じ id と
update = trueを使います。これにより、新しいセッションではなくその広告セッションの 更新(PUT /api/sessions/{id})として送信されます。
3 つすべてに同じ adUnit を渡してください。各証明に署名されて含まれます。
各呼び出しはブロックします。DEA からチャレンジを取得し、署名し、送信します。DEA に到達できない、または サーバーエラーが返った場合、SDK は証明を再送します。送信は合計で最大 5 回、署名から 90 秒後の証明の期限切れ 以降は行いません。したがって、呼び出しはその程度の時間ブロックすることがあります。次のクラスは各呼び出しを コルーチンで実行します。
import ai.dea.sdk.DeaSdk
import ai.dea.sdk.attest.Verdict
import ai.dea.sdk.proof.ProofEvent
import android.util.Log
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch
/** DEA's proofs for one ad. Create one for each ad you show. */
class AdProofs(private val scope: CoroutineScope, private val adUnit: String) {
@Volatile private var sessionId: String? = null
@Volatile private var clickSent = false
/** The ad is on screen. */
fun shown() {
scope.launch(Dispatchers.IO) {
val dea = DeaSdk.instance ?: return@launch
if (dea.attest().verdict != Verdict.PASSED) return@launch
// An empty session id: DEA opens the ad session and answers with its id.
val impression = dea.sendProof(ProofEvent.AD_IMPRESSION, sessionId = "", adUnit = adUnit)
sessionId = impression.sessionId
if (impression.sessionId == null) Log.w("MyApp", "No ad session: ${impression.said}")
}
}
/** The user clicked the ad. */
fun clicked() {
val id = sessionId ?: return // no ad session, or the ad has ended
if (clickSent) return // one click per ad session
clickSent = true
scope.launch(Dispatchers.IO) {
val click = DeaSdk.instance?.sendProof(ProofEvent.AD_CLICK, sessionId = id, adUnit = adUnit)
if (click?.accepted != true) Log.w("MyApp", "Click not recorded: ${click?.said}")
}
}
/** The ad is gone: removed or replaced. */
fun ended() {
val id = sessionId ?: return
sessionId = null
scope.launch(Dispatchers.IO) {
DeaSdk.instance?.record(ProofEvent.AD_ENDED, sessionId = id, adUnit = adUnit, update = true)
}
}
}
広告が画面に表示されたら shown()、クリックされたら clicked()、削除または置き換えられたら ended() を、
たとえば広告 SDK のコールバックから呼び出します。Application が保持するスコープなど、画面より長く生きる
スコープを渡してください。広告は画面が閉じるときに終了することが多く、画面とともにキャンセルされるスコープでは
終了が送信されません。次の広告には新しい AdProofs を作ります。
DEA がインプレッションに応答する前のクリックや終了には、一緒に送る広告セッション id がありません。そのため、 Web SDK と同様に、このクラスはそれらについて何も送信しません。
注: Android では SDK はクリックをユーザーのタッチと照合しません。アプリがクリックを宣言し、SDK は広告に 何かが触れたかどうかにかかわらず署名します。
セッションが十分になるまで、つまり
モデルが求める数のアクション
(組み込みモデルでは 8。証拠を参照)が集まるまで、何も
署名されません。それ以前は sendProof は nothing signed: core refused -33 を返すため、そのときに宣言された
インプレッションは記録されず、SDK は後で送信するために保持することもしません。インプレッションを確実に記録する
必要がある場合は、まず getClassification().result が INSUFFICIENT でないことを確認してください。
証明が受け付けられなかった理由を調べる¶
sendProof は RecordOutcome を返します。DEA が証明を受け付けると accepted は true です。それ以外の場合、
isSigned が何かが署名されたかを、said がその理由を示します。
import ai.dea.sdk.DeaSdk
import ai.dea.sdk.proof.ProofEvent
import android.util.Log
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
/** Sends the impression; returns the ad session's id, or null. */
suspend fun openAdSession(adUnit: String): String? = withContext(Dispatchers.IO) {
val dea = DeaSdk.instance ?: return@withContext null
val outcome = dea.sendProof(ProofEvent.AD_IMPRESSION, sessionId = "", adUnit = adUnit)
when {
outcome.accepted -> Log.d("MyApp", "ad session ${outcome.sessionId}")
!outcome.isSigned -> Log.w("MyApp", "Nothing signed: ${outcome.said}")
else -> Log.w("MyApp", "Signed, not accepted: ${outcome.said}")
}
outcome.sessionId
}
said の先頭 |
理由 |
|---|---|
no appKey |
appKey が指定されていない。何も署名・送信されない |
no device key on this handset |
端末がキーを保持できない。Android 6.0 未満、または Keystore が拒否した |
nothing signed: core refused -33 |
セッションがまだ十分でない。モデルが求める数(組み込みモデルでは 8)よりアクションが少ない。何も送信されていない。広告がまだ表示中なら、getClassification().result が INSUFFICIENT でなくなった後にインプレッションを再送する |
nothing signed: no core loaded |
スコアリングエンジンが動作していない。coreFault を確認する |
nothing signed: the device key did not sign |
Keystore が署名を拒否した |
/api/sessions answered、終了の場合は /api/sessions/{id} answered |
DEA が続くエラーステータスで応答した。4xx は最終的なもので、たとえば端末キーが登録されていない(先に attest() を呼び出す)、または appKey が端末キーの登録先のアプリではない。5xx は再試行され、これはその最後の応答 |
unreachable |
5 回の送信で DEA に到達できなかった |
proof expired before it was delivered |
再試行が証明の 90 秒を超えた |
failed |
要求が他の理由で失敗した。たとえばメインスレッドで実行された。再試行されない |
インプレッションの後、accepted で sessionId が null の場合、DEA は証明を受け付けたが広告セッションを
指定しなかったことを意味します。その場合、クリックと終了に使う id はありません。
送信せずに署名する¶
getProof は 1 つのイベントに署名し、送信する代わりに証明を返します。証明を自分で配信するアプリ向けです。
sendProof と同じ event、sessionId、attestation、adUnit、appScopedUid を取り、チャレンジを取得する間
ブロックします。sendProof が nothing signed や no device key on this handset と言う場合には、理由なしに
null を返します。sendProof と異なり、appKey がなくても拒否されません。
広告を要求する前に分類を読む¶
証明の呼び出しは分類を読みません。セッションが十分になると、アプリが宣言したすべての広告はスコアにかかわらず 署名され、証明の中のスコアが、セッションがどれだけ人間らしかったかを DEA に伝えます。広告を要求するかどうか 自体を決めるには、まず分類を読み、自分の広告スタックでそれに基づいて行動してください。 ヒューマンスコアリングを参照してください。
API¶
| メンバー | 戻り値 | 説明 |
|---|---|---|
sendProof(event, sessionId, attestation, adUnit, appScopedUid, extra, update) |
RecordOutcome |
1 つの広告イベントに署名し、DEA に送信します。ブロックします |
record(event, sessionId, attestation, adUnit, appScopedUid, extra, update) |
Boolean |
同じ送信。DEA が証明を受け付けると true。ブロックします |
getProof(event, sessionId, attestation, adUnit, appScopedUid) |
SignedProof? |
1 つの広告イベントに署名し、送信はしません。ブロックします |
ProofEvent: AD_IMPRESSION、AD_CLICK、AD_ENDED。
RecordOutcome:
| フィールド | 型 | 説明 |
|---|---|---|
accepted |
Boolean |
DEA が証明を受け付けたかどうか |
isSigned |
Boolean |
証明が署名されたかどうか |
signed |
SignedProof? |
証明。何も署名されなかった場合は null |
said |
String? |
DEA の回答そのまま、または DEA に到達できなかった理由 |
sessionId |
String? |
DEA の回答の session_id。インプレッションの後は広告セッションの id |
すべてのパラメーターと SignedProof については API リファレンスを参照してください。