広告¶
インプレッションやクリックが実在の人物によるものであることを、広告パートナーに証明します。広告が画面に 表示された、クリックされた、消えたことをアプリが SDK に伝えると、SDK はユーザーが実際に広告に触れたかを 監視し、それぞれについて 1 つの証明に署名して DEA の記録サービス に送信し、サービスがそれを保管します。各広告は DEA 上で独自の 広告セッションを持ちます。これは SDK がスコアリングする セッションとは別のものです。
SDK は広告の要求、描画、ラップを行いません。広告スタックが引き続きそれを担います。
使いどころ¶
- 広告枠を販売しており、買い手に検証済みのヒューマントラフィックを示したい
- 無効なクリック(広告に触れずに申告されたもの)を除外したい
前提条件¶
- SDK がインストールされ、
appIdとappKeyで初期化されていること。 クイックスタートを参照してください。本番のappIdでappKeyがない場合、証明は 署名されません。 - ページが HTTPS で配信され、Content Security Policy が
connect-srcでhttps://poh-api.dep-protocol.comを許可していること。 Content Security Policy を参照してください。 - ブラウザーのキーが登録されていること。広告セッションを開く前に
attest()を呼び、'passed'を得てください。SDK が自らキーを登録することはなく、DEA は未登録のキーで署名されたすべての 証明を拒否します。
使い方¶
1. 広告が画面に表示されたら広告セッションを開く¶
import { DeaSdk } from '@dea/sdk';
const dea = DeaSdk.current!;
const container = document.querySelector('#ad-slot')!;
const attestation = await dea.attest(); // answers at once while the last registration is valid
const ad = attestation.verdict === 'passed'
? await dea.ads.session_opened(container, 'homepage_top')
: null;
session_opened(surface?, adUnit?) はインプレッションに署名して送信します。DEA のサービスが広告セッション
の ID ad.id を返します。SDK が ID を作ることはありません。クリックを実際のタッチと照合できるように、
広告が描画される要素と、広告が読み込まれた広告ユニットを渡してください。広告ユニットはインプレッション、
クリック、終了に署名して含められます。要素上のタッチは、session_opened() を呼んだ瞬間から、解決する前で
あっても数えられます。
SDK は広告を記録する前に分類を読み取りません。'bot' の結果でもインプレッションは止まらず、証明に含まれる
スコアが、その訪問がどれほど人間らしかったかをサービスに伝えます。ただし、セッションが
十分になるまで、つまりユーザーが
モデルの求める数の
アクションを行うまで(組み込みモデルでは、デスクトップ
ブラウザーで 20 個(ポインター、スクロール、キーボードのうち少なくとも 2 種類の入力から、それぞれ 3 個
以上)、スマートフォンやタブレットのブラウザーで 8 個。証拠
を参照)、証明は署名されません。それまでは session_opened() は null に解決し、インプレッションは記録
されません。SDK が後で送るために保持することもありません。したがって、ユーザーが操作する前のページ読み込み
時に表示された広告は記録されません。
インプレッションを必ず記録しなければならない場合は、session_opened() を呼ぶ前に
getClassification().result を読み取ってください。'insufficient' の間は後で(たとえばユーザーの次の操作
時に)再確認し、'insufficient' でなくなった時点で広告がまだ画面にあれば広告セッションを開きます。
null の後、ads.counts.notScored が呼び出し前より増えていれば、これが原因です。
session_opened() は、広告セッションを開けなかったとき null に解決します。appKey がない、ブラウザーの
キーがない、セッションがまだ十分でない、サービスがインプレッションを受理しなかった、のいずれかです。
ネットワークやサービスの障害時、SDK は証明が有効な 90 秒の間にインプレッションを最大 5 回試行するため、
session_opened() の解決にはそれだけの時間がかかることがあります。どのケースだったかを調べるには、
広告セッションが開かなかった理由を調べるを参照してください。
2. クリックと終了を宣言する¶
container.addEventListener('click', () => ad?.click()); // the user clicked it
ad?.end(); // the ad is gone
click()はクリックに署名して送信します。要素を渡していて、何もそれに触れていなかった場合、クリックは 拒否され、click()はfalseを返します。広告セッションごとにクリックは 1 回です。end()は広告セッションの終了に署名して送信し、要素を解放します。以降のclick()呼び出しは拒否されます。
次の広告は、新しい ID での新しい session_opened() 呼び出しです。SDK は一度に 1 つの要素を監視します。
2 つ目の広告の広告セッションを開くと 1 つ目の監視は止まり、その後の 1 つ目へのクリックは確認なしに受理
されます。
警告: SDK が見えるのはページ自身のドキュメント上の入力のみです。
<iframe>内(Google Publisher Tag や多くの広告サーバーがクリエイティブを描画する場所)でのプレスは、SDK にもコンテナ上のclickリスナーにも届きません。このようなクリエイティブでは SDK はタッチを目撃できず、コンテナを渡して開いた 広告セッションでのclick()は拒否されます。注:
end()は証明に非同期で署名・送信します。ページのアンロード中(pagehide)に呼ぶと、送信前に ブラウザーが要求をキャンセルすることがあります。end()はページがまだ開いている間、つまり広告が削除 または置き換えられたときに呼んでください。
広告セッションが開かなかった理由を調べる¶
session_opened() は理由なしに null に解決します。本番 SDK はログを出力しませんが、ads.counts は
試行ごとに変化します。呼び出しの前後で比較してください。
import { DeaSdk, type AdCounts } from '@dea/sdk';
const dea = DeaSdk.current!;
const before: AdCounts = dea.ads.counts;
const ad = await dea.ads.session_opened(document.querySelector('#ad-slot')!, 'homepage_top');
if (ad === null) {
const after = dea.ads.counts;
if (dea.appKey === null) {
console.warn('No appKey: nothing is signed on a production appId');
} else if (after.notScored > before.notScored) {
console.warn('The session is not sufficient yet: the impression was not recorded');
} else if (after.refused > before.refused) {
console.warn('Nothing signed: no browser key, or the scoring engine is not running');
} else if (after.delivery.dropped > before.delivery.dropped) {
console.warn('DEA refused the impression, or could not be reached before the proof expired');
} else if (after.delivery.sent > before.delivery.sent) {
console.warn('DEA accepted the impression but answered no ad session id');
}
}
| 変化したもの | 広告セッションが開かなかった理由 |
|---|---|
dea.appKey が null |
appKey のない本番の appId。何も署名も送信もされない |
notScored |
セッションがまだ十分でない(getClassification().result が 'insufficient')ため、インプレッションは署名も記録もされなかった。十分になった時点で広告がまだ画面にあれば、広告セッションを再度開く |
refused |
ブラウザーのキーがない(IndexedDB が拒否、Web Crypto がない)、またはスコアリングエンジンが動作していない。dea.error を確認する |
delivery.dropped |
DEA がインプレッションを拒否した(たとえばブラウザーのキーが未登録(先に attest() を呼ぶ)、または appKey がこの appId と一緒に発行されたキーではない)、または証明の期限内に DEA に到達できなかった |
delivery.sent |
DEA はインプレッションを受理したが、その応答に広告セッション ID が含まれていなかった |
カウントは呼び出しが解決した直後に読み取ってください。同時に実行中の 2 つの session_opened() 呼び出しは
同じカウントを動かします。
ステージングパッケージ(セットアップの確認を参照)も各試行をログに
出力します。結果 refused と not_scored や app_key_missing などの reason を持つ ad.impression、
および DEA が返した HTTP ステータスを持つ proof.rejected です。
例¶
Google Publisher Tag のバナー¶
Google Publisher Tag はクリエイティブを iframe 内に描画するため、そのクリックはページから宣言できません (上記の警告を参照)。この例ではインプレッションと終了を記録します。
import { DeaSdk, type AdSession } from '@dea/sdk';
let ad: AdSession | null = null;
googletag.cmd.push(() => {
const slot = googletag.defineSlot('/1234/homepage_top', [728, 90], 'ad-slot')!
.addService(googletag.pubads());
googletag.pubads().addEventListener('slotRenderEnded', async (event) => {
if (event.slot !== slot) return;
ad?.end(); // the slot rendered again: the previous ad is gone
ad = null;
if (event.isEmpty) return;
const dea = DeaSdk.current!;
const attestation = await dea.attest();
if (attestation.verdict === 'passed') {
ad = await dea.ads.session_opened(undefined, '/1234/homepage_top');
}
});
googletag.enableServices();
googletag.display('ad-slot');
});
広告セッションは要素なしで開かれます。SDK は iframe 内のタッチを見られないため、目撃するものがありません。 セッションが十分になる前に描画された広告は記録されません。 広告が画面に表示されたら広告セッションを開くを参照してください。
API¶
| メンバー | 戻り値 | 説明 |
|---|---|---|
ads.session_opened(surface?, adUnit?) |
Promise<AdSession \| null> |
広告が画面に表示された。インプレッションを送信する。セッションが十分でない間は null |
ads.counts |
AdCounts |
署名された証明、拒否された証明、まだスコアリングされていないもの、目撃されなかったクリック、配信 |
ad.id |
string |
DEA のサービスが作成した広告セッションの ID |
ad.click() |
boolean |
クリックを宣言する。拒否されない限り送信する |
ad.end() |
void |
広告が消えたことを宣言する。終了を送信する |
AdCounts:
| フィールド | 型 | 説明 |
|---|---|---|
signed |
number |
署名された証明。DEA が受理したかどうかは問わない |
refused |
number |
署名されなかった証明。appKey がない、ブラウザーのキーがない、またはスコアリングエンジンが動作していないか拒否した |
notScored |
number |
セッションがまだ十分でなかったため署名されなかった証明 |
unwitnessed |
number |
監視中の要素に何も触れなかったため拒否されたクリック |
delivery.sent |
number |
DEA が受理した証明 |
delivery.dropped |
number |
断念された証明。DEA が拒否した、または期限までにすべての試行が失敗した |
delivery.pending |
number |
送信中、または再試行を待っている証明 |