広告¶
インプレッションやクリックが実在の人物によるものであることを広告パートナーに証明します。Flutter では、 広告が画面に表示された、クリックされた、消えたことをアプリが SDK に伝えます。SDK はそれぞれについて 端末キーで証明に署名し、それらを保管する DEA の記録サービスに 送信します。
SDK は広告を要求、描画、ラップしません。それは引き続き広告スタックの仕事です。
Flutter にあるもの¶
Flutter SDK には、DeaSdk 上の低レベルの証明呼び出し sendProof()、record()、getProof() が
あります。それぞれが広告イベント 1 件(ProofEvent.adImpression、adClick、または adEnded)の証明に、
その時点でスコアリングエンジンが持つスコアで署名
します。Web SDK の広告モジュールが代わりに行う 3 つの呼び出しを、アプリが同じ順序、同じ
広告セッション ID で行います。
Web SDK の広告モジュールがこれらの証明の上に追加しているものは ありません:
- 広告セッションオブジェクト。
ads.session_opened(surface?, adUnit?)、ad.id、ad.click()、ad.end()、ads.countsはありません。アプリが広告ごとに DEA の広告セッション ID を自分で保持し、各 証明を自分で送信します。 - ユーザーが広告に触れたかどうかのチェック。 Web SDK は広告の要素を監視し、何も触れていない クリックを拒否します。
注: Flutter ではクリックはタッチと照合されません。アプリが宣言し、SDK が署名します。クリックは 広告への実際のタップのハンドラーからのみ、広告ごとに最大 1 回、終了後には送らないでください。
Web モジュールと同様に、これらの呼び出しは分類を読み取りません。bot の結果でも証明は止まらず、証明の
中のスコアが、セッションがどれほど人間らしかったかを DEA に
伝えます。ただし、セッションが十分になるまで、つまり
モデルが求める数の
アクション(組み込みモデルでは 8。
証拠を参照)に達するまでは何も署名されません。
それより前は、各呼び出しは何も署名されなかったと答えます。そのため、その時点で報告された
インプレッションは記録されず、SDK が後で送るために保持することもありません。インプレッションを確実に
記録する必要がある場合は、その前に getClassification().result が insufficient でないことを確認して
ください。証明が受け入れられなかった理由を調べるを参照して
ください。
使いどころ¶
- 広告在庫を販売しており、買い手に検証済みの人間のトラフィックを示したい
- 各インプレッション、クリック、広告終了を、その時点のスコアとともに記録したい
前提条件¶
- SDK がインストールされ、このプラットフォームの
appIdとそのappKeyで初期化されている。 クイックスタートとアカウントとキーを 参照してください。 - 端末キーが登録されている。インプレッションの前に
attest()を呼び出し、Verdict.passedを得てください。証明呼び出しはキーを自分では登録せず、DEA は登録していないキーで 署名された証明を拒否します。
両方を DeaSdk.init に渡します。それぞれ、アプリが動作しているプラットフォームに対して発行された
値です:
import 'dart:io' show Platform;
import 'package:dea_sdk/dea_sdk.dart';
import 'package:flutter/material.dart';
void main() {
DeaSdk.init(
DeaOptions(
appId: Platform.isIOS ? 'YOUR_IOS_APP_ID' : 'YOUR_ANDROID_APP_ID',
),
appKey: Platform.isIOS ? 'YOUR_IOS_APP_KEY' : 'YOUR_ANDROID_APP_KEY',
);
runApp(const MyApp());
}
警告: 証明呼び出しは
appKeyやアテステーションを チェックしません。appKeyがないとattest()はunsupportedを返しますが、証明呼び出しはそれでも 署名して送信し、そのアプリキーはあなたのものではないため、DEA はそれらを拒否します。passedの アテステーションがなくても、やはり署名して送信し、証明は ティアCを主張します。
使い方¶
1 件の広告の 3 つの証明は、Web モジュールが送る順序どおりに、この順で送ります:
| ステップ | イベント | sessionId |
送信方法 |
|---|---|---|---|
| 広告が画面に表示される | ProofEvent.adImpression |
''(空) |
POST /api/sessions。DEA は広告のセッション ID を返す |
| ユーザーが広告をタップする | ProofEvent.adClick |
DEA の ID | POST /api/sessions |
| 広告が消える | ProofEvent.adEnded |
DEA の ID | PUT /api/sessions/{id}、update: true 付き |
広告のセッション ID は取得セッションではありません。getSessionInfo().session を渡さないでください。
sessionId にはデフォルトがないため、各呼び出しで指定します。
1. 広告が画面に表示されたらインプレッションを送る¶
final dea = DeaSdk.instance!;
final attestation = await dea.attest(); // answers at once while the last registration is valid
if (attestation.verdict != Verdict.passed) return;
final outcome = await dea.sendProof(
sessionId: '', // empty: DEA makes the ad's session id
event: ProofEvent.adImpression,
adUnit: 'home_banner',
);
final adSessionId = outcome.sessionId;
if (!outcome.accepted || adSessionId == null) return; // no session opened
sendProof() はインプレッションに署名して送信し、RecordOutcome で完了します。DEA が受け入れると、
outcome.sessionId が DEA がこの広告のために作成した ID になります。クリックと終了はこの ID で送ります。
インプレッションには record() ではなく sendProof() を使ってください。record() は true か false
しか返さないため、ID を得られません。
広告が読み込まれた広告ユニットを adUnit として渡します。これは ad_unit として証明に署名されます。
クリックと終了にも同じ値を渡してください。
2. クリックを送る¶
広告へのタップのハンドラーから:
await DeaSdk.instance?.sendProof(
sessionId: adSessionId,
event: ProofEvent.adClick,
adUnit: 'home_banner',
);
3. 終了を送る¶
広告が取り除かれた、置き換えられた、またはその画面が閉じたとき:
await DeaSdk.instance?.sendProof(
sessionId: adSessionId,
event: ProofEvent.adEnded,
adUnit: 'home_banner',
update: true, // PUT /api/sessions/{adSessionId}
);
update: true は、終了をインプレッションが開いたセッションの更新として送ります。SDK は代わりに設定して
くれません。すべての ProofEvent.adEnded で渡してください。
配信と再試行¶
- 各呼び出しはまず DEA に単回使用のノンスを求め、それを署名の中に含めます。DEA が返さない場合、証明は ノンスなしで署名されます。
- DEA に到達できない、または
5xxステータスが返った場合、sendProof()とrecord()は同じ証明を 2 秒後、次に 4、8、16 秒後(それぞれ最大 1 秒を加算)に再送し、合計で最大 5 回送信します。4xxの 応答は最終です。 - 証明は署名後 90 秒間有効で、それ以降は送信を開始しません。Future は最後の送信の後に完了するため、 1 分以上かかることがあります。
- 端末には何も保持されません。アプリが閉じられた時点で未送信の証明は失われます。
証明が受け入れられなかった理由を調べる¶
sendProof() は必ず理由付きで答えます。outcome.accepted が false のとき、outcome.said が理由を
示し、outcome.isSigned が何かが署名されたかどうかを示します:
isSigned |
said |
理由 |
|---|---|---|
false |
no device key on this handset |
この端末で端末キーを作成も読み取りもできなかった |
false |
nothing signed: core refused -33: the session is not scored enough yet |
セッションがまだ十分ではない。モデルが求める数(組み込みモデルでは 8)よりアクションが少なく、getClassification() は insufficient と報告する。何も送信されていないため、インプレッションは記録されない。広告がまだ表示されているなら、セッションが十分になってから再度送る |
false |
nothing signed: no core loaded, so nothing is composed |
スコアリングエンジンが動作していない。isScoring は false で、error に理由がある |
false |
nothing signed: the device key did not sign で始まる |
プラットフォームが端末キーでの署名を拒否した |
true |
HttpException: /api/sessions… answered 4xx、続けて DEA の応答 |
DEA が証明を拒否した。たとえば端末キーが登録されていない(先に attest() を呼ぶ)、または appKey が端末キーの登録先のアプリではない |
true |
HttpException: /api/sessions… answered 5xx、または別のエラー |
5 回の送信すべてで DEA が失敗した、または到達できなかった、または応答を読み取れなかった |
true |
proof expired before it was delivered |
署名後 90 秒の証明の有効期限内に DEA に到達できなかった |
said は、診断画面などで人が読むためのテキストです。accepted が true のとき、said は DEA の応答、
または応答が空だった場合は null です。
注: DEA が受け入れたインプレッションでも、DEA の応答がセッション ID を含まなかった場合、
outcome.sessionIdがnullのままになることがあります。セッションは開かれていないので、クリックや 終了を送らないでください。
送信せずに署名する¶
getProof() は証明に署名し、送信せずに SignedProof として返します。sendProof() と同じ sessionId、
event、attestation、adUnit、appScopedUid を受け取り、上の表の理由で何も署名されなかった場合は
null を返します。
final signed = await DeaSdk.instance?.getProof(
sessionId: '',
event: ProofEvent.adImpression,
adUnit: 'home_banner',
);
final jws = signed?.proof; // compact JWS, valid for 90 seconds
SDK は getProof() の証明を再試行も配信もしません。証明を別の方法で DEA に送るのでなければ、
sendProof() を使ってください。
広告を要求する前に分類を読み取る¶
証明は、すでに表示した広告を記録するものです。広告を要求するかどうか自体を決めるには、まず分類を 読み取り、その扱いを自身の広告スタックの中で決めてください。 ヒューマンスコアリングを参照してください。
例¶
1 件の広告、インプレッションから終了まで¶
import 'dart:io' show Platform;
import 'package:dea_sdk/dea_sdk.dart';
/// Call once in main(), before runApp().
void initDea() {
final ios = Platform.isIOS;
DeaSdk.init(
DeaOptions(appId: ios ? 'YOUR_IOS_APP_ID' : 'YOUR_ANDROID_APP_ID'),
appKey: ios ? 'YOUR_IOS_APP_KEY' : 'YOUR_ANDROID_APP_KEY',
);
}
/// The proofs of one ad: the impression, at most one click, and the end.
class AdProofs {
AdProofs(this.adUnit);
final String adUnit;
/// DEA's session id for this ad, from its answer to the impression.
String? _sessionId;
bool _clicked = false;
bool _ended = false;
/// The ad is on screen. Returns why no session opened, or null when one did.
Future<String?> shown() async {
final dea = DeaSdk.instance;
if (dea == null) return 'DeaSdk.init has not run';
final attestation = await dea.attest();
if (attestation.verdict != Verdict.passed) {
return 'device key not registered: ${attestation.detail}';
}
final outcome = await dea.sendProof(
sessionId: '', // empty: DEA makes the session id
event: ProofEvent.adImpression,
adUnit: adUnit,
);
if (!outcome.accepted) return outcome.said ?? 'not accepted';
final id = outcome.sessionId;
if (id == null) return 'DEA answered no session id';
_sessionId = id;
return null;
}
/// The user tapped the ad. Call it from your ad's click callback.
Future<void> clicked() async {
final id = _sessionId;
if (id == null || _clicked || _ended) return;
_clicked = true;
await DeaSdk.instance?.sendProof(
sessionId: id,
event: ProofEvent.adClick,
adUnit: adUnit,
);
}
/// The ad is gone: removed, replaced, or its screen closed.
Future<void> ended() async {
final id = _sessionId;
if (id == null || _ended) return;
_ended = true;
await DeaSdk.instance?.sendProof(
sessionId: id,
event: ProofEvent.adEnded,
adUnit: adUnit,
update: true, // PUT /api/sessions/{id}
);
}
}
表示する広告ごとに AdProofs を 1 つ作成し、その広告に対する広告 SDK のコールバックから shown()、
clicked()、ended() を呼び出します。次の広告は新しい AdProofs であり、DEA は新しい ID を与えます。
API¶
| メンバー | 戻り値 | 説明 |
|---|---|---|
sendProof({sessionId, event, …}) |
Future<RecordOutcome> |
証明 1 件に署名して送信する。結果には DEA のセッション ID、または受け入れられなかった理由が含まれる |
record({sessionId, event, …}) |
Future<bool> |
同じ送信。DEA が証明を受け入れたとき true |
getProof({sessionId, event, …}) |
Future<SignedProof?> |
証明 1 件に送信せずに署名する。何も署名されなかったとき null |
ProofEvent |
— | adImpression、adClick、adEnded |
各パラメーターについては API リファレンスを参照してください。