最近の更新
今後の変更と既知の問題のリストが更新されました
完全な柔軟なイベントレベルの設定への橋渡しとして、柔軟なイベントレベルの設定のライト版を導入しました
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 Cloud の集計サービスを使用して概要レポートを生成できるようになります。具体的なタイミングについては、こちらをご覧ください。Google Cloud で Aggregation Service を設定する方法については、デプロイガイドをご覧ください。
一意の宛先の数に対する新しいプライバシー保護レート制限。
ルックバック ウィンドウ トリガー フィルタの機能の更新は 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 またはアプリ パッケージ名のオリジン。
- 期限(省略可): デバイスからソースを削除する必要がある期限(秒単位)。デフォルトは 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 がバックグラウンド リクエストとして registerSource()
を直接呼び出すことで処理されます。この呼び出しにより、アトリビューション ソースは最上位のオリジンではなくアプリに関連付けられます。ブラウザ コンテキスト内の埋め込みウェブ コンテンツからソースを登録することもできます。この場合、API 呼び出し元とアプリの両方で設定を調整する必要があります。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
に一致するトリガー フィルタ キーがない場合、フィルタは無視されます。
広告テクノロジー プラットフォームがトリガーを個別にフィルタする必要があるもう 1 つのシナリオは、有効期限を短くすることです。広告テクノロジーは、トリガーの登録時に、コンバージョンが発生した時点からのルックバック ウィンドウを秒単位で指定できます。たとえば、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 つのアトリビューション ソースに帰属させることができるトリガーの数には制限があります。詳しくは、このページで後述するアトリビューション レポートで測定データを表示するをご覧ください。
この上限を超える複数のトリガーがある場合は、最も価値のあるトリガーを得るために、優先度設定ロジックを導入することをおすすめします。たとえば、広告テクノロジーのデベロッパーが、「カートに追加」トリガーよりも「購入」トリガーの方を優先させる場合などです。
このロジックをサポートするには、トリガーに個別の優先度フィールドを設定します。特定のレポート期間内で、制限が適用される前に最も優先度の高いトリガーが選択されます。
複数の広告テクノロジーがアトリビューション ソースまたはトリガーを登録できるようにする
複数の広告テクノロジーがアトリビューション レポートを受け取ることは一般的であり、通常はクロスネットワークの重複除去を行います。そのため、この 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 のサーバーにリクエストを行い、それに応じてサーバー レスポンスのメタデータにコンバージョンが登録されます。
上のリストで説明したプロセスを図 1 に示します。
アトリビューションは次のように機能します。
- 広告テクノロジー 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 が許可されているアプリ間の測定
- AdId が許可され、アプリソースとウェブトリガーの両方で一致するアプリからウェブへの測定
- ソースとトリガーの両方に
ar_debug
が存在する場合のウェブからウェブへの測定(同じブラウザアプリ上)
リダイレクトなしのクロスネットワーク アトリビューションのキー検出
キー検出は、1 つ以上の配信広告テクノロジーが共有集計キーを使用している場合(上記のリダイレクトを使用しないクロスネットワーク アトリビューションで説明されているように)、クロスネットワーク アトリビューションのために広告テクノロジー(通常は MMP)がアトリビューション構成を実装する方法を効率化することを目的としています。
MMP が集計サービスにクエリを実行して、派生ソースを含むキャンペーンの概要レポートを生成する場合、集計サービスでは、集計ジョブの入力として使用できるキーのリストを MMP に指定する必要があります。場合によっては、考えられるソース集計キーのリストが非常に大きいか、不明な場合があります。考えられるキーのリストが大きい場合、追跡が困難になるだけでなく、処理が非常に複雑でコストも高くなる可能性があります。次の例について考えてみましょう。
- 使用可能なすべての鍵のリストが大きい場合:
- 配信広告ネットワークが、20 個のキャンペーン(各キャンペーンに 10 個の広告グループ、各広告グループに 5 個のクリエイティブ)を含む複雑なユーザー獲得イニシアチブを実施しています。各クリエイティブはパフォーマンスに基づいて毎週更新されます。
- 使用可能なすべてのキーのリストは不明です。
- 配信広告ネットワークが、キャンペーンの開始時にパブリッシャーのアプリ ID の完全なリストが不明な多くのモバイルアプリに広告を配信している。
- 広告主が、ソース登録時に MMP にリダイレクトしない複数の配信広告ネットワークを使用している場合。各配信広告ネットワークには異なるキー構造と値があり、MMP と事前に共有されていない可能性があります。
キー検出機能の導入により、次のことが可能になります。
- 集計サービスで、使用可能な集計キーをすべて列挙する必要がなくなりました。
- 使用可能なキーの完全なリストを指定する必要はなく、MMP は空の(または部分的に空の)キーセットを作成し、しきい値を設定することで、しきい値を超える値を持つ(事前宣言されていない)キーのみが出力に含まれるようにすることができます。
- MMP には、設定したしきい値を超える貢献値を持つキーのノイズ値を含む概要レポートが送信されます。レポートには、実際のユーザーの貢献に関連付けられていないキーが含まれ、純粋にノイズが含まれていることもあります。
- MMP は、トリガー登録の
x_network_bit_mapping
フィールドを使用して、どの広告テクノロジーがどのキーに対応しているかを判断します。 - MMP は、適切な配信広告テクノロジーに連絡して、ソースキーの値を把握できます。
要約すると、キー検出により、MMP は事前に知ることなく集計キーを取得でき、ノイズの増加を犠牲に大量のソースキーを処理する必要がなくなります。
デイジー チェーン リダイレクト
ソースまたはトリガーの登録 HTTPS サーバー レスポンスで複数の Attribution-Reporting-Redirect
ヘッダーを提供することで、広告テクノロジーは Attribution Reporting API を使用して、1 回の登録 API 呼び出しで複数のソースとトリガーの登録を実行できます。
サーバー レスポンスでは、URL を含む 1 つの Location
(302 リダイレクト)ヘッダーを広告テクノロジーが含めることもできます。これにより、設定された上限まで別の登録が行われます。
どちらのタイプのヘッダーも省略可能です。リダイレクトが不要な場合は、どちらも指定しないでください。ヘッダーのタイプは 1 つまたは両方を指定できます。ソースとトリガーの登録リクエスト(リダイレクトを含む)は、ネットワーク障害が発生した場合に再試行されます。デバイスに大きな影響を与えないように、リクエストあたりの再試行回数は一定の数に制限されています。
ブラウザで使用される registerWebSource と registerWebTrigger では、リダイレクトは使用できません。詳しくは、ウェブとアプリのクロスイ mplementation ガイドをご覧ください。
アトリビューション レポートで測定データを表示する
Attribution Reporting API では、次の種類のレポートが可能です。詳細についてはこのページ内で別途説明します。
- イベントレベル レポートは、特定のアトリビューション ソース(クリックまたはビュー)を、限られたビットの忠実度の高いトリガーデータに関連付けます。
- 集計可能レポートは、必ずしも特定のアトリビューション ソースに関連付けられるわけではありません。イベントレベル レポートよりも豊富な、忠実度の高いトリガーデータが提供されますが、このデータは集計形式でしか利用できません。
これら 2 種類のレポートは相互に補完し合うものであり、同時に使用できます。
イベントレベル レポート
トリガーがアトリビューション ソースに帰属するとイベントレベル レポートが生成され、いずれかのレポート送信期間の間に各広告テクノロジーのポストバック URL に送信できるようになるまで、デバイスに保存されます。詳細についてはこのページ内で別途説明します。
イベントレベル レポートは、トリガーについて情報がほとんど必要ない場合に便利です。イベントレベルのトリガーデータは、クリックについては 3 ビットに制限され(つまり、トリガーが 8 つのカテゴリのいずれかに割り当てられます)、ビューについては 1 ビットに制限されます。また、イベントレベル レポートでは、特定の価格やトリガー時間など、忠実度の高いトリガー側データのエンコードはサポートされていません。アトリビューションはデバイスで行われるため、イベントレベルのレポートではクロスデバイス分析がサポートされません。
イベントレベル レポートには次のようなデータが含まれます。
- デスティネーション: トリガーが発生する広告主アプリのパッケージ名または eTLD+1
- アトリビューション ソース ID: アトリビューション ソースの登録に使用したものと同じアトリビューション ソース ID
- トリガータイプ: アトリビューション ソースのタイプに応じた、1 ビットまたは 3 ビットの低忠実度トリガーデータ
すべてのレポートに適用されるプライバシー保護メカニズム
次の上限は、アトリビューション ソースとトリガーに関する優先度を考慮して適用されます。
広告テクノロジーの数の制限
API のレポートを登録または受信できる広告テクノロジーの数には制限があり、現在の提案では次のようになっています。
- {ソースアプリ、デスティネーション アプリ、30 日、デバイス} ごとに、アトリビューション ソースがある広告テクノロジーが 100 個。
- {ソースアプリ、デスティネーション アプリ、30 日、デバイス} ごとに、関連付けられたトリガーがある広告テクノロジーが 10 個。
- 20 個の広告テクノロジーが 1 つのアトリビューション ソースまたはトリガーを登録可能(
Attribution-Reporting-Redirect
を使用)
一意の宛先数の上限
これらの上限により、広告テクノロジーが連携して大量のアプリにクエリを実行し、特定のユーザーのアプリ使用状況を把握することが困難になります。
- 登録されているすべてのソースと広告テクノロジー全体で、API がサポートする一意のデスティネーションは、ソースアプリごとに 1 分あたり 200 個までです。
- 登録されているすべてのソースで、1 つの広告テクノロジーに対して、API がサポートする一意のデスティネーション数は、ソースアプリごとに 1 分あたり 50 個以下です。この上限により、1 つの広告テクノロジーが前述のレート上限の予算をすべて使い切ってしまうことを防ぐことができます。
期限切れのソースは、レート制限にはカウントされません。
1 つのソースアプリに対して 1 日あたり 1 つのレポート送信元
特定の広告テクノロジー プラットフォームは、同じデバイスの同じ日に、パブリッシャー アプリのソースを登録するために、1 つのレポート送信元のみを使用できます。このレート制限により、広告テクノロジーが複数のレポート送信元を使用して追加のプライバシー バジェットにアクセスすることを防ぐことができます。
1 つの広告テクノロジーが、複数のレポート送信元を使用して、1 つのデバイスのパブリッシャー アプリにソースを登録したいとします。
- 広告テクノロジー A のレポート オリジン 1 がアプリ B のソースを登録する
- 12 時間後、広告テクノロジー A のレポート送信元 2 がアプリ B でソースの登録を試みます。
広告テクノロジー A のレポート送信元 2 の 2 つ目のソースは、API によって拒否されます。広告テクノロジー A のレポート作成元 2 は、翌日まで同じデバイスのアプリ B にソースを正常に登録できません。
クールダウンとレート制限
{ソース、デスティネーション} ペア間のユーザー 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 時間後に送信されます。この期限は構成できますが、1 日未満または 30 日を超える長さにすることはできません。2 つのトリガーが(インストール後のアトリビューションを介して)広告ビューのアトリビューション ソースに帰属する場合、イベントレベル レポートは次のように指定されたレポート期間の区切りで送信できます。
広告クリックのアトリビューション ソースのイベントレベル レポートは構成できません。ソースの期限が切れる前、または切れたときに、ソースの登録時点を基準とした特定の時点で送信されます。アトリビューション ソースから期限までの時間は、複数のレポート期間に分割されます。各レポート期間に(アトリビューション ソースの時間からの)期限があります。各レポート期間の最後に、デバイスは前回のレポート期間以降に発生したすべてのトリガーを収集し、スケジュール設定したレポートを送信します。この API は、次のレポート期間をサポートしています。
- 2 日間: デバイスは、アトリビューション ソースの登録から 2 日後までに発生したトリガーをすべて収集します。レポートは、アトリビューション ソースの登録から 2 日と 1 時間後に送信されます。
- 7 日間: デバイスは、アトリビューション ソースの登録から 2 日を超え、かつ 7 日以内に発生したトリガーをすべて収集します。レポートは、アトリビューション ソースの登録から 7 日と 1 時間後に送信されます。
- カスタム期間: アトリビューション ソースの「expiry」属性で定義します。レポートは、指定した期限の 1 時間後に送信されます。この値を 1 日未満または 30 日を超える長さにすることはできません。
柔軟なイベントレベルの設定
ユーティリティ テストを開始する際には、イベントレベル レポートのデフォルト設定を使用することを広告テクノロジーにおすすめしますが、すべてのユースケースに適しているとは限りません。Attribution Reporting API は、より柔軟な設定をオプションとしてサポートする予定です。これにより、広告テクノロジーはイベントレベル レポートの構造をより詳細に制御し、データの有用性を最大限に高めることができます。
この柔軟性は、次の 2 つのフェーズで Attribution Reporting API に導入されます。
- フェーズ 1: 柔軟なイベントレベル設定のライト版
- このバージョンは、すべての機能のサブセットを提供し、フェーズ 2 とは独立して使用できます。
- フェーズ 2: 柔軟なイベントレベル設定の完全版
フェーズ 1(柔軟なイベントレベルのライト版)を使用すると、次のことができます。
- レポート期間の数を指定してレポートの頻度を変更する
- ソース登録あたりのアトリビューション数を変更する
- 上記のパラメータを減らして、ノイズの総量を減らす
- デフォルトではなくレポート期間を設定
フェーズ 2(柔軟なイベントレベルの完全版)では、フェーズ 1 のすべての機能に加えて、次のことができます。
- レポートでトリガーデータのカーディナリティを変更する
- トリガーデータのカーディナリティを減らして、ノイズの総量を減らす
デフォルト設定の 1 つのディメンションを減らすと、広告テクノロジーは別のディメンションを増やすことができます。または、上記のパラメータを減らすことで、イベントレベル レポートのノイズの総量を減らすこともできます。
広告テクノロジーが選択した構成に基づいてノイズレベルを動的に設定するだけでなく、コンピューティング コストの増大や、出力状態が多すぎる構成(ノイズが大幅に増加する)を回避するために、いくつかのパラメータの上限が設定されます。制限の例を次に示します。[設計案][50] についてフィードバックをお寄せください。
- グローバルおよび trigger_data ごとに最大 20 件のレポート
- trigger_data ごとに最大 5 つのレポート期間
- トリガーデータのカーディナリティは最大 32(フェーズ 1: ライト フレキシブル イベントレベルには適用されません)
広告テクノロジーがこの機能を使用できるようになりますが、極端な値を使用するとノイズが多く発生したり、プライバシー レベルが満たされていない場合に登録に失敗したりする可能性があります。
集計可能レポート
集計可能レポートを使用する前に、クラウド アカウントをセットアップし、集計可能レポートの受信を開始する必要があります。
集計可能レポートは、イベントレベル レポートより忠実度の高いトリガーデータを、より迅速にデバイスから提供します。忠実度の高いデータは集計でしか学習できず、特定のトリガーまたはユーザーと関連付けられることはありません。集計キーは最大 128 ビットであり、集計可能レポートは次のようなレポートのユースケースをサポートできます。
- 収益などのトリガー値のレポート
- より多くのトリガータイプの処理
また、集計可能レポートはイベントレベル レポートと同じソース優先アトリビューション ロジックを使用しますが、クリックまたはビューに帰属する、より多くのコンバージョンをサポートします。
Attribution Reporting API で集計可能レポートを準備して送信する方法の全体的な設計を、図に示します。
- デバイスが、暗号化された集計可能レポートを広告テクノロジーに送信します。本番環境では、広告テクノロジーがこれらのレポートを直接使用することはできません。
- 広告テクノロジーが、集計可能レポートのバッチを集計サービスに送信します。
- 集計サービスが、集計可能レポートのバッチを読み取り、復号して集計します。
- 最終的な集計結果がサマリー レポートで広告テクノロジーに返されます。
集計可能レポートには、アトリビューション ソースに関連する次のデータが含まれます。
- デスティネーション: トリガーが発生したアプリのパッケージ名または eTLD+1 ウェブ URL。
- 日付: アトリビューション ソースで表されるイベントが発生した日付。
- ペイロード: 暗号化された Key-Value ペアとして収集されるトリガー値。信頼できる集計サービスで集計の計算に使用されます。
集計サービス
次のサービスは、データ集計機能を提供して、集計データへの不正アクセスを防ぎます。
これらのサービスは異なる当事者によって管理されています。詳細についてはこのページ内で別途説明します。
- 集計サービスは、広告テクノロジーでデプロイが想定される唯一のサービスです。
- 鍵管理サービスと集計可能レポートのアカウンティング サービスは、コーディネーターという信頼できる当事者によって実行されます。コーディネーターは、集計サービスを実行するコードが Google によって提供された一般公開のコードであることと、すべての集計サービス ユーザーに同じ鍵と集計可能レポートのアカウンティング サービスが適用されていることを証明します。
集計サービス
広告テクノロジー プラットフォームでは、Google によって提供されたバイナリに基づく集計サービスを事前にデプロイしておく必要があります。
この集計サービスは、クラウドでホストされた高信頼実行環境(TEE)で動作します。TEE には、次のようなセキュリティ上のメリットがあります。
- TEE で動作するコードが、Google によって提供された特定のバイナリであることが保証されます。この条件が満たされない限り、集計サービスはオペレーションに必要な復号鍵にアクセスできません。
- 実行中のプロセスにセキュリティを提供し、外部の監視や改ざんから隔離します。
こうしたセキュリティ上のメリットにより、集計サービスは、暗号化されたデータへのアクセスなどの機密性の高いオペレーションを安全に実施できるようになります。
集計サービスの設計、ワークフロー、セキュリティ上の考慮事項の詳細については、GitHub の集計サービスのドキュメントをご覧ください。
鍵管理サービス
このサービスは、集計サービスが承認済みのバージョンのバイナリを実行していることを確認してから、広告テクノロジーの集計サービスとトリガーデータの正しい復号鍵を提供します。
集計可能レポートのアカウンティング
このサービスは、広告テクノロジーの集計サービスが特定のトリガー(複数の集計キーを含む場合があります)にアクセスする頻度を追跡し、アクセス時の復号回数を適切な範囲に制限します。詳細については、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 API と Attribution Reporting API をクロス API で統合すると、さまざまなリマーケティング戦術におけるアトリビューションのパフォーマンスを評価し、最も高い費用対効果をもたらすオーディエンスのタイプを把握できます。
このクロス API 統合により、アドテックは次のことができます。
- 1)インタラクション レポートと 2)ソース登録の両方に使用される URI の Key-Value マップを作成します。
- 集計サマリー レポート(Attribution Reporting API を使用)のソースサイド キー マッピングに
CustomAudience
を含めます。
ユーザーが広告を閲覧またはクリックしたとき:
- Protected Audience を使用してインタラクションを報告するために使用された URL は、Attribution Reporting API でビューまたはクリックを有効なソースとして登録するためにも使用されます。
- 広告テクノロジーは、その URL を使用してカスタム オーディエンス(または広告プレースメントや視聴時間など、広告に関するその他の関連コンテキスト情報)を渡すことができます。これにより、広告テクノロジーがキャンペーンの総合的なパフォーマンスを確認する際に、このメタデータが概要レポートに反映されます。
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 でノイズがどのように適用されるかをより詳細に把握できます。
- 集計可能レポート:
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 を利用できる場合にのみ含めることができます。
- Body: レポートの本文。タイプによって異なります。
広告テクノロジーは、Attribution-Reporting-Register_Source
ヘッダーと Attribution-Reporting-Register-Trigger
ヘッダーの新しい debug_reporting
ディクショナリ フィールドを使用して、詳細デバッグ レポートの受信を有効にする必要があります。
- ソース詳細レポートでは、ソース登録ヘッダーでのみオプトインする必要があります。
- トリガーのデバッグ レポートは、トリガー登録ヘッダーでのみ有効にする必要があります。
デバッグ レポートの使用方法
(既存の測定システムによる)コンバージョンが発生し、そのコンバージョンのデバッグ レポートを受信した場合、これはトリガーが正常に登録されたことを意味します。
デバッグ アトリビューション レポートごとに、2 つのデバッグキーに一致する通常のアトリビューション レポートを受信しているかどうかを確認します。
一致がない場合、いくつかの原因が考えられます。
意図したとおりの動作:
- プライバシー重視の API 動作:
- ユーザーがレポートのレート制限に達し、それ以降のレポートがすべて期限内に送信されなくなる。または、保留中のデスティネーション制限によりソースが削除される。
- イベントレベル レポート: レポートがランダム化レスポンス(ノイズ)の対象となり、抑制される。または、ランダム化レポートを受信することがある。
- イベントレベル レポート: レポートが 3 回(クリック数)または 1 回(ビュー数)の上限に達し、後続のレポートに明確な優先度が設定されていないか、既存のレポートよりも低い優先度が設定されている。
- 集計可能レポートの投稿制限を超えている。
- 広告テクノロジーで定義されたビジネス ロジック:
- トリガーがフィルタまたは優先度ルールによってフィルタされる。
- 時間遅延、またはネットワークの可用性との連携(ユーザーが長時間デバイスの電源をオフにした場合など)。
意図しない原因:
- 実装の問題:
- ソースヘッダーが正しく構成されていない。
- トリガー ヘッダーが正しく構成されていない。
- その他の構成の問題。
- デバイスまたはネットワークの問題:
- ネットワーク状態に起因する障害。
- ソースまたはトリガーの登録レスポンスがクライアントに届かない。
- API のバグ。
今後の検討事項と未解決の問題
Attribution Reporting API は現在開発中です。また、ラストクリック アトリビューション以外のモデルやクロスデバイス測定のユースケースなど、将来的な機能についても検討しています。
いくつかの問題点について、コミュニティからのフィードバックもお待ちしております。
- 検証済みインストールのレポートを API で送信するユースケースはあるでしょうか。そうしたレポートは、広告テクノロジー プラットフォームのレート制限にカウントされます。
- ソース登録のためにアプリから広告テクノロジーに
InputEvent
を渡すことに難点があると思いますか。 - プリロードされたアプリまたは再インストールされたアプリに特別なアトリビューションのユースケースはありますか。