コンテンツにスキップ

広告

インプレッションやクリックが実在の人物によるものであることを、広告パートナーに証明します。広告の各瞬間 (表示中、クリック、終了)について、SDK は現在のスコアを端末キーで 証明に署名し、DEA の記録サービスに送ります。記録サービスは 後で検証できるようにそれを保持します。

SDK は広告の要求、描画、ラップは行いません。それは引き続きアプリの広告スタックが行います。

注: iOS には Web の広告モジュールではなく、証明の呼び出しがあります。3 つの証明は sendProof で 自分で送り、SDK はユーザーが広告に触れたかどうかを確認しません。

iOS にあるもの

Web SDK には広告モジュールがあります。ads.session_opened(surface?, adUnit?) がインプレッションを送り、id、click()、end() が残りを担う AdSession を解決し、 ads.counts が起きたことを数え、広告の要素に何も触れていなければクリックは拒否されます。iOS には モジュールもタッチの確認もありません。モジュールの土台となる呼び出し、sendProof、record、getProof があります。

Web iOS
広告が画面に表示される ads.session_opened(surface?, adUnit?) sendProof(event: .adImpression, sessionId: "") を呼び、DEA が応答した sessionId を保持する
広告がクリックされる ad.click() sendProof(event: .adClick, sessionId: id)
広告が消える ad.end() sendProof(event: .adEnded, sessionId: id, update: true)
クリックをタッチと照合する はい(広告の要素を渡した場合) いいえ: アプリが宣言する
広告ごとに 1 クリック、終了後は何もなし SDK が強制する アプリ側の責任
何が起きたか ads.counts 各呼び出しが返す RecordOutcome

使いどころ

  • 広告在庫を販売しており、買い手に検証済みのヒューマントラフィックを示したい
  • 広告の各インプレッション、クリック、終了を、その瞬間のスコアとともに記録したい

前提条件

  • SDK がインストールされ、appId と appKey で開始されている。クイックスタートを 参照してください。appKey がなければ何も送られません。
  • 端末キーが登録されている。インプレッションの前に attest() を呼び出し、 .passed を得てください。SDK は自分ではキーを登録せず、登録したかどうかも確認しません。登録がなくても 証明は署名されて送られますが、DEA は登録していないキーで署名されたあらゆる証明を拒否するのと同様に、 それらを拒否します。
  • requireConsent が有効(デフォルト)の場合、 ユーザーの同意。同意前は何も記録されないため、 セッションは決して 十分にならず、何も署名されません。

クイックスタートのホルダー:

import DeaSDK

enum Dea {
    /// The app's one DEA SDK instance. Nil until `start()` has run.
    private(set) static var sdk: DeaSdk?

    static func start() {
        guard sdk == nil else { return }
        let dea = DeaSdk(
            options: DeaSdkOptions(
                appId: "YOUR_APP_ID",
                appKey: "YOUR_APP_KEY"
            )
        )
        dea.start()
        sdk = dea
    }
}

使い方

sendProof はネットワーク要求を行い、それが終わるまで呼び出し元のスレッドをブロックします。 メインスレッドでは決して呼び出さないでください。

1. 広告が画面に表示されたらインプレッションを送る

import DeaSDK
import Foundation

DispatchQueue.global(qos: .utility).async {
    guard let dea = Dea.sdk, dea.attest().verdict == .passed else { return }

    let outcome = dea.sendProof(event: .adImpression, sessionId: "", adUnit: "YOUR_AD_UNIT")
    guard outcome.accepted, let adSessionId = outcome.sessionId else {
        print("DEA impression not recorded: \(outcome.said ?? "")")
        return
    }
    print("DEA ad session \(adSessionId)") // keep it for the click and the end
}
  • sessionId: "" を渡します。インプレッションは空のセッション id で送られ、DEA は開いた 広告セッションの id で応答します。outcome.sessionId がそれを持ちます。sessionId を省略すると、SDK は代わりに SDK 自身のセッションの id (sessionInfo.session)に署名しますが、これは広告セッションではありません。
  • adUnit は ad_unit として証明に署名されます。インプレッション、クリック、終了に同じものを渡して ください。
  • outcome.sessionId は、DEA がインプレッションを受け付けなかった場合や応答に id がなかった場合に nil です。その場合、クリックや終了を送る先の広告セッションはありません。

