Attribution Reporting API クロスウェブとアプリ実装ガイド

Attribution Reporting API を使用すると、同じデバイスで発生したソースとトリガーのクロスアプリ アトリビューションとクロスウェブ アトリビューションが可能になります。Chrome などのブラウザでは、ソースとトリガーの両方の登録をブラウザで処理するのではなく、Android 向け Attribution Reporting API に委任できます。これにより、Android はサイトとアプリの両方でソースとトリガーを照合できます。

このガイドでは、アプリとウェブのクロス アトリビューションを設定する方法について説明します。

クロスアプリとウェブのアトリビューションを設定する際は、設定が意図したとおりに機能していることを確認するために、利用可能なデバッグ ソリューションについても理解しておくことを強くおすすめします。

Android OS でソースとトリガーを登録する

アプリとウェブのクロス アトリビューションは、同じデバイスのブラウザと Android OS の両方で Attribution Reporting API が有効になっている場合にのみ利用できます。Android Attribution Reporting API の可用性は、Attribution-Reporting-Support ヘッダーを介して送信されます。このヘッダーは、デバイスで利用可能なものに応じて、os、web、またはその両方を返します。両方が利用可能な場合は、広告テクノロジーがブラウザまたは OS のいずれかでウェブソースとウェブトリガーを登録できます。

広告テクノロジーは、ウェブソースまたはウェブトリガーをブラウザまたは OS に登録するかどうかを決定する必要があります。

• ウェブ専用キャンペーンの場合、広告テクノロジーは引き続き Chrome の Attribution Reporting API でソースとトリガーの両方を登録できます。また、両方を OS に委任することもできます。ソースまたはトリガーが WebView で発生する可能性があるウェブ専用キャンペーンの場合、広告テクノロジーはソースとトリガーの両方の登録を OS に委任する必要があります。詳しくは、WebView に関するセクションをご覧ください。

• 重複するアトリビューション レポートが作成されないように、広告テクノロジーは Chrome API と Android API の両方でソースとトリガーを同時に登録しないでください。

• アトリビューションは、ブラウザと OS で別々に行われます。ソースがブラウザに登録されていて、トリガーが OS に登録されている場合、これら 2 つを一致させることはできません。また、その逆も同様です。

• アプリまたはウェブのトリガーが発生する可能性があるソースの場合は、広告テクノロジーがウェブソースとトリガーの登録を Android Attribution Reporting API に委任することを強くおすすめします。

• アプリベースのソースによってトリガーされた可能性がある場合、広告テクノロジーは、ウェブトリガーの登録を Android Attribution Reporting API に委任できます。

• ソースとトリガーの両方がアプリ内で発生するキャンペーンの場合は、両方を OS Attribution Reporting API に登録する必要があります。

アプリソースとウェブトリガーを登録する

キャンペーンによっては、ソースがアプリで発生し、トリガーが同じデバイスのモバイル ブラウザのウェブサイトで発生する場合があります。

例

ユーザーがよく使うニュースアプリで記事を読んでいると、パリ行きの格安航空券の広告が表示され、ワクワクしながらクリックして予約します。ニュースアプリで広告を配信する広告テクノロジーが、Android Attribution Reporting API にクリック ソースを登録します。ユーザーは Chrome で広告主のウェブページに移動し、コンバージョンに至ることができます。広告主のサイトで広告テクノロジーが OS レベルの API が使用可能かどうかを確認し、使用可能であれば、Chrome の Attribution Reporting API で直接登録するのではなく、登録を OS に委任するよう Chrome に指示してコンバージョン トリガーを登録します。OS レベルの Attribution Reporting API は、アプリソースとウェブ トリガーを照合し、関連するレポートを送信できます。

アプリソースの登録:

1. Daily News Android アプリの広告テクノロジー SDK は、registerSource() を使用してクリックを登録します。

2. Android の Attribution Reporting API は、registerSource() に指定された広告テクノロジー サーバー URL にリクエストを送信します。

