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 に送信されるため、第三者測定プロバイダが登録を重複してカウントする可能性があります。登録の重複カウントを防ぐため、広告テクノロジーはリダイレクトの動作を変更して、Attribution Reporting API の登録を代替の決定論的 URL に送信できます。

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

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

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

    のセクションを参照してください。

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

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

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

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

      Attribution-Reporting-Support: os, web

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

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

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

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

      3. OS API が、ブラウザから渡された広告テクノロジー URI へのセカンダリ 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 は、ウェブソースとアプリトリガーを照合し、関連するレポートを送信できます。

ウェブからアプリへのアトリビューションのフロー
Web to app アトリビューション フロー

ウェブソースの登録:

  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. パブリッシャーのウェブサイト上の広告テクノロジーが、Chrome に登録を Android Attribution Reporting API に委任するよう指示してソースを登録します。

    • ウェブからアプリへのユースケースでは、ソースを登録する際に、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 へのセカンダリ 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
    • ソース登録を完了するには、広告テクノロジーのエンドポイントが、レスポンス ヘッダー Attribution-Reporting-Register-Source を使用して Android Attribution Reporting API リクエストに応答する必要があります。レスポンスでは、宛先フィールドにアプリの宛先も指定する必要があります。
    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 トリガーを登録する

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 の eTLD+1 ではなくアプリに関連付けられるべき WebView ベースのアプリ。
      無効 WebView からのソースとトリガーの登録を無効にします。
    1. WebView からのソースとトリガーの登録

    2. 広告テクノロジーは、Attribution-Reporting-Register-OS-Source ヘッダーを使用してソース登録に応答する必要があります。WebView の設定された動作に基づいて、OS で registerSource() または registerWebSource() を呼び出し、Android アトリビューション レポート 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"]}
    ],
    ...
}

デバッグ

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

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