2. DEA の id でクリックと終了を送る

import DeaSDK
import Foundation

DispatchQueue.global(qos: .utility).async {
    guard let dea = Dea.sdk else { return }

    // The user clicked the ad.
    _ = dea.sendProof(event: .adClick, sessionId: adSessionId, adUnit: "YOUR_AD_UNIT")

    // Later: the ad is gone.
    _ = dea.sendProof(event: .adEnded, sessionId: adSessionId, adUnit: "YOUR_AD_UNIT", update: true)
}

adSessionId はステップ 1 の id です。インプレッションとクリックは POST /api/sessions として送られ、 update: true は終了を PUT /api/sessions/{adSessionId}、つまりインプレッションが開いた広告セッション の更新として送ります。この順序で、前のものが返ってから次を送ってください。下の例ではそのために 1 つの シリアルキューを使っています。

注: iOS ではクリックはタッチと照合されません。SDK はアプリが sendProof(event: .adClick, …) を 呼び出すたびに、ユーザーが何に触れたかを見ずにクリックに署名して送ります。2 回目のクリックや終了後の クリックも止めません。クリックを宣言するのはアプリです。広告 SDK がクリックを報告したときに、広告 ごとに 1 回送ってください。

各呼び出しの動作

  • sendProof は 1 つの証明に署名して送ります。RecordOutcome を返します。DEA が証明を受け付けたか、 証明そのもの、DEA の応答、DEA が応答した広告セッション id です。
  • record は同じ呼び出しで、DEA が証明を受け付けたかどうかだけを返します。
  • getProof は 1 つの証明に署名し、送らずに SignedProof として返します。独自の方法で証明を届ける アプリ向けです。

各呼び出しは署名の前に DEA に使い捨てのノンスを求めるため、getProof を含む 3 つすべてがブロック します。DEA がノンスを渡さない場合(appKey なし、応答なし、拒否)、証明はノンスなしで署名されます。 証明は、スコアリングエンジンが書き込み、端末キーで 署名された現在のスコアを持ちます。

sendProof と record はその後、証明を送ります。DEA が応答しないか 5xx で応答した場合、SDK は 2、4、8、16 秒後(それぞれ最大 1 秒を加えて)に再送し、最大 5 回送り、証明の 90 秒の有効期間を超えて 送ることはありません。各要求は最大 15 秒かかるため、要求がタイムアウトすると呼び出しは最大約 2 分 ブロックすることがあります。4xx の応答は最終です。

attestation パラメータは、証明に署名されるティアだけを 決めます。nil のままだと、SDK は保持している登録を使います。App Attest トークンで合格し (platformAttested)、期限切れでなければ B、それ以外は C です。extra は、証明の隣、署名の外側に あるリクエストボディに独自のフィールドを追加します。DEA はその中の何も信頼せず、証明そのものを置き換える こともありません。値は JSON 値である必要があります。

証明が記録されなかった理由を読み取る

sendProof は決して throw しません。accepted が false のとき、said が理由を示します。

理由 isSigned said
セッションがまだ十分でない false nothing signed: core refused -33: the session is not scored enough yet
この端末で端末キーを作成できなかった false no device key on this handset
スコアリングエンジンが動いていない(ready が false) false nothing signed: no core loaded, so nothing is composed
appKey がない: 何も送られない true no appKey: a production account must be given the key it was issued, DeaSdkOptions.appKey
DEA が証明を拒否した(4xx の応答) true パス、DEA のステータスとその文言。例: /api/sessions answered 401: …
DEA が応答しない、または 5xx で応答した(5 回) true 最後の失敗。例: unreachable: …
送信が通る前に証明が期限切れになった true proof expired before it was delivered

getProof は最初の 3 つの場合に nil を返します。開始したばかりのセッションは、 モデルが求める数(組み込みモデルでは 8)の アクションを持つまで十分ではありません (証拠を参照)。それまでは何も署名されないため、 その時点で送ったインプレッションは記録されず、SDK は後で送るために保持することもありません。拒否に 要求を費やすのではなく、例のようにインプレッションの前に getClassification().result が .insufficient でないことを確認してください。インプレッションが拒否されると、クリックと終了のための 広告セッションはありません。

広告を要求する前に分類を読み取る

広告を要求する前に分類を読み取り、自分の広告スタックでそれをどう扱うかを決めることもできます。 ヒューマンスコアリングを参照してください。

例

1 つの広告、表示から終了まで

import DeaSDK
import Foundation

/// The proofs for one ad, from on screen to gone. Each method returns at once; the proofs are
/// sent in order on a background queue.
final class AdProofs {
    private let adUnit: String
    private let queue = DispatchQueue(label: "ad-proofs") // serial: keeps the three in order
    private var adSessionId: String? // DEA's id for this ad, from the impression's answer
    private var hasClicked = false

    init(adUnit: String) {
        self.adUnit = adUnit
    }

    /// The ad is on screen.
    func shown() {
        queue.async { [self] in
            // Nothing is signed before the session is sufficient, and DEA refuses a proof
            // from a device key it has not registered.
            guard let dea = Dea.sdk,
                let result = (try? dea.getClassification())?.result,
                result != .insufficient,
                dea.attest().verdict == .passed
            else { return }

            let outcome = dea.sendProof(event: .adImpression, sessionId: "", adUnit: adUnit)
            if outcome.accepted, let id = outcome.sessionId {
                adSessionId = id
            } else {
                print("DEA impression not recorded: \(outcome.said ?? "")")
            }
        }
    }

    /// The user clicked the ad. Only the first click is sent.
    func clicked() {
        queue.async { [self] in
            guard let dea = Dea.sdk, let id = adSessionId, !hasClicked else { return }
            hasClicked = true

            let outcome = dea.sendProof(event: .adClick, sessionId: id, adUnit: adUnit)
            if !outcome.accepted {
                print("DEA click not recorded: \(outcome.said ?? "")")
            }
        }
    }

    /// The ad is gone: removed, replaced or dismissed.
    func gone() {
        queue.async { [self] in
            guard let dea = Dea.sdk, let id = adSessionId else { return }
            adSessionId = nil // nothing more is sent for this ad

            let outcome = dea.sendProof(
                event: .adEnded, sessionId: id, adUnit: adUnit, update: true)
            if !outcome.accepted {
                print("DEA end not recorded: \(outcome.said ?? "")")
            }
        }
    }
}

広告ごとに 1 つの AdProofs を作成し、広告 SDK のコールバックからそのメソッドを呼び出します。

let ad = AdProofs(adUnit: "YOUR_AD_UNIT")
ad.shown()   // your ad SDK reports the ad on screen
ad.clicked() // it reports a click
ad.gone()    // the ad is removed or dismissed

次の広告は新しい AdProofs で、そのインプレッションが新しい id の新しい広告セッションを開きます。

API

メンバー 戻り値 説明
sendProof(event:sessionId:attestation:adUnit:appScopedUid:extra:update:) RecordOutcome 1 つの証明に署名して送り、何が起きたかを返す。ブロックする
record(event:sessionId:attestation:adUnit:appScopedUid:extra:update:) Bool 同じ処理で、DEA が受け付けたかどうかだけを返す。ブロックする
getProof(event:sessionId:attestation:adUnit:appScopedUid:) SignedProof? 1 つの証明に署名し、送らない。ブロックする

ProofEvent: .adImpression、.adClick、.adEnded。

RecordOutcome:

フィールド 型 説明
accepted Bool DEA が証明を受け付けたかどうか
signed SignedProof? 署名された証明。何も署名されなかった場合は nil
isSigned Bool 証明が署名されたかどうか
said String? DEA の応答、または何も送られなかった理由。DEA が空の応答で受け付けた場合は nil
sessionId String? DEA が応答した広告セッション id。受け付けられたインプレッションで設定される

SignedProof とパラメータについては API リファレンスを参照してください。