3. 広告テクノロジー サーバーが Attribution-Reporting-Register-Source ヘッダーで応答し、ソースの登録を完了します。

ウェブ トリガーの登録:

1. 広告テクノロジーがトリガーを登録し、Attribution Reporting API で OS の可用性を確認します。

2. ウェブ ARA は、サポートされているプラットフォームに関する情報を返します。

3. OS-Trigger ヘッダーは、OS ARA API registerWebTrigger() 関数を呼び出すよう、ウェブ ARA API に指示します。

4. registerWebTrigger() への呼び出しは内部で行われるため、デベロッパーは OS で registerWebTrigger() を直接呼び出す必要はありません。

5. OS ARA が引き継ぎ、Attribution-Reporting-Register-OS-Trigger ヘッダーで指定された広告テクノロジー サーバー URL にリクエストを送信します。

6. 広告テクノロジーが OS API を使用してトリガーの登録を完了します。

7. OS ARA は、アプリ間アトリビューションに適用されるロジックに従ってアトリビューションを実行し、同じレポートを送信します。

ワークフロー

次の手順では、タスクを完了する方法について詳しく説明します。

1. アプリの広告テクノロジーが、Android の Attribution Reporting API にソースを登録します。このとき、以下の調整が行われます。

   • ウェブサイトでコンバージョンが見込まれるアプリソースを登録するには、Attribution-Reporting-Register-Source レスポンス ヘッダーに、アプリのデスティネーションではなくウェブのデスティネーション（eTLD+1）を含める必要があります。

   Attribution-Reporting-Register-Source: {
       "web_destination": "https://advertiser.example",
       ...
   }
   

   • 一部の広告主は、302 リダイレクト チェーンを使用して複数の測定プロバイダ（サードパーティの測定ツールや分析ツールなど）を使用している場合があります。場合によっては、Attribution Reporting API が Attribution-Reporting-Redirect ヘッダーで指定されたリダイレクト パスに従ってバックグラウンドで実行され、同時に、既存のナビゲーション リクエストに対して 302 リダイレクト パスがフォアグラウンドで実行されます。これらのリクエストは同じ URL に送信されるため、第三者測定プロバイダで登録が重複してカウントされる可能性があります。登録の重複を防ぐため、広告テクノロジーはリダイレクト動作を変更して、代替の確定的な URL に Attribution Reporting API の登録を送信できます。

   • この動作を有効にするには、広告テクノロジーが登録リクエストに応答するときに、新しい HTTP ヘッダーを含める必要があります。

     • ヘッダーは Attribution-Reporting-Redirect-Config です。
     • ヘッダーの値は redirect-302-to-well-known にする必要があります。

     Attribution-Reporting-Redirect-Config: redirect-302-to-well-known
     

   • ソース登録プロセスの残りの部分は、標準のアプリ間ソース登録と同じです。

2. 広告主のウェブサイト上の広告テクノロジーが、登録を Android Attribution Reporting API に委任するよう Chrome にリクエストして、トリガーを登録します。

   • ユーザーがウェブサイトでコンバージョンを完了すると、広告テクノロジーが Chrome にトリガーを登録するためのリクエストを送信します。

     1. ピクセル リクエストまたは fetch() リクエストを使用して、トリガーを登録するリクエストを送信できます。

     2. Attribution-Reporting-Support リクエスト ヘッダーは、Chrome から広告テクノロジーに返されます。Chrome ブラウザと Android デバイスの両方で API が有効になっている場合、ヘッダーは os, web を返します。

     Attribution-Reporting-Support: os, web
     

   • 広告テクノロジーは、Attribution-Reporting-Register-OS-Trigger ヘッダーを使用して Chrome に OS に委任するよう指示する必要があります。このヘッダーは次のように機能します。

     1. 登録を OS に委任するよう Chrome に指示します。

     2. Chrome は、OS API 関数 registerWebTrigger() を呼び出して、登録を OS に委任します。

        • registerWebTrigger() への呼び出しは内部で行われるため、広告テクノロジーが registerWebTrigger() を直接呼び出す必要はありません。

     3. OS API が、ブラウザから渡された広告テクノロジー URI への 2 番目の API 呼び出しを開始します。

     Attribution-Reporting-Register-OS-Trigger: "https://adtech.example/register-trigger",
     "https://other-adtech.example/register-trigger"
     

   • Attribution-Reporting-Support ヘッダーが使用できない場合、送信できません。このような場合でも、広告テクノロジーは Attribution-Reporting-Info ヘッダーを含めることで、トリガー登録を処理する優先プラットフォームを設定できます。キーは preferred-platform で、許可される値は os と web です。ブラウザは、優先プラットフォームが利用可能な場合はそのプラットフォームを使用し、OS が利用できない場合はウェブ プラットフォームにフォールバックします。

   Attribution-Reporting-Info: preferred-platform=os
   

   • トリガー登録を完了するには、広告テクノロジーのエンドポイントがレスポンス ヘッダーを使用して Android Attribution Reporting API リクエストに応答する必要があります。

   Attribution-Reporting-Register-Trigger: {
       "event_trigger_data": [{"trigger_data":"1"}],
       "aggregatable_trigger_data": [
           {"key_piece":"0x400","source_keys":["campaignCounts"]},
           {"key_piece":"0xA80","source_keys":["geoValue"]}
       ],
       ...
   }
   

   • トリガーの登録の残りの部分は同じです。

ウェブソースとアプリトリガーを登録する

キャンペーンによっては、ソースがモバイル ブラウザのサイトで発生し、トリガーが同じデバイス上のアプリで発生する場合があります。

例

ユーザーが Android スマートフォンの Chrome ブラウザでサイトを閲覧している。ユーザーは、お気に入りのショップのセーターの広告を目にします。ユーザーが広告をクリックすると、すでにダウンロード済みのアプリが表示されます。広告が配信されたウェブサイトの広告テクノロジーが、Chrome の Attribution Reporting API を使用する代わりに、登録を Android Attribution Reporting API に委任するよう Chrome に指示することで、クリック ソースを登録します。ユーザーがショッピング アプリでセーターを購入すると、広告主のアプリの広告テクノロジーが Android Attribution Reporting API でコンバージョン トリガーを登録します。OS レベルの Attribution Reporting API は、ウェブソースとアプリ トリガーを照合し、関連するレポートを送信できます。

ウェブソースの登録:

1. 広告テクノロジーがソースを登録し、Attribution Reporting API で OS の可用性を確認します。

2. ウェブ ARA は、サポートされているプラットフォームに関する情報を返します。

3. OS-Source ヘッダーは、OS ARA API registerWebSource() 関数を呼び出すよう、ウェブ ARA API に指示します。

4. registerWebSource() への呼び出しは内部で行われるため、デベロッパーは OS で registerWebSource() を直接呼び出す必要はありません。

5. OS ARA が引き継ぎ、Attribution-Reporting-Register-OS-Source ヘッダーで指定された広告テクノロジー サーバー URL にリクエストを送信します。

6. 広告テクノロジーが OS API を使用してソースの登録を完了します。

アプリ トリガーの登録:

1. 衣料品店の Android アプリの広告テクノロジー SDK が、OS ARA にトリガーを登録します。

2. Android の Attribution Reporting API は、registerTrigger() に指定された広告テクノロジー サーバー URL にリクエストを送信します。

3. 広告テクノロジー サーバーが Attribution-Reporting-Register-Trigger ヘッダーで応答し、トリガーの登録を完了します。

4. OS ARA は、アプリ間アトリビューションに適用されるロジックに従ってアトリビューションを実行し、同じレポートを送信します。

ワークフロー

次の手順では、タスクを完了する方法について詳しく説明します。

1. パブリッシャーのウェブサイト上の広告テクノロジーが、登録を Android Attribution Reporting API に委任するよう Chrome に指示することで、ソースを登録します。

   • ウェブからアプリへのユースケースの場合、ソースを登録する際に、attributionsrc タグを使用するか、JavaScript 登録を使用して、アトリビューション ソース パラメータを直接指定する必要があります。
   • 次の例では、attributionsrc タグを使用してソース パラメータを指定しています。

   <img src="https://adtech.example/conversionpixel"
   attributionsrc="https://adtech.example/register-source?purchase=12">
   

2. Attribution-Reporting-Support リクエスト ヘッダーは、Chrome から広告テクノロジーに返されます。Chrome ブラウザと Android デバイスの両方で API が有効になっている場合、ヘッダーは os, web を返します。

   Attribution-Reporting-Support: os, web
   

3. 広告テクノロジーは、Attribution-Reporting-Register-OS-Source ヘッダーを使用して OS レベルの API に委任するよう Chrome に指示する必要があります。このヘッダーは次のように使用します。

   1. 登録を OS に委任するよう Chrome に指示します。
   2. Chrome は、OS API 関数 registerWebSource() を呼び出して、登録を OS に委任します。
   3. registerWebSource() への呼び出しは内部で行われるため、広告テクノロジーが registerWebSource() を直接呼び出す必要はありません。
   4. OS API が、ブラウザから渡された広告テクノロジー URI への 2 番目の API 呼び出しを開始します。

   Attribution-Reporting-Register-OS-Source: "https://adtech.example/register-source"
   

   • Attribution-Reporting-Support ヘッダーを使用できない場合もあります。このような場合でも、広告テクノロジーは Attribution-Reporting-Info ヘッダーを含めることで、ソース登録を処理する優先プラットフォームを設定できます。キーは preferred-platform で、指定できる値は os と web です。ブラウザは、利用可能な場合は優先プラットフォームを使用し、OS を使用できない場合はウェブ プラットフォームにフォールバックします。

   Attribution-Reporting-Info: preferred-platform=os
   

   • ソースの登録を完了するには、広告テクノロジーのエンドポイントが Android Attribution Reporting API リクエストにレスポンス ヘッダー Attribution-Reporting-Register-Source で応答する必要があります。レスポンスでは、destination フィールドにアプリのリンク先も指定する必要があります。

   Attribution-Reporting-Register-Source: {
       "source_event_id":"123001",
       "destination":"android-app://com.example.advertiser",
       ...
   }
   

   • ソース登録のリダイレクトをサポートするため、Chrome はリダイレクトをたどり、リダイレクト ホップごとに ウェブ コンテキスト API を呼び出します。
   • ソース登録の残りの手順は同じです。

4. 広告主のアプリの広告テクノロジーが、Android Attribution Reporting API にトリガーを登録します。

   • アプリ内で発生するトリガーの場合、アプリは通常どおり Android Attribution Reporting API にトリガーを登録します。

アプリとウェブの両方の見込み顧客のリンク先があるキャンペーン

1. デュアル デスティネーションを設定する

   • 一部のキャンペーンでは、ユーザーがアプリをインストールしているかどうかなど、さまざまな要素に応じて、広告主のアプリまたは広告主のウェブページでコンバージョンが発生するように設定されている場合があります。
   • このような場合は、トリガーが発生した場所に関係なくソースを正しくアトリビューションできるように、ソース登録を OS に委任することをおすすめします。OS にソースを登録する際、アプリとウェブの両方のデスティネーションをそれぞれのパラメータで指定できます。
   • アプリのリンク先が destination フィールドに指定されている
   • ウェブのリンク先は web_destination フィールドに指定する必要があります
   • Chrome デベロッパーは、OS Attribution Reporting API の destination フィールドは URL ではなくアプリ パッケージである必要があることに注意してください。

   Attribution-Reporting-Register-Source: {
       "source_event_id":"123001",
       "destination":"android-app://com.example.advertiser",
       "web_destination": "https://example.advertiser"
       ...
   }
   

   • 次のセクションの概要レポートでは、デスティネーションを 2 つ使用するとレポートのノイズにどのような影響があるかについて説明します。

2. 粗いレポートを使用して、デュアル デスティネーション ソースのイベントレベル レポートのノイズを低減します。

   • ソースの登録で OS（アプリ）とウェブの両方のリンク先が指定されている場合、イベントレベル レポートでは、トリガーがウェブのリンク先とアプリのリンク先のどちらで発生したかがデフォルトで指定されます。ただし、プライバシーの制限を維持するため、これらのレポートには追加のノイズが追加されます。
   • 広告テクノロジーは、Attribution-Reporting-Register-Source ヘッダーの coarse_event_report_destinations フィールドを使用して、大まかなレポートを有効にしてノイズを低減できます。coarse_event_report_destinations フィールドが指定されているソースがアトリビューションを獲得した場合、生成されるレポートには、実際のトリガーが発生した場所を区別することなく、アプリとウェブの両方のリンク先が含まれます。ただし、アプリまたはウェブのリンク先が指定されているレポートよりもノイズが少なくなります。
   • 集計レポートは変更されません。

Chrome カスタムタブを使用するアプリの場合

一部のアプリでは、カスタムタブを使用してウェブ コンテンツをレンダリングすることがあります。カスタムタブは、アプリとモバイルウェブサイト全体で測定する場合、通常のウェブページと同様に動作します。

1. アプリソースとカスタムタブ トリガーを登録します。

   • 手順に沿ってアプリソースとウェブトリガーを登録します。

2. カスタムタブのソースとアプリトリガーを登録します。

   • 手順に沿ってウェブソースとアプリトリガーを登録します。

3. CCT ソースと CCT トリガーを登録する

   • これは、Chrome のサイト間ウェブ アトリビューションと同じように扱われます。

WebView を使用するアプリの場合

一部のアプリでは、WebView を使用してコンテンツを表示しています。WebView には、広告のレンダリング、ウェブ コンテンツのホスティング、ウェブ形式に適したカスタム アプリ機能など、さまざまなユースケースがあります。

1. WebView が Attribution Reporting API を使用できるようにするには、埋め込みアプリに適切な権限を構成する必要があります。

2. WebView では、OS レベルのアトリビューションのみが使用できます。Attribution-Reporting-Support ヘッダーは、Android Attribution Reporting API が使用可能な場合にのみ、os のみを返します。

3. OS に委任する場合、WebView は registerSource または registerWebSource と registerTrigger または registerWebTrigger を使用します。WebView で使用されるメソッドは、WebView をレンダリングするアプリによって設定され、WebView ごとに決まります。

   • registerSource と registerWebSource の違いは、パブリッシャーとしてログに記録されるソースです。registerSource を使用すると、アプリはパブリッシャーとしてログに記録されます。registerSource を使用する例としては、WebView を使用してレンダリングされた広告を表示するパブリッシャー アプリなどがあります。registerWebSource を使用すると、WebView でホストされているウェブサイトがパブリッシャーとしてログに記録されます。registerWebSource を使用する例としては、WebView をホストするアプリがあり、WebView によってレンダリングされているウェブサイトに広告が表示されている場合などがあります。registerTrigger と registerWebTrigger は同様に動作します。項目 3 の表に、アプリまたは SDK デベロッパーが registerSource または registerWebSource、registerTrigger または registerWebTrigger を使用するように API を構成する必要があるさまざまなシナリオが示されています。
   • デフォルトでは、WebView は Android Attribution Reporting API を呼び出すときに registerSource と registerWebTrigger を使用します。これにより、ソースがアプリに関連付けられ、トリガーが発生したときに WebView の URL のトップレベルのオリジンにトリガーが関連付けられます。

     • アプリで異なる動作が必要な場合は、androidx.webkit.WebViewSettingsCompat クラスの新しいメソッド setAttributionRegistrationBehavior を使用する必要があります。このメソッドでは、WebView が registerSource() または registerTrigger() ではなく registerWebSource() または registerWebTrigger() を呼び出すかどうかを指定します。

     • この動作は、開始される WebView ごとに設定する必要があります。

     • 広告テクノロジー SDK が WebView を開始する場合は、SDK でこのデフォルトの動作を設定する必要があります。

     • registerWebSource() を使用して、アプリではなく WebView 内のウェブサイトにソース登録を関連付けるアプリは、WebApp 許可リストに登録する必要があります。許可リストに登録するには、こちらのフォームにご入力ください。許可リストの目的は、ウェブ コンテキストに対する信頼の確立に関するプライバシーの懸念を軽減することです。

     値	説明	ユースケースの例
     APP_SOURCE_AND_WEB_TRIGGER（デフォルト）	アプリが WebView からアプリソース（アプリのパッケージ名に関連付けられたソース）とウェブトリガー（eTLD+1 に関連付けられたトリガー）を登録できるようにします。	ウェブ ブラウジングではなく WebView を使用して広告を配信するアプリ
     WEB_SOURCE_AND_WEB_TRIGGER	アプリが WebView からウェブソースとウェブトリガーを登録できるようにします。	WebView ベースのブラウザアプリ: 広告のインプレッションとコンバージョンの両方が WebView 内のウェブサイトで発生する可能性があります。
     APP_SOURCE_AND_APP_TRIGGER	WebView からアプリソースとアプリトリガーを登録できるようにします。	WebView ベースのアプリ。広告のインプレッションとコンバージョンは、WebView の eTLD+1 ではなく、常にアプリに関連付ける必要があります。
     無効	WebView からのソースとトリガーの登録を無効にします。

   1. WebView からのソースとトリガーの登録

   2. 広告テクノロジーは、Attribution-Reporting-Register-OS-Source ヘッダーを使用してソース登録に応答する必要があります。WebView に設定された動作に基づいて、OS で registerSource() または registerWebSource() を呼び出し、Android Attribution Reporting API から広告テクノロジー URI へのセカンダリ API 呼び出しを開始します。

      • ソースの登録を完了するには、広告テクノロジーのエンドポイントが Android Attribution Reporting API リクエストにレスポンス ヘッダーで応答する必要があります。

       Attribution-Reporting-Register-OS-Source: {
        "source_event_id":"123001",
        "destination":"android-app://com.example.advertiser",
        ...
      }
      

   3. ソース登録の残りの手順は同じです。

   4. 広告テクノロジーは、Attribution-Reporting-Register-OS-Trigger ヘッダーを使用してトリガー登録に応答する必要があります。WebView に設定された動作に基づいて、OS で registerTrigger() または registerWebTrigger() を呼び出し、Rb から広告テクノロジー URI へのセカンダリ API 呼び出しを開始します。

   5. トリガーの登録を完了するには、広告テクノロジーのエンドポイントが Android Attribution Reporting API リクエストにレスポンス ヘッダーで応答する必要があります。

   Attribution-Reporting-Register-OS-Trigger: {
       "event_trigger_data": [{"trigger_data":"1"}],
       "aggregatable_trigger_data": [
           {"key_piece":"0x400","source_keys":["campaignCounts"]},
           {"key_piece":"0xA80","source_keys":["geoValue"]}
       ],
       ...
   }
   

   • トリガー登録プロセスの残りの部分は同じです。

デバッグ

アプリからウェブへの実装をセットアップする場合は、デバッグ レポートを設定して、ソースとトリガーが正しく登録されているかどうかを確認し、登録されていない場合はその理由に関する情報を受け取ることをおすすめします。

アトリビューション レポートのデバッグ手順については、デバッグ クックブックをご覧ください。