最近の更新
- 今後の変更点と既知の問題のリストを更新しました。
- 完全なイベントレベルのブリッジとして、Lite の柔軟なイベントレベル構成を導入しました。 柔軟なイベントレベルの設定
- 2023 年 9 月より、
registerWebSource
、registerWebTrigger
、registerAppSource
とregisterAppTrigger
では、 数値(priority
、source_event_id
、debug_key
、trigger_data
、deduplication_key
など) - 2023 年第 4 四半期に、Android Attribution Reporting API で Google Cloud がサポートされるようになります。 Google の集計サービスを使用して概要レポートを生成するために追加できる より具体的なタイミングをここに反映しています。詳細については、導入ガイドをご覧ください。 設定に関する情報を確認する。
- 固有のリンク先の数に対するプライバシー保護のレート制限が新しく追加されました。
- ルックバック ウィンドウ トリガー フィルタの機能の更新は、2024 年第 1 四半期にリリースされる予定です。詳細については、注記をご覧ください。
概要
現在、モバイル アトリビューションと測定ソリューションでは、広告 ID などのクロスパーティ識別子を使用するのが一般的です。Attribution Reporting API は、クロスパーティ ユーザー ID への依存をなくすことでユーザーのプライバシーを向上させ、アプリとウェブを対象としたアトリビューションとコンバージョン測定の主要なユースケースをサポートするように設計されています。
この API には、プライバシーを向上させるためのフレームワークを提供する、次のような構造メカニズムが用意されています。詳細については、このページ内で別途説明します。
- イベントレベル レポートで使用できるビット数を制限する
- 集計可能レポートでのみ、忠実度の高いコンバージョン データを有効にする
- 利用可能なトリガー(コンバージョン)のレート制限と 1 つのアトリビューション ソースに関連付けることのできる広告テクノロジーの数を導入する
- さまざまなノイズ付加手法を組み込む
こうしたメカニズムにより、2 つの異なるアプリ間またはドメイン間でユーザー ID をリンクする機能が制限されます。
Attribution Reporting API では、次のユースケースがサポートされます。
- コンバージョン レポート: キャンペーン別、広告グループ別、広告クリエイティブ別など、さまざまなディメンションでコンバージョン(トリガー)数やコンバージョン(トリガー)値を表示して、広告主がキャンペーンのパフォーマンスを測定できるようにします。
- 最適化: ML モデルのトレーニングに使用できるインプレッションごとのアトリビューション データを提供することで、広告費の最適化をサポートするイベントレベルのレポートを提供します。
- 無効なアクティビティの検出: 無効なトラフィックと広告の不正行為の検出と分析に使用できるレポートを提供します。
Attribution Reporting API の動作の概要は次のとおりです。詳細についてはこのドキュメント内で別途説明します。
- 広告テクノロジーが、Attribution Reporting API を使用するための登録プロセスを完了する。
- 広告テクノロジーが、Attribution Reporting API にアトリビューション ソースを登録する(広告クリックまたは広告ビュー)。
- 広告テクノロジーが、Attribution Reporting API にトリガーを登録する(広告主のアプリまたはウェブサイトのユーザー コンバージョン)。
- Attribution Reporting API が、トリガーをアトリビューション ソース(コンバージョン アトリビューション)と照合し、1 つ以上のトリガーがイベントレベル レポートと集計可能レポートを通じてデバイスから広告テクノロジーに送信される。
Attribution Reporting API にアクセスする
Attribution Reporting API にアクセスするには、広告テクノロジー プラットフォームの登録が必要です。詳しくは、プライバシー サンドボックス アカウントの登録をご覧ください。
アトリビューション ソース(クリックまたはビュー)を登録する
Attribution Reporting API では、広告クリックと広告ビューを「アトリビューション ソース」と呼称します。広告クリックまたは広告ビューを登録するには、registerSource()
を呼び出します。この API には次のパラメータが必要です。
- アトリビューション ソース URI: プラットフォームは、アトリビューション ソースに関連付けられたメタデータを取得するために、この URI に対してリクエストを行います。
- 入力イベント:
InputEvent
オブジェクト(クリック イベントの場合)またはnull
(ビューイベントの場合)。
API がアトリビューション ソース URI にリクエストを行うと、広告テクノロジーは、次のフィールドを持つ新しい HTTP ヘッダー Attribution-Reporting-Register-Source
でアトリビューション ソースのメタデータを返します。
- ソースイベントの ID: この値は、関連付けられたイベントレベルのデータを表します。 関連付けられます。64 ビット符号なしにする必要があります。 文字列としてフォーマットされた整数。
- デスティネーション: eTLD+1 またはアプリのパッケージ名を持つオリジン。 トリガーイベントが発生します
- Expiry(省略可): ソースの有効期限(秒) 削除しました。デフォルトは 30 日であり、最小値は 1 日、最大値は 30 日です。この値は最も近い日に丸められます。可能 64 ビット符号なし整数または文字列のいずれかになります。
- イベント レポート ウィンドウ(省略可): 発生元から経過した期間(秒) このソースのイベント レポートが作成される場合があります。条件 イベント レポート ウィンドウが過ぎているが、まだ有効期限を過ぎていない場合は、 トリガーはソースと照合できますが、イベント レポートは一致しません。 トリガーに送信されます有効期限を超えることはできません。次の形式にできる: 64 ビット符号なし整数または文字列のいずれかを指定します。
- 集計可能レポート期間(省略可): ソース後の期間(秒) この期間中に集計可能レポートが作成されます。 あります。有効期限を超えることはできません。64 ビットまたは 符号なし整数または文字列を指定します
- ソースの優先度(省略可): どのアトリビューション ソースが
複数のアトリビューションがある場合は
関連付けられる可能性があります。符号付き 64 ビットである必要があります
文字列としてフォーマットされた整数。
トリガーを受信すると、API ソース優先度の値が最も高い、一致するアトリビューション ソースを見つける レポートが生成されます。各広告テクノロジー プラットフォームは、 優先順位付け戦略について説明します。優先度の影響について詳しくは、 優先順位付けの例のセクションをご覧ください。
高い 値の優先度が高いことを示します。 - インストールとインストール後のアトリビューション期間(省略可): このページで後述するインストール後のイベントのアトリビューションを決定するために使用します。
- データのフィルタ(省略可): 一部のトリガーを選択的にフィルタし、事実上無視するために使用します。詳細については、このページのトリガー フィルタをご覧ください。
- 集計キー(省略可): 集計可能レポートに使用するセグメンテーションを指定します。
必要に応じて、アトリビューション ソースのメタデータ レスポンスでは、アトリビューション レポート リダイレクト ヘッダーに追加データを含めることができます。このデータにはリダイレクト URL が含まれており、複数の広告テクノロジーがリクエストを登録できるようになります。
デベロッパー ガイドには、ソースの登録を受け入れる方法の例が記載されています。
ワークフローの例は次のとおりです。
広告テクノロジー SDK が API を呼び出してアトリビューション ソースの登録を開始し、API で呼び出す URI を指定します。
registerSource( Uri.parse("https://adtech.example/attribution_source?AD_TECH_PROVIDED_METADATA"), myClickEvent);
API が次のいずれかのヘッダーを使用して、
https://adtech.example/attribution_source?AD_TECH_PROVIDED_METADATA
にリクエストを行います。<!-- For click events --> Attribution-Reporting-Source-Info: navigation <!-- For view events --> Attribution-Reporting-Source-Info: event
この広告テクノロジーの HTTPS サーバーが、ヘッダーに次の内容を含めて応答します。
Attribution-Reporting-Register-Source: { "destination": "android-app://com.advertiser.example", "source_event_id": "234", "expiry": "60000", "priority": "5" } Attribution-Reporting-Redirect: https://adtechpartner1.example?their_ad_click_id=567 Attribution-Reporting-Redirect: https://adtechpartner2.example?their_ad_click_id=890
API が、
Attribution-Reporting-Redirect
で指定された各 URL にリクエストを行います。この例では、広告テクノロジー パートナー URL が 2 つ指定されているため、API はhttps://adtechpartner1.example?their_ad_click_id=567
とhttps://adtechpartner2.example?their_ad_click_id=890
のそれぞれにリクエストを行います。この広告テクノロジーの HTTPS サーバーが、ヘッダーに次の内容を含めて応答します。
Attribution-Reporting-Register-Source: { "destination": "android-app://com.advertiser.example", "source_event_id": "789", "expiry": "120000", "priority": "2" }
ここまでのステップで示したリクエストに基づいて、3 つのナビゲーション(クリック)アトリビューション ソースが登録されます。
WebView からアトリビューション ソースを登録する
WebView は、アプリが WebView 内で広告をレンダリングするユースケースをサポートします。
WebViewこれは、WebView が registerSource()
を
ダウンロードされます。この呼び出しにより、アトリビューション ソースがアプリに関連付けられます。
オリジンを指定します埋め込みウェブ コンテンツからのソースの登録
ブラウザ コンテキスト内でもサポートされています。API 呼び出し元とアプリの両方で、
そのように設定を調整します。アトリビューション ソースの登録とトリガー元
WebView をご覧ください。
手順については、WebView からのアトリビューション ソースとトリガーの登録をご覧ください。
アプリ
広告テクノロジーはウェブと WebView で共通のコードを使用するため、WebView は HTTP 302 に従います。
リダイレクトし、有効な登録をプラットフォームに渡します。計画
Attribution-Reporting-Redirect
ヘッダーをサポートする必要がありますが、
影響を受けるユースケースがある場合は、お問い合わせください。
トリガー(コンバージョン)を登録する
広告テクノロジー プラットフォームは registerTrigger()
メソッドを使用してトリガー(インストールまたはインストール後のイベントなどのコンバージョン)を登録できます。
registerTrigger()
メソッドにはトリガー URI パラメータが必要です。API は、トリガーに関連付けられたメタデータを取得するために、この URI に対してリクエストを実行します。
API はリダイレクトに従います。広告テクノロジー サーバーのレスポンスには、1 つ以上の登録済みトリガーの情報を表す、Attribution-Reporting-Register-Trigger
という HTTP ヘッダーが含まれている必要があります。ヘッダーの内容は
JSON エンコード
次のフィールドを含めます
- トリガーデータ: トリガー イベントを識別するためのデータ(クリックの場合は 3 ビット、1 視聴回数です。文字列形式の 64 ビット符号付き整数を指定する必要があります。
- トリガーの優先度(省略可): このトリガーの優先度を表します。 同じアトリビューション ソースの他のトリガーと比較します。64 ビットである必要があります 文字列形式の符号付き整数です。優先度の詳細については レポートに与える影響については、優先順位付けのセクションをご覧ください。
- 重複除去キー(省略可): 同じ重複除去のケースを特定するために使用します。 同じ広告テクノロジー プラットフォームによって複数回登録された 同じアトリビューションソースが必要です64 ビット符号付き整数を 使用します。
- 集計キー(省略可): 集計キーを指定する辞書のリストと、値を集計する必要のある集計可能レポートを指定します。
- 集計値(省略可): 各キーに影響する値の量のリスト。
- フィルタ(省略可): トリガーまたはトリガーデータを選択的にフィルタするために使用されます。詳細については、このページのトリガー フィルタをご覧ください。
必要に応じて、広告テクノロジー サーバーのレスポンスでは、アトリビューション レポート リダイレクト ヘッダーに追加データを含めることができます。このデータにはリダイレクト URL が含まれており、複数の広告テクノロジーがリクエストを登録できるようになります。
複数の広告テクノロジーが、Attribution-Reporting-Redirect
フィールドでリダイレクトを使用するか、registerTrigger()
メソッドを複数回呼び出して、同じトリガー イベントを登録できます。同じ広告テクノロジーが同じトリガー イベントに対して複数のレスポンスを提供する場合、レポートに重複するトリガーが含まれないように、重複除去キーフィールドを使用することをおすすめします。重複除去キーを使用する方法とタイミングについてご確認ください。
デベロッパー ガイドには、トリガーの登録を受け入れる方法の例が記載されています。
ワークフローの例は次のとおりです。
事前登録した URI を使用して、広告テクノロジー SDK が API を呼び出してトリガーの登録を開始します。詳しくは、プライバシー サンドボックス アカウントの登録をご覧ください。
registerTrigger( Uri.parse("https://adtech.example/attribution_trigger?AD_TECH_PROVIDED_METADATA"));
API が
https://adtech.example/attribution_trigger?AD_TECH_PROVIDED_METADATA
にリクエストを行います。この広告テクノロジーの HTTPS サーバーが、ヘッダーに次の内容を含めて応答します。
Attribution-Reporting-Register-Trigger: { "event_trigger_data": [{ "trigger_data": "1122", // This returns 010 for click-through conversions (CTCs) and 0 for // view-through conversions (VTCs) in reports "priority": "3", "deduplication_key": "3344" }], } Attribution-Reporting-Redirect: https://adtechpartner.example?app_install=567
API が、
Attribution-Reporting-Redirect
で指定された各 URL にリクエストを行います。この例では URL が 1 つしか指定されていないため、API はhttps://adtechpartner.example?app_install=567
にリクエストを行います。この広告テクノロジーの HTTPS サーバーが、ヘッダーに次の内容を含めて応答します。
Attribution-Reporting-Register-Trigger: { "event_trigger_data":[{ "trigger_data": "5566", "priority": "3", "deduplication_key": "3344" }] }
ここまでのステップのリクエストに基づいて、2 つのトリガーが登録されます。
アトリビューションの機能
次のセクションでは、Attribution Reporting API がコンバージョン トリガーとアトリビューション ソースを照合する仕組みについて説明します。
ソース優先アトリビューション アルゴリズムの適用
Attribution Reporting API は、トリガー(コンバージョン)をアトリビューション ソースに一致させるためにソース優先アトリビューション アルゴリズムを適用します。
優先度パラメータは、トリガーのアトリビューションをソースにカスタマイズする方法を提供します。
- トリガーを他のものよりも特定の広告イベントに強く関連付けることができます。たとえば、ビューよりもクリックを重視する場合や、特定のキャンペーンのイベントを重視する場合が考えられます。
- アトリビューション ソースとトリガーは、レート制限に達した場合に、より重要性の高いレポートが届く可能性が高くなるように構成できます。たとえば、入札可能なコンバージョンや価値の高いコンバージョンがレポートに現れる可能性を高めることができます。
このページで後述するように、複数の広告テクノロジーがアトリビューション ソースを登録する場合、このアトリビューションは広告テクノロジーごとに独立して行われます。広告テクノロジーごとに、優先度が最も高いアトリビューション ソースがトリガー イベントに関連付けられます。同じ優先度のアトリビューション ソースが複数ある場合、API は最後に登録されたアトリビューション ソースを選択します。選択されなかった他のアトリビューション ソースは破棄され、今後のトリガー アトリビューションの対象ではなくなります。
トリガー フィルタ
ソースとトリガーの登録には、次を行うためのオプション機能も含まれています。
- 一部のトリガーを選択的にフィルタし、事実上無視する。
- ソースデータに基づいてイベントレベル レポートのトリガーデータを選択する。
- トリガーをイベントレベル レポートから除外する。
広告テクノロジーでトリガーを選択的にフィルタするには、ソースとトリガーの登録時に、キーと値で構成されるフィルタデータを指定します。ソースとトリガーの両方に同じキーが指定されている場合、共通部分が空であればトリガーが無視されます。たとえば、ソースに "product": ["1234"]
を指定した場合、product
がフィルタキーで、1234
が値です。トリガー フィルタが "product": ["1111"]
に設定されている場合、このトリガーは無視されます。product
に一致するトリガー フィルタ キーがない場合、フィルタは無視されます。
広告テクノロジー プラットフォームがトリガーを選択的にフィルタするもう一つのシナリオ
より短い有効期限を強制することですトリガーの登録時に、広告テクノロジーは
コンバージョン発生からのルックバック ウィンドウを秒単位で指定します。
たとえば、7 日間のルックバック ウィンドウは、"_lookback_window":
604800 // 7d
のように定義されます。
フィルタに一致するかどうかを判断するために、API はまずルックバック ウィンドウを確認します。条件 ソースが登録されてからの期間を短くするか、それより短くする必要があります。 指定することもできます
広告テクノロジー プラットフォームでは、ソース イベント データに基づいてトリガーデータを選択することもできます。たとえば、source_type
は API が navigation
または event
として自動的に生成します。トリガーの登録時、trigger_data
で、ある値を "source_type": ["navigation"]
に設定し、別の値を "source_type": ["event"]
に設定することができます。
次のいずれかに該当する場合、トリガーはイベントレベル レポートから除外されます。
trigger_data
が指定されていない。- ソースとトリガーで同じフィルタキーが指定されているが、値が一致しない。この場合、イベントレベル レポートと集計可能レポートのどちらでも、トリガーは無視されます。
インストール後のアトリビューション
場合によっては、最近発生した他の有効なアトリビューション ソースがあったとしても、インストール後のトリガーを、インストールにつながった同じアトリビューション ソースに帰属させる必要があります。
API では、広告テクノロジーがインストール後のアトリビューション期間を設定できるようにすることで、このユースケースをサポートできます。
- アトリビューション ソースを登録する際、インストールが予想される、インストールのアトリビューション期間を指定します(許容範囲は 1~30 日間、通常は 2~7 日間)。この期間は秒数で指定します。
- アトリビューション ソースを登録する際、インストール後のアトリビューション除外期間を指定します(許容範囲は 0~30 日間、通常は 7~30 日間)。この期間については、インストール後のトリガー イベントをインストールにつながったアトリビューション ソースに関連付ける必要があります。この期間は秒数で指定します。
- Attribution Reporting API は、アプリのインストールがいつ行われたかを検証し、内部的にインストールをソース優先アトリビューション ソースに帰属させます。ただし、このインストールは広告テクノロジーには送信されず、プラットフォームのそれぞれのレート制限にカウントされません。
- アプリのインストールの検証は、ダウンロードしたすべてのアプリで可能です。
- インストール後のアトリビューション期間内に発生する今後のトリガーは、そのアトリビューション ソースが有効である限り、検証済みのインストールと同じアトリビューション ソースに帰属します。
将来的には、より高度なアトリビューション モデルをサポートするために設計の拡張を検討する可能性があります。
次の表に、広告テクノロジーでインストール後のアトリビューションを使用する例を示します。すべてのアトリビューション ソースとトリガーが同じ広告テクノロジー ネットワークによって登録されていて、すべての優先度が同じであるとします。
イベント | イベントが発生する日 | 備考 |
---|---|---|
クリック 1 | 1 | install_attribution_window を 172800 (2 日間)に設定し、post_install_exclusivity_window を 864000 (10 日間)に設定します。 |
検証済みインストール | 2 | この API は、検証済みのインストールを内部的に関連付けますが、トリガーとはみなされません。したがって、この時点でレポートは送信されません。 |
トリガー 1(初回起動) | 2 | 広告テクノロジーによって最初に登録されたトリガー。この例では、初回起動を表していますが、任意のトリガータイプを指定できます。 クリック 1 に関連付けされます(検証済みインストールのアトリビューションに一致)。 |
クリック 2 | 4 | install_attribution_window と post_install_exclusivity_window には、クリック 1 と同じ値を使用します。 |
トリガー 2(インストール後) | 5 | 広告テクノロジーによって登録された 2 つ目のトリガー。この例では、購入などのインストール後コンバージョンを表しています。 クリック 1 に関連付けされます(検証済みインストールのアトリビューションに一致)。 クリック 2 は破棄され、将来のアトリビューションの対象外となります。 |
インストール後のアトリビューションに関するその他の注意事項は次のとおりです。
- 検証済みインストールが
install_attribution_window
で指定された日数以内に発生しない場合、インストール後のアトリビューションは適用されません。 - 検証済みのインストールは、広告テクノロジーでは登録されず、レポートにも送信されません。広告テクノロジーのレート制限にはカウントされません。検証済みインストールは、そのインストールに貢献しているアトリビューション ソースの識別にのみ使用されます。
- 上の表の例では、トリガー 1 とトリガー 2 がそれぞれ初回起動とインストール後のコンバージョンを表しています。ただし広告テクノロジーは 任意のタイプのトリガーを登録できます。つまり、最初の 初回起動トリガーである必要はありません
post_install_exclusivity_window
の期限が切れた後にトリガーがさらに登録された場合でも、期限内かつレート制限に達していないことを前提として、クリック 1 はアトリビューションの対象となります。- それでも、優先度の高いアトリビューション ソースが登録されている場合は、クリック 1 が失われるか、破棄される可能性があります。
- 広告主のアプリがアンインストールされ、再インストールされた場合、再インストールは新しい検証済みインストールとしてカウントされます。
- 一方、クリック 1 がビューイベントだった場合、「初回起動」トリガーとインストール後トリガーの両方が関連付けられます。この API では、アトリビューションが、ビューごとに 1 つのトリガーに制限されます。ただし、インストール後のアトリビューションの場合は、ビューごとに 2 つまでのトリガーが許容されます。インストール後のアトリビューションの場合、広告テクノロジーで 2 つの異なるレポート期間(2 日またはソースの有効期限)を受け取ることができます。
アプリベースとウェブベースのトリガーパスのすべての組み合わせをサポート
Attribution Reporting API を使用すると、1 台の Android デバイスで次のトリガーパスのアトリビューションが可能になります。
- アプリからアプリ: アプリでユーザーに広告が表示されてから、そのアプリまたは別のインストール済みアプリでコンバージョンを実行します。
- アプリからウェブ: アプリでユーザーに広告が表示されてから、モバイルまたはアプリのブラウザでコンバージョンを実行します。
- ウェブからアプリ: モバイルまたはアプリのブラウザでユーザーに広告が表示されてから、アプリでコンバージョンを実行します。
- ウェブからウェブ: モバイルまたはアプリのブラウザでユーザーに広告が表示されてから、同じブラウザまたは同じデバイス上の別のブラウザでコンバージョンを実行します。
ウェブブラウザでは、新しいウェブ公開機能をサポートすることが可能です。ウェブの Attribution Reporting API 用のプライバシー サンドボックスと同様の機能などで、Android API を呼び出してアプリとウェブを対象にアトリビューションを有効にできます。
アプリとウェブにわたる測定のトリガーパスをサポートするために、広告テクノロジーとアプリで行う必要がある変更についてご確認ください。
1 つのアトリビューション ソースに対する複数のトリガーに優先度を設定する
1 つのアトリビューション ソースが複数のトリガーにつながることがあります。たとえば、1 つの購入フローに、1 つの「アプリのインストール」トリガー、1 つ以上の「カートに追加」トリガー、1 つの「購入」トリガーが含まれる場合があります。各トリガーは、このページで後述するソース優先アトリビューション アルゴリズムに従って、1 つ以上のアトリビューション ソースに帰属します。
1 つのアトリビューションに関連付けられるトリガーの数には上限がある source;詳しくは、測定データの表示に関するセクションを アトリビューション レポートも後ほど説明します。複数のゾーンに 複数のトリガーを設定できるため、優先順位を 最も価値のあるトリガーを取り出しますたとえば、Cloud Shell の開発者は 広告テクノロジーが「購入」を優先する場合「カートに追加」に対するトリガー 使用できます。
このロジックをサポートするには、トリガーに個別の優先度フィールドを設定します。特定のレポート期間内で、制限が適用される前に最も優先度の高いトリガーが選択されます。
複数の広告テクノロジーがアトリビューション ソースまたはトリガーを登録できるようにする
複数の広告テクノロジーがアトリビューション レポートを受け取ることは一般的であり、通常はクロスネットワークの重複除去を行います。そのため、この API を使用すると、複数の広告テクノロジーが同じアトリビューション ソースまたはトリガーを登録できます。広告テクノロジーは、API からポストバックを受け取るために、アトリビューション ソースとトリガーの両方を登録する必要があり、アトリビューションは、広告テクノロジーが API に登録したアトリビューション ソースとトリガーの間で行われます。
サードパーティを使用してクロスネットワークの重複除去を行う広告主は、次のような手法で続行できます。
- レポートの登録と API から受信を行うための社内サーバーをセットアップする。
- 既存のモバイル測定パートナーを引き続き使用する。
アトリビューション ソース
アトリビューション ソースのリダイレクトは、registerSource()
メソッドでサポートされています。
registerSource()
メソッドを呼び出す広告テクノロジーは、パートナー広告テクノロジーのリダイレクト URL のセットを表すAttribution-Reporting-Redirect
フィールドをレスポンスに追加できます。- API がリダイレクト URL を呼び出し、パートナー広告テクノロジーでアトリビューション ソースを登録できるようにします。
Attribution-Reporting-Redirect
フィールドには、複数のパートナー広告テクノロジーの URL のリストを指定できます。パートナー広告テクノロジーが独自の Attribution-Reporting-Redirect
フィールドを指定することはできません。
この API では、registerSource()
の呼び出しごとに異なる広告テクノロジーを使用することもできます。
トリガー
トリガーの登録については、サードパーティも同様の方法でサポートされています。広告テクノロジーは、追加の Attribution-Reporting-Redirect
フィールドを使用するか、registerTrigger()
メソッドをそれぞれで呼び出すことができます。
広告主が複数の広告テクノロジーを使用して同じトリガー イベントを登録する場合は、重複除去キーを使用する必要があります。重複除去キーは、同じ広告テクノロジー プラットフォームで登録された同じイベントのレポートが繰り返される場合の曖昧さを取り除くために使用します。たとえば、広告テクノロジーが SDK から API を直接呼び出して、 トリガーを登録し、その URL を別の広告テクノロジーのリダイレクト フィールドに指定する あります。重複除去キーが指定されていない場合、重複するトリガーが報告される可能性があります 各広告テクノロジーに固有のものとして 返すことができます
重複するトリガーを処理する
広告テクノロジーは、同じトリガーを API に複数回登録できます。次のようなシナリオがあります。
- ユーザーが同じアクション(トリガー)を複数回行う。たとえば、ユーザーが同じレポート期間に同じ商品を繰り返し閲覧する場合です。
- 広告主のアプリがコンバージョンの測定に複数の SDK を使用しており、そのすべてが同じ広告テクノロジーにリダイレクトされる。たとえば、広告主のアプリが 2 つの測定パートナー(MMP #1 と MMP #2)を使用しています。両方の MMP が広告テクノロジー #3 にリダイレクトされます。トリガーが発生すると、両方の MMP がトリガーを Attribution Reporting API に登録します。広告テクノロジー #3 は、同じトリガーについて 2 つの別々のリダイレクト(一方は MMP #1 から、もう一方は MMP #2 から)を受け取ります。
このような場合、重複するトリガーのイベントレベル レポートを抑制し、イベントレベル レポートに適用されるレート制限を超えにくくする方法がいくつかあります。おすすめの方法は、重複除去キーを使用することです。
おすすめの方法: 重複除去キー
広告主のアプリで、コンバージョンの測定に使用している広告テクノロジーまたは SDK に一意の重複除去キーを渡す方法をおすすめします。コンバージョンが発生すると、アプリは広告テクノロジーまたは SDK に重複除去キーを渡します。その後、これらの広告テクノロジーまたは SDK は引き続き、Attribution-Reporting-Redirect
で指定された URL のパラメータを使用して重複除去キーをリダイレクトに渡します。
広告テクノロジーは、最初のトリガーのみを特定の
重複除去キーを指定するか、複数のトリガーまたはすべてのトリガーを登録できます。
広告テクノロジーは重複を登録する際に deduplication_key
を指定できます
使用できます。
広告テクノロジーが、同じ重複除去キーと、関連付けられたソースで複数のトリガーを登録した場合、最初に登録されたトリガーのみがイベントレベル レポートで送信されます。重複するトリガーは、暗号化された集計可能レポートで引き続き送信されます。
別の方法: 広告テクノロジーが広告主ごとのトリガータイプに同意する
広告テクノロジーが重複除去キーを使用しない場合や、広告主のアプリが重複除去キーを渡せない場合、別の方法があります。特定の広告主のコンバージョンを測定しているすべての広告テクノロジーが連携して、広告主ごとに異なるトリガータイプを定義する必要があります。
トリガー登録呼び出しを開始する広告テクノロジー(SDK など)が、Attribution-Reporting-Redirect
で指定された URL にパラメータ(duplicate_trigger_id
など)を含めます。この duplicate_trigger_id
パラメータには、その広告主の SDK 名やトリガータイプなどの情報を含めることができます。広告テクノロジーは、これらの重複するトリガーのサブセットをイベントレベルのレポートに送信できます。広告テクノロジーはこの duplicate_trigger_id
を集計キーに含めることもできます。
クロスネットワーク アトリビューションの例
このセクションの例では、広告主は 2 つの配信広告テクノロジー プラットフォーム(広告テクノロジー A と広告テクノロジー B)と、1 つの測定パートナー(MMP)を使用しています。
まず、広告テクノロジー A、広告テクノロジー B、MMP のそれぞれが、Attribution Reporting API を使用するための登録を完了する必要があります。詳しくは、プライバシー サンドボックス アカウントの登録をご覧ください。 ご確認ください。
次のリストは、それぞれ 1 日おきに発生する一連のユーザー アクションを仮定し、広告テクノロジー A、広告テクノロジー B、MMP に関して、Attribution Reporting API がそうしたアクションをどのように処理するかを示しています。
- 1 日目: 広告テクノロジー A によって配信された広告をユーザーがクリックする
広告テクノロジー A が、URI を指定して
registerSource()
を呼び出します。API が URI にリクエストを行い、広告テクノロジー A のサーバー レスポンスのメタデータにクリックが登録されます。また、広告テクノロジー A の
Attribution-Reporting-Redirect
ヘッダーに MMP の URI が記載されます。API が MMP の URI にリクエストを行い、MMP のサーバー レスポンスのメタデータにクリックが登録されます。- 2 日目: 広告テクノロジー B によって配信された広告をユーザーがクリックする
広告テクノロジー B が、URI を指定して
registerSource()
を呼び出します。API が URI にリクエストを行い、広告テクノロジー B のサーバー レスポンスのメタデータにクリックが登録されます。広告テクノロジー A と同様に、広告テクノロジー B の
Attribution-Reporting-Redirect
ヘッダーに MMP の URI が記載されます。API が MMP の URI にリクエストを行い、MMP のサーバー レスポンスのメタデータにクリックが登録されます。- 3 日目: 広告テクノロジー A によって配信された広告をユーザーが表示する
API は 1 日目と同様に応答します。ただし今回は、広告テクノロジー A と MMP にビューが登録されます。
- 4 日目: コンバージョンの測定に MMP を使用するアプリをユーザーがインストールする
MMP が、URI を指定して
registerTrigger()
を呼び出します。API が URL にリクエストを行い、MMP のサーバー レスポンスのメタデータにコンバージョンが登録されます。また、MMP の
Attribution-Reporting-Redirect
ヘッダーに広告テクノロジー A と広告テクノロジー B の URI が記載されます。API が広告テクノロジー A と広告テクノロジー B のサーバーにリクエストを行い、それに応じてサーバー レスポンスのメタデータにコンバージョンが登録されます。
次の図は、上記のリストで説明したプロセスを示しています。
<ph type="x-smartling-placeholder">アトリビューションは次のように機能します。
- 広告テクノロジー A は、クリックの優先度をビューより高く設定しているため、インストールを 1 日目のクリックに関連付けます。
- 広告テクノロジー B は、インストールを 2 日目に関連付けます。
- MMP は、クリックの優先度をビューより高く設定しているため、インストールを 2 日目のクリックに関連付けます。2 日目のクリックは、優先度が最も高い最新の広告イベントです。
リダイレクトなしのクロスネットワーク アトリビューション
リダイレクトを使用して、複数の広告テクノロジーでアトリビューション ソースとトリガーを登録できるようにすることをおすすめしていますが、リダイレクトの使用が適さない場合もあります。このセクションでは、リダイレクトなしのクロスネットワーク アトリビューションをサポートする方法について説明します。
大まかな流れ
- ソース登録時に、配信広告テクノロジー ネットワークがソース集計キーを共有します。
- トリガー登録時に、広告主または測定パートナーが、使用するソース側キーピースを選択してアトリビューション構成を指定します。
- アトリビューションは、アトリビューション構成、共有キーや、広告主または測定パートナーが実際に登録したソース(リダイレクトを有効にしている別の配信広告テクノロジー ネットワークなど)に基づきます。
- トリガーがリダイレクトなしの配信広告テクノロジーのソースに関連付けられている場合、広告主または測定パートナーは、ステップ 2 で定義したソースとトリガーのキーピースを組み合わせた集計可能レポートを受け取ることができます。
ソースの登録
ソース登録時に、配信広告テクノロジー ネットワークは、リダイレクトではなくソース集計キーまたはソース集計キーのサブセットを共有することもできます。配信広告テクノロジーは、これらのソースキーを独自の集計可能レポートで実際に使用する必要はありません。広告主または測定パートナーに代わって必要な場合にのみ宣言できます。
共有した集計キーは、同じ広告主のトリガーを登録するどの広告テクノロジーでも使用できます。ただし、必要な集計キーの種類、名前や、読み取り可能なディメンションにキーをデコードする方法については、配信広告テクノロジーとトリガー測定広告テクノロジーが協力する必要があります。
トリガーの登録
トリガー登録時に、測定広告テクノロジーは、配信広告テクノロジーが共有するものを含め、各トリガーのキーピースに適用するソース側キーピースを選択します。
また、測定広告テクノロジーはウォーターフォールも指定する必要があります 新しいアトリビューション設定 API 呼び出しを使用するようになりました。この構成では 広告テクノロジーは、ソースの優先度、有効期限、ソースのフィルタを指定できます。 (たとえば、リダイレクトを使用しないソースなど)。
帰属
Attribution Reporting API はソース優先のラストタッチを実行 アトリビューション構成に基づいて、測定広告テクノロジーのアトリビューションを そのユーザーが登録したソースを確認できます。例:
- ユーザーが、広告テクノロジー A、B、C、D が配信した広告をクリックし、測定広告テクノロジー パートナー(MMP)を使用する広告主のアプリをインストールした。
- 広告テクノロジー A はソースを MMP にリダイレクトする。
- 広告テクノロジー B と C はリダイレクトしないが集計キーを共有する。
- 広告テクノロジー D はリダイレクトも集計キーの共有もしない。
MMP が広告テクノロジー A からのソースを登録し、アトリビューション構成を定義する 広告技術 B と広告技術 D が含まれます
MMP のアトリビューションに以下が含まれるようになりました。
- 広告テクノロジー A(MMP が広告テクノロジーのリダイレクトのソースを登録したため)。
- 広告テクノロジー B(広告テクノロジー B がキーを共有し、それを MMP がアトリビューション構成に含めたため)。
MMP のアトリビューションに以下は含まれません。
- 広告テクノロジー C(MMP がアトリビューション構成に含めなかったため)。
- 広告テクノロジー D(リダイレクトも集計キーの共有もしなかったため)。
デバッグ
リダイレクトなしのクロスネットワーク アトリビューションのデバッグをサポートするには、次の操作を行います。
広告テクノロジーが設定できる追加のフィールド shared_debug_key
があります。
ソースの登録。元のソース登録で設定されていた場合は、これも
トリガーの登録時に対応する派生ソースで debug_key
として設定される
リダイレクトなしのクロスネットワークアトリビューションに
対応していますこのデバッグキーは
イベント レポートと集計レポートの source_debug_key
。
このデバッグ機能はクロスネットワーク アトリビューションでのみサポートされ、 次のような状況でリダイレクトされます。
- AdId が有効なアプリ間の測定 許可
- 広告 ID が許可されて照合される、アプリからウェブへの測定 アプリソースとウェブトリガーの両方
- ウェブからウェブへの測定(同じ
ブラウザアプリ)に
ar_debug
が存在する場合
リダイレクトなしのクロスネットワーク アトリビューションでの主な発見
主な発見は、広告テクノロジー(通常は MMP)の実装方法を合理化するためのものです。 クロスネットワーク アトリビューションが目的の場合、 または複数の配信広告テクノロジーが共有集計キーを使用している場合(詳しくは リダイレクトなしのクロスネットワーク アトリビューションを参照)。
MMP が集計サービスに対してクエリを実行し、概要レポートを生成すると、 キャンペーンに派生ソースが含まれる場合、集計サービスでは MMP が 有効なキーのリストを集計ジョブの入力として指定します。一部の ソース集計キーのリストが非常に大きい場合や、 不明。キー候補の大規模なリストは追跡が困難であり、 非常に複雑で 処理に費用がかかります次の点を考慮してください。 例:
- 可能性のあるすべてのキーのリストが大きい:
<ph type="x-smartling-placeholder">
- </ph>
- 広告配信中の広告ネットワークで複雑なユーザー獲得イニシアチブが実施されている 20 個のキャンペーン(それぞれに 10 個の広告グループを含む)と各広告グループを含む パフォーマンスに応じて毎週更新される 5 つのクリエイティブを割り当てる。
- 使用可能なすべての鍵のリストが不明です:
<ph type="x-smartling-placeholder">
- </ph>
- 広告配信中の広告ネットワークでは、多くのモバイルアプリで広告が配信されています。 パブリッシャーのアプリ ID の全一覧は、キャンペーンの開始時点では不明です。
- 広告主が複数の広告ネットワークで広告を配信 ソース登録時に MMP にリダイレクトしない配信される各広告 鍵の構造と値が異なるため、 事前に MMP と共有します。
鍵検出の導入により:
- 集約サービスで、可能なイベントの完全な列挙が不要になりました。 使用できます。
- 使用可能なすべての鍵のリストを指定する代わりに、MMP で 空の(または部分的に空)のキーセットを作成し、しきい値を設定して、 しきい値を超える値を持つ(事前に宣言されていない)キーが あります。
- MMP は概要レポートを受け取ります。この概要レポートには、問題のあるキーのノイズの多い値が含まれています。 寄与する値が設定したしきい値を上回っているか 確認できますこのレポートには 実ユーザーのコントリビューションが関連付けられておらず、純粋にノイズが付けられたキーです。
- MMP は、トリガー登録で
x_network_bit_mapping
フィールドを使用して、 どの広告テクノロジーがどのキーに対応するかを判断します。 - MMP は適切な配信広告テクノロジーに連絡して値を把握できます。 あります。
まとめると、キー検出により、MMP は独自のキーなしで集計キーを取得できます。 事前に把握しておき、大量のソース鍵を処理せずに済みます。 代わりにノイズが追加されます
アトリビューション レポートで測定データを表示する
Attribution Reporting API では、次の種類のレポートが可能です。詳細についてはこのページ内で別途説明します。
- イベントレベル レポートは、特定のアトリビューション ソース(クリックまたはビュー)を、限られたビットの忠実度の高いトリガーデータに関連付けます。
- 集計可能レポートは、必ずしも特定のアトリビューション ソースに関連付けられるわけではありません。イベントレベル レポートよりも豊富な、忠実度の高いトリガーデータが提供されますが、このデータは集計形式でしか利用できません。
これら 2 種類のレポートは相互に補完し合うものであり、同時に使用できます。
イベントレベル レポート
トリガーがアトリビューション ソースに帰属するとイベントレベル レポートが生成され、いずれかのレポート送信期間の間に各広告テクノロジーのポストバック URL に送信できるようになるまで、デバイスに保存されます。詳細についてはこのページ内で別途説明します。
イベントレベル レポートは、トリガーについて情報がほとんど必要ない場合に便利です。イベントレベルのトリガーデータは、クリックについては 3 ビットに制限され(つまり、トリガーが 8 つのカテゴリのいずれかに割り当てられます)、ビューについては 1 ビットに制限されます。また、イベントレベル レポートでは、特定の価格やトリガー時間など、忠実度の高いトリガー側データのエンコードはサポートされていません。アトリビューションはデバイスで行われるため、イベントレベルのレポートではクロスデバイス分析がサポートされません。
イベントレベル レポートには次のようなデータが含まれます。
- デスティネーション: トリガーが発生する広告主アプリのパッケージ名または eTLD+1
- アトリビューション ソース ID: アトリビューション ソースの登録に使用したものと同じアトリビューション ソース ID
- トリガータイプ: アトリビューション ソースのタイプに応じた、1 ビットまたは 3 ビットの低忠実度トリガーデータ
すべてのレポートに適用されるプライバシー保護メカニズム
以下の制限は、アトリビューション ソースに関する優先度の後に適用されます。 トリガーが考慮されます
広告テクノロジーの数の制限
API のレポートを登録または受信できる広告テクノロジーの数には制限があり、現在の提案では次のようになっています。
- {ソースアプリ、デスティネーション アプリ、30 日、デバイス} ごとに、アトリビューション ソースがある広告テクノロジーが 100 個。
- {ソースアプリ、デスティネーション アプリ、30 日、デバイス} ごとに、関連付けられたトリガーがある広告テクノロジーが 10 個。
- 20 個の広告テクノロジーが 1 つのアトリビューション ソースまたはトリガーを登録できる(
Attribution-Reporting-Redirect
)
固有の宛先数の上限
この制限により、一連の広告テクノロジーが 多数のアプリを分析し、特定のユーザーのアプリ使用行動を把握します。
- 登録されているすべてのソース、すべての広告テクノロジーにおいて、 ソースアプリごとに 1 分あたり 200 件を超える一意の宛先。
- 全登録済み 1 つの広告テクノロジーについて、API でサポートされる一意のソースは ソースアプリごとの 1 分あたりの宛先の数。この制限により 1 つの広告テクノロジーが 前述のレート制限の予算を使い切ること。
期限切れのソースはレート制限にカウントされません。
1 日にソースアプリごとに 1 つのレポート生成元
1 つの広告テクノロジー プラットフォームがソースを登録する際に使用できるレポートオリジンは 1 つのみです パブリッシャーのアプリで 同じ日に行われた場合このレート制限 広告テクノロジーが複数のレポート生成元を使用して追加の プライバシー バジェット
次のシナリオを考えてみましょう。1 人の広告テクノロジーが複数の 1 台のデバイスについて、パブリッシャー アプリのソースを登録するためのレポート生成ツール。
- 広告テクノロジー A のレポートオリジン 1 がアプリ B にソースを登録する
- 12 時間後、広告テクノロジー A のレポートオリジン 2 がソースの登録を試みる アプリ B
2 番目のソース(広告テクノロジー A のレポートオリジン 2 の場合)は、 API広告テクノロジー A のレポート元 2 は、 アプリ B の同じデバイスで翌日まで利用可能です。
クールダウンとレート制限
{source, destination} 間のユーザー ID の漏洩の量を制限するため API は、一定の時間内に送信される情報の合計量をスロットリングします。 予測します
現在の提案では、各広告テクノロジーが関連付けるトリガーが {ソースアプリ、デスティネーション アプリ、30 日、デバイス} あたり 100 個に制限されています。
一意のデスティネーションの数
この API は、広告テクノロジーが測定できるデスティネーションの数を制限します。 上限を低く設定すると、広告テクノロジーが API を使用して試行するのが難しくなる 表示される広告に関連付けられていないユーザーの閲覧アクティビティを測定する場合。
現在の提案では、各広告テクノロジーで、ソースアプリごとに 100 個の別々のデスティネーション(ソースは期限内)に制限されています。
イベントレベル レポートに適用されるプライバシー保護メカニズム
トリガーデータの忠実度の制限
API は、ビュースルー トリガーに 1 ビット、クリックスルー トリガーに 3 ビットを提供します。アトリビューション ソースは、引き続き 64 ビットのメタデータを完全にサポートします。
イベントレベル レポートで利用可能な限られたビット数で機能するように、トリガーで表現される情報を減らすかどうかを検討する必要があります。減らす場合の方法についても評価する必要があります。
差分プライバシー ノイズのフレームワーク
この API の目標は、k ランダム化レスポンスを使用して各ソースイベントに対しノイズのある出力を生成することで、イベントレベルの測定がローカルの差分プライバシー要件を満たすようにすることです。
ノイズの適用は、アトリビューション ソース イベントが正しくレポートされるかどうかに応じて行われます。アトリビューション ソースがデバイスに登録される際、アトリビューション ソースが通常どおりに登録される確率は $ 1-p $ であり、可能性のあるすべての API 出力状態(一切レポートが行われない場合や、複数の偽のレポートが行われる場合を含む)の中からデバイスがランダムに選択する確率は $ p $ です。
k ランダム化レスポンスは、次の式が成立する場合に、イプシロン差分プライバシーを満たすアルゴリズムです。
ε の値が低い場合、真の出力は k ランダム化レスポンス メカニズムによって保護されます。正確なノイズ パラメータは現在開発中であり、フィードバックに基づいて変更される可能性があります。現在の提案では次のようになっています。
- ナビゲーション ソース: p=0.24%
- イベントソース: p=0.00025%
利用可能なトリガー(コンバージョン)の制限
アトリビューション ソースごとのトリガーの数には制限があり、現在の提案では次のようになっています。
- 広告ビューのアトリビューション ソース用に 1 ~ 2 個のトリガー(2 つのトリガーは (インストール後のアトリビューションの場合)
- 広告クリックのアトリビューション ソース: トリガー 3 個
レポートを送信する特定の期間(デフォルトの動作)
広告ビュー アトリビューション ソースのイベントレベル レポートは、 ソースが期限切れになります。有効期限は 1 日以上に設定できますが、 30 日超えています1 つの広告ビューに 2 つのトリガーが関連付けられている場合 アトリビューション ソース(インストール後のアトリビューションを使用)、イベントレベル レポートでは 次のレポート期間間隔で送信されます。
広告クリックのアトリビューション ソースのイベントレベル レポートは設定できず、 ソースが期限切れになる前または期限が切れたときに、 ソースの登録日時を指定します。アトリビューション ソースと 複数のレポート期間に分割されます。各レポート期間には 期限(アトリビューション ソースの時間から)です。各レポートの最後に それ以降に発生したすべてのトリガーを スケジュール設定されたレポートが送信されます。API は 次のレポート期間:
- 2 日間: デバイスは、アトリビューション ソースの登録から 2 日後までに発生したトリガーをすべて収集します。レポートは、アトリビューション ソースの登録から 2 日と 1 時間後に送信されます。
- 7 日間: デバイスは、アトリビューション ソースの登録から 2 日を超え、かつ 7 日以内に発生したトリガーをすべて収集します。レポートは、アトリビューション ソースの登録から 7 日と 1 時間後に送信されます。
- カスタム期間: アトリビューション ソースの「expiry」属性で定義します。レポートは、指定した期限の 1 時間後に送信されます。この値を 1 日未満または 30 日を超える長さにすることはできません。
柔軟なイベントレベルの設定
広告テクノロジーに推奨されるイベントレベル レポートのデフォルト設定 使用を開始できますが、すべてのユースケースに最適であるとは限らない 対応できますAttribution Reporting API では、より柔軟なオプション対応の 広告テクノロジーが広告の構成をより細かく制御できるように データの有用性を最大化できます
柔軟性の向上が Attribution Reporting に導入される予定 2 つのフェーズ:
- フェーズ 1: 柔軟なイベントレベルのライト構成
<ph type="x-smartling-placeholder">
- </ph>
- このバージョンでは、完全な機能のサブセットが提供されます。 使用されます。
- フェーズ 2: 柔軟なイベントレベル設定の完全版
フェーズ 1(Lite の柔軟なイベントレベル)は、次の目的で使用できます。
- レポート期間の数を指定してレポートの頻度を変える
- ソース登録ごとにアトリビューションの数を変える
- 上記のパラメータを減らすことで、全体的なノイズの量を減らす
- デフォルトではなくレポート期間を設定する
フェーズ 2(完全な柔軟なイベントレベル)では、 次の点に着目します。
- レポートでトリガーデータのカーディナリティを変化させる
- トリガーデータのカーディナリティを下げてノイズの総数を削減する
デフォルト構成のディメンションを 1 つ減らすと、広告テクノロジーで次のことが可能になります。 別の次元を増やすこともできますまたは、イベントに含まれるノイズの 上記のパラメータを減少させると、レポートレベルのレポートが減少する場合があります。
選択された広告テクノロジーに基づいてノイズレベルが動的に設定されるほか、 コンピューティング量が膨大になるのを避けるために、パラメータに制限があります。 出力状態が多すぎると(ノイズが増えてしまい、コストがかさむことが あります)。制限の例を以下に示します。フィードバックをお寄せください。 [設計案][50]:
- グローバルに、trigger_data ごとに合計 20 件のレポート
- trigger_data ごとに最大 5 つのレポート期間
- 最大 32 のトリガーデータ カーディナリティ(フェーズ 1: Lite には適用されません) 柔軟なイベント単位)
広告テクノロジーがこの機能の使用を開始するにあたり、極端な値を使用すると ノイズが多くなったり、プライバシー レベルが適切で 満たされません。
集計可能レポート
集計可能レポートを使用する前に、クラウド アカウントをセットアップし、集計可能レポートの受信を開始する必要があります。
集計可能レポートは、イベントレベル レポートより忠実度の高いトリガーデータを、より迅速にデバイスから提供します。忠実度の高いデータは集計でしか学習できず、特定のトリガーまたはユーザーと関連付けられることはありません。集計キーは最大 128 ビットであり、集計可能レポートは次のようなレポートのユースケースをサポートできます。
- 収益などのトリガー値のレポート
- より多くのトリガータイプの処理
また、集計可能レポートはイベントレベル レポートと同じソース優先アトリビューション ロジックを使用しますが、クリックまたはビューに帰属する、より多くのコンバージョンをサポートします。
Attribution Reporting API がどのように準備および送信するかの全体的な設計 図に示す集計可能レポートは、次のとおりです。
- デバイスが、暗号化された集計可能レポートを広告テクノロジーに送信します。本番環境では、広告テクノロジーがこれらのレポートを直接使用することはできません。
- 広告テクノロジーが、集計可能レポートのバッチを集計サービスに送信します。
- 集計サービスが、集計可能レポートのバッチを読み取り、復号して集計します。
- 最終的な集計は、 概要レポート。
集計可能レポートには、アトリビューション ソースに関連する次のデータが含まれます。
- デスティネーション: トリガーが発生したアプリのパッケージ名または eTLD+1 ウェブ URL。
- 日付: アトリビューション ソースで表されるイベントが発生した日付。
- ペイロード: 暗号化された Key-Value ペアとして収集されるトリガー値。信頼できる集計サービスで集計の計算に使用されます。
集計サービス
次のサービスは集計機能を提供し、集計データに対する不適切なアクセスから保護します。
これらのサービスは異なる当事者によって管理されています。詳細についてはこのページ内で別途説明します。
- 集計サービスは、広告テクノロジーが想定している唯一のサービス デプロイできます。
- 鍵管理サービスと集計可能レポートのアカウンティング サービスは、コーディネーターという信頼できる当事者によって実行されます。コーディネーターは、集計サービスを実行するコードが Google によって提供された一般公開のコードであることと、すべての集計サービス ユーザーに同じ鍵と集計可能レポートのアカウンティング サービスが適用されていることを証明します。
集計サービス
広告テクノロジー プラットフォームでは、Google によって提供されたバイナリに基づく集計サービスを事前にデプロイしておく必要があります。
この集計サービスは、クラウドでホストされた高信頼実行環境(TEE)で動作します。TEE には、次のようなセキュリティ上のメリットがあります。
- TEE で動作するコードが、Google によって提供された特定のバイナリであることが保証されます。この条件が満たされない限り、集計サービスはオペレーションに必要な復号鍵にアクセスできません。
- 実行中のプロセスにセキュリティを提供し、外部の監視や改ざんから隔離します。
こうしたセキュリティ上のメリットにより、集計サービスは、暗号化されたデータへのアクセスなどの機密性の高いオペレーションを安全に実施できるようになります。
インフラストラクチャの設計、ワークフロー、セキュリティの考慮事項について 詳細については、このモジュールの 集計サービス ドキュメント ご覧ください。
鍵管理サービス
このサービスは、集計サービスが承認済みのバージョンのバイナリを実行していることを確認してから、広告テクノロジーの集計サービスとトリガーデータの正しい復号鍵を提供します。
集計可能レポートのアカウンティング
このサービスは、広告テクノロジーの集計サービスが特定のトリガー(複数の集計キーを含む場合があります)にアクセスする頻度を追跡し、アクセス時の復号回数を適切な範囲に制限します。詳細については、Attribution Reporting API の集計サービスの設計案をご覧ください。
Aggregatable Reports API
集計可能レポートへの投稿を用意するための API は、イベントレベル レポートにアトリビューション ソースを登録するときと同じベース API を使用します。以降のセクションでは、API の拡張機能について説明します。
集計可能ソースデータを登録する
API がアトリビューション ソース URI にリクエストを行うと、広告テクノロジーは、HTTP ヘッダー Attribution-Reporting-Register-Source
の aggregation_keys
という新しいフィールド(キーは key_name
、値は key_piece
)で応答することにより、histogram_contributions
という集計キーのリストを登録できます。
- (キー)キー名: キーの名前の文字列。結合キーとして使用され、トリガー側のキーと組み合わせて最終的なキーを形成します。
- (値)キーピース: キーのビット文字列値。
最終的なヒストグラム バケット キーは、これらのピースとトリガー側ピースにバイナリ OR 演算を行うことで、トリガー時に完全に定義されます。
最終的なキーは最大 128 ビットに制限されます。それより長いキーは切り捨てられます。つまり、JSON 内の 16 進文字列は、32 桁以下に制限されます。
集計キーの構造とその方法について詳しくは、こちらをご覧ください。 集計キーを構成できます
次の例では、広告テクノロジーが API を使用して以下を収集しています。
- キャンペーン レベルでのコンバージョン数の集計
- 地域レベルでの購入額の集計
// This is where the Attribution-Reporting-Register-Source object appears when // an ad tech registers an attribution source. // Attribution source metadata specifying histogram contributions in aggregate report. Attribution-Reporting-Register-Source: … aggregation_keys: { // Generates a "0x159" key piece named (low order bits of the key) for the key // named "campaignCounts". // User saw an ad from campaign 345 (out of 511). "campaignCounts": "0x159", // Generates a "0x5" key piece (low order bits of the key) for the key name "geoValue" // Source-side geo region = 5 (US), out of a possible ~100 regions. "geoValue": "0x5" }
集計可能トリガーを登録する
トリガーの登録では、フィールドがさらに 2 つ追加されます。
1 つ目のフィールドは、トリガー側の集計キーのリストを登録するために使用されます。広告テクノロジーは、リスト内の各集計キーについて次のフィールドを持つ HTTP ヘッダー Attribution-Reporting-Register-Trigger
の aggregatable_trigger_data
フィールドで応答する必要があります。
- キーピース: キーのビット文字列値。
- ソースキー: 最終的なキーを形成するために、トリガーキーを組み合わせる必要があるアトリビューション ソース側のキーの名前を含んだ文字列のリスト。
2 つ目のフィールドは、各キーに寄与する値のリストを登録するために使用されます。広告テクノロジーは HTTP ヘッダー Attribution-Reporting-Register-Trigger
の aggregatable_values
フィールドで応答する必要があります。2 つ目のフィールドは、各キーに寄与する値のリストを登録するために使用されます。これは $ [1, 2^{16}] $ の範囲の整数です。
各トリガーは、集計可能レポートに複数のコントリビューションを設定できます。任意のソースイベントへのコントリビューションの総量は、$ L1 $ パラメータによって制約されます。これは、任意のソースのすべての集計キーにわたるコントリビューション(値)を合計したものの最大値です。$ L1 $ は、L1 感度、すなわちソースイベントあたりのヒストグラム コントリビューションのノルムを表します。この制限を超えると、以降のコントリビューションは通知なしに破棄されます。最初の提案では、$ L1 $ が $ 2^{16} $ (65536) に設定されます。
集計サービスのノイズは、このパラメータに比例して調整されます。そのため、特定の集計キーについてレポートされる値は、割り当てられた $ L1 $ のバジェット部分に基づいて適切に調整することをおすすめします。このアプローチでは、ノイズが適用されたときに、集計レポートの忠実度を最も高く保てます。このメカニズムは柔軟性が高く、多くの集計戦略をサポートできます。
次の例では、$ L1 $ の寄与分をそれぞれに分割することで、プライバシー バジェットが campaignCounts
と geoValue
の間で均等に分割されます。
// This is where the Attribution-Reporting-Register-Trigger object appears // when an ad tech registers a conversion trigger. // Specify a list of dictionaries that generates aggregation keys. Attribution-Reporting-Register-Trigger:{ … "aggregatable_trigger_data": [ // Each dictionary independently adds pieces to multiple source keys. { // Conversion type purchase = 2 at a 9-bit offset, i.e. 2 << 9. // A 9-bit offset is needed because there are 511 possible campaigns, which // will take up 9 bits in the resulting key. "key_piece": "0x400",// Conversion type purchase = 2 // Apply this key piece to: "source_keys": ["campaignCounts"] }, { // Purchase category shirts = 21 at a 7-bit offset, i.e. 21 << 7. // A 7-bit offset is needed because there are ~100 regions for the geo key, // which will take up 7 bits of space in the resulting key. "key_piece": "0xA80", // Apply this key piece to: "source_keys": ["geoValue", "nonMatchingIdsListedHereAreIgnored"] } ] // Specify an amount of an abstract value which can be integers in [1, 2^16] to // contribute to each key that is attached to aggregation keys in the order that // they're generated. aggregatable_values: { // Privacy budget for each key is L1 / 2 = 2^15 (32768). // Conversion count was 1. // Scale the count to use the full budget allocated: 1 * 32768 = 32768. "campaignCounts": 32768, // Purchase price was $52. // Purchase values for the app range from $1 to $1,024 (integers only). // Scaling factor applied is 32768 / 1024 = 32. // For $52 purchase, scale the value by 32 ($52 * 32 = $1,664). "geoValue": 1664 } }
上記の例では、次のヒストグラム コントリビューションが生成されます。
[
// campaignCounts:
{
"key": "0x559", // = 0x159 | 0x400
"value": 32768
},
// geoValue:
{
"key": "0xA85", // = 0x5 | 0xA80
"value": 1664
}
]
正しい値(適用されるモジュロノイズ)が得られるように、スケーリング ファクタを反転できます。
L1 = 65536
trueCampaignCounts = campaignCounts / (L1 / 2)
trueGeoValue = geoValue / (L1 / 2) * 1024
差分プライバシー
この API の目標は、差分プライバシーを満たす集計結果の測定をサポートできるフレームワークを用意することです。これは、次のような分布のノイズを選ぶなどして、$ L1 $ のバジェットに比例するノイズを追加することで実現できます。
Protected Audience API と Attribution Reporting API の統合
Protected Audience と Attribution Reporting の API をまたいだ統合 アドテックは API を使用して、さまざまな側面にわたってアトリビューションのパフォーマンスを評価できます。 どのタイプのオーディエンスで成果が高いかを把握したり 費用対効果を最大化できます
この API 間の統合により、アドテックは次のことが可能になります。
- 両方に使用する URI の Key-Value マップを作成する (1)インタラクション レポート、2)ソース登録の 2 つがあります。
- 集計用のソース側のキーマッピングに
CustomAudience
を含める サマリー レポート(Attribution Reporting API を使用)。
ユーザーが広告を表示またはクリックすると、次のようになります。
- Protected Audience を使用してそうした操作を報告するために使用される URL も、 を使って、ビューまたはクリックを対象ソースとして Attribution Reporting API
- 広告テクノロジーは、CustomAudience(またはその他の関連するコンテキスト 広告の配置や視聴時間など、広告に関する情報) このメタデータが概要レポートに反映されるように、広告テクノロジーが キャンペーンのパフォーマンスの集計を審査しています
Protected Audience 内でこれを有効にする方法について詳しくは、 Protected Audience API 説明の該当セクション
登録優先度、アトリビューション、レポートの例
この例では、一連のユーザー インタラクションのほか、広告テクノロジーでアトリビューション ソースとトリガーの優先度がアトリビューション レポートにどのように影響するかを説明します。この例では、次のように仮定します。
- アトリビューション ソースとトリガーはすべて、同じ広告主の同じ広告テクノロジーによって登録されます。
- アトリビューション ソースとトリガーはすべて、最初のイベント レポート期間(広告がパブリッシャー アプリに最初に表示されてから 2 日以内)に発生します。
ユーザーが次を行う場合を考えます。
- ユーザーに広告が表示されます。広告テクノロジーが優先度
0
のアトリビューション ソースを API で登録します(ビュー #1)。 - 優先度
0
で登録された広告がユーザーに表示されます(ビュー #2)。 - ユーザーが優先度
1
で登録された広告をクリックします(クリック #1)。 - 広告主のアプリでユーザーによるコンバージョン(ランディング ページへのアクセス)が発生します。広告テクノロジーが優先度
0
のトリガーを API で登録します(コンバージョン #1)。- トリガーが登録されるため、レポートを生成する前に、まず API でアトリビューションが行われます。
- 使用可能なアトリビューション ソースは、ビュー #1、ビュー #2、クリック #1 の 3 つです。このトリガーは、優先度が最も高く、最新のものであるため、API がクリック #1 に関連付けます。
- ビュー #1 とビュー #2 は破棄され、今後のアトリビューションの対象ではなくなります。
- ユーザーが広告主のアプリで商品をカートに追加し、優先度
1
で登録されます(コンバージョン #2)。- 対象となるアトリビューション ソースは、クリック #1 のみです。API は、このトリガーをクリック #1 に関連付けます。
- ユーザーが広告主のアプリで商品をカートに追加し、優先度
1
で登録されます(コンバージョン #3)。- 対象となるアトリビューション ソースは、クリック #1 のみです。API は、このトリガーをクリック #1 に関連付けます。
- ユーザーが広告主のアプリで商品をカートに追加し、優先度
1
で登録されます(コンバージョン #4)。- 対象となるアトリビューション ソースは、クリック #1 のみです。API は、このトリガーをクリック #1 に関連付けます。
- ユーザーが広告主のアプリで購入を行い、優先度
2
で登録されます(コンバージョン #5)。- 対象となるアトリビューション ソースは、クリック #1 のみです。API は、このトリガーをクリック #1 に関連付けます。
イベントレベル レポートには次のような特性があります。
- デフォルトで、クリックに関連付けられた最初の 3 つのトリガーと、ビューに関連付けられた最初のトリガーが、該当するレポート期間の後で送信されます。
- レポート期間により高い優先度で登録されたトリガーがある場合は、それらが優先され、最新のトリガーを置き換えます。
- 上記の例では、広告テクノロジーは 2 日間のレポート期間の後で、コンバージョン #2、コンバージョン #3、コンバージョン #5 に関する 3 つのイベント レポートを受け取ります。
- これら 5 つのトリガーはすべて、クリック #1 に関連付けられます。API はデフォルトで、最初の 3 つのトリガー(コンバージョン #1、コンバージョン #2、コンバージョン #3)に関するレポートを送信します。
- ただし、コンバージョン #4 の優先度(
1
)はコンバージョン #1 の優先度(0
)より高くなっています。コンバージョン #4 のイベント レポートは、コンバージョン #1 のイベント レポートを置き換え、送信候補となります。 - また、コンバージョン #5 の優先度(
2
)は他のトリガーよりも高くなっています。コンバージョン #5 のイベント レポートがコンバージョン #4 のレポートを置き換え、送信候補となります。
集計可能レポートには次のような特性があります。
暗号化された集計可能レポートは、処理後すぐ(トリガーの登録から数時間後)に広告テクノロジーに送信されます。
広告テクノロジーである場合は、集計可能レポートに暗号化されない状態で届く情報に基づいてバッチを作成します。この情報は、集計可能レポートの
shared_info
フィールドに含まれ、タイムスタンプとレポート送信元を含んでいます。集計 Key-Value ペアの中の暗号化された情報に基づいてバッチ処理することはできません。簡単な戦略としては、レポートを毎日または毎週バッチ処理する方法があります。理想的には、バッチには少なくとも 100 レポートを含める必要があります。集計可能レポートをバッチ処理して集計サービスに送信するタイミングと方法は、広告テクノロジーで判断します。
イベントレベル レポートと比較すると、暗号化された集計可能レポートでは、より多くのトリガーをソースに関連付けることができます。
上記の例では、登録されたトリガーごとに 1 つずつ、合計 5 つのレポートが送信されます。
移行デバッグ レポート
Attribution Reporting API は、クロスアプリ ID なしでアトリビューション測定を行うための、かなり複雑な新しい方法です。そのため、 アトリビューション レポートの詳細を確認できる移行メカニズム 広告 ID を利用できる(ユーザーがパーソナライズを無効にしていない) 広告 ID を使用し、パブリッシャーまたは広告主のアプリで AdID を宣言している 権限など)。これにより、作成中に API を完全に理解し、 バグを明確化して、パフォーマンスを 広告 ID ベースの代替手段です。デバッグ レポートには次の 2 種類があります。 詳しく見てみましょう。
デバッグについて詳しくは、移行デバッグ レポートに関するガイドをご覧ください。 アプリからウェブとウェブからアプリへの測定を含むレポートを作成できます。
アトリビューション成功のデバッグ レポート
ソースとトリガーの登録の両方で新しい 64 ビットの debug_key
フィールドを受け入れる
(文字列形式)が広告テクノロジーによって入力されます。source_debug_key
、
trigger_debug_key
は、イベントレベルと集計の両方で、変更されることなく渡されます。
できます。
ソースとトリガーの両方のデバッグキーを使用してレポートを作成した場合、
デバッグ レポートがわずかな遅延で
.well-known/attribution-reporting/debug/report-event-attribution
エンドポイント。「
デバッグ レポートは、両方のデバッグキー フィールドを含め、通常のレポートと同じです。
これらのキーを両方に含めると、通常のレポートを個別のストリームに関連付けることができます。
デバッグ レポートを利用できます。
- イベントレベル レポート:
- 重複するデバッグ レポートがわずかな遅延で送信されるため、 使用可能なトリガーの制限によって抑制され、広告テクノロジーが許可されます。 これらの上限がイベントレベル レポートに与える影響を把握するには、
- 誤ったトリガー イベントに関連付けられているイベントレベル レポートに、
trigger_debug_key
はありません。これにより、広告テクノロジーは API でノイズがどのように適用されるかをより詳細に把握できます。
- 集計可能レポートの場合:
<ph type="x-smartling-placeholder">
- </ph>
source_debug_key
とtrigger_debug_key
の両方が設定されている場合にのみ、復号されたペイロードを含む新しいdebug_cleartext_payload
フィールドがサポートされます。
詳細なデバッグ レポート
詳細なデバッグ レポートを使用すると、開発者は特定のエラーを
アトリビューションソースやトリガーの登録に
使用しますこれらのデバッグ レポートは、
アトリビューション ソースまたはトリガー登録後の遅延は限られている
をタップします。well-known/attribution-reporting/debug/verbose
エンドポイント。
各詳細レポートには次のフィールドがあります。
- タイプ: レポートが生成された原因。詳しくは、
詳細レポートタイプ。
- 一般的に、ソース詳細レポートとトリガー詳細レポートがあります。
- ソース詳細レポートでは、ユーザーが広告 ID を使用できる必要があります。 詳細レポートをトリガーするには、広告 ID が一致していることが 広告主のアプリで利用できるようにします
- 詳細レポートをトリガーする(例外は
trigger-no-matching-source
)には、必要に応じてsource_debug_key
を含めることができます。 これは、広告 ID が 使用します。
- 本文: レポートの本文。タイプによって異なります。
広告テクノロジーは、新しい API
debug_reporting
ディクショナリ フィールド
Attribution-Reporting-Register_Source
と
Attribution-Reporting-Register-Trigger
ヘッダー。
- ソース詳細レポートでは、ソース登録ヘッダーでのみオプトインが必要です。
- トリガーのデバッグ レポートでは、トリガー登録ヘッダーでのみオプトインが必要です。
デバッグ レポートの使用方法
(既存の測定システムによる)コンバージョンが発生し、そのコンバージョンのデバッグ レポートを受信した場合、これはトリガーが正常に登録されたことを意味します。
デバッグ アトリビューション レポートごとに、2 つのデバッグキーに一致する通常のアトリビューション レポートを受信しているかどうかを確認します。
一致がない場合、いくつかの原因が考えられます。
意図したとおりの動作:
- プライバシー重視の API 動作:
- ユーザーがレポートのレート制限に達し、それ以降のレポートがすべて期限内に送信されなくなる。または、保留中のデスティネーション制限によりソースが削除される。
- イベントレベル レポート: レポートがランダム化レスポンス(ノイズ)の対象となり、抑制される。または、ランダム化レポートを受信することがある。
- イベントレベル レポート: レポートが 3 回(クリック数)または 1 回(ビュー数)の上限に達し、後続のレポートに明確な優先度が設定されていないか、既存のレポートよりも低い優先度が設定されている。
- 集計可能レポートの投稿制限を超えている。
- 広告テクノロジーで定義されたビジネス ロジック:
- トリガーがフィルタまたは優先度ルールによってフィルタされる。
- 時間遅延、またはネットワークの可用性との連携(ユーザーが長時間デバイスの電源をオフにした場合など)。
意図しない原因:
- 実装の問題:
- ソースヘッダーが正しく構成されていない。
- トリガー ヘッダーが正しく構成されていない。
- その他の構成の問題。
- デバイスまたはネットワークの問題:
- ネットワーク状態に起因する障害。
- ソースまたはトリガーの登録レスポンスがクライアントに届かない。
- API のバグ。
今後の検討事項と未解決の問題
Attribution Reporting API は現在開発中です。また、ラストクリック アトリビューション以外のモデルやクロスデバイス測定のユースケースなど、将来的な機能についても検討しています。
いくつかの問題点について、コミュニティからのフィードバックもお待ちしております。
- 検証済みインストールのレポートを API で送信するユースケースはあるでしょうか。そうしたレポートは、広告テクノロジー プラットフォームのレート制限にカウントされます。
- アプリから
InputEvent
を渡す際に何か問題が発生する可能性はありますか? ソース登録のために広告テクノロジーに送信しますか? - プリロードされたアプリまたは再インストールされたアプリに特別なアトリビューションのユースケースはありますか。