AdServices を構成する

次の手順に沿って API 固有の権限を宣言し、対象の API で管理されているリソースへの SDK アクセスを構成します。

AdServices API 固有の権限を宣言する

各 PPAPI にアクセスするには、広告サービスの normal 権限が必要です。マニフェストで、アプリまたは SDK に必要な API に対応する適切なアクセス権限を宣言します。

Attribution Reporting API:

<uses-permission android:name="android.permission.ACCESS_ADSERVICES_ATTRIBUTION" />

Attribution Reporting API(デバッグ レポート付き):

<uses-permission android:name="android.permission.ACCESS_ADSERVICES_ATTRIBUTION" />
<uses-permission android:name="android.permission.ACCESS_ADSERVICES_AD_ID" />

Protected Audience / Custom Audience API:

<uses-permission android:name="android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE" />

Topics API:

<uses-permission android:name="android.permission.ACCESS_ADSERVICES_TOPICS" />

Attribution Reporting API でデバッグ レポートを受け取るには、AD_ID 権限を含めます。

<uses-permission android:name="android.permission.ACCESS_ADSERVICES_AD_ID" />

プロジェクトがモジュールまたは SDK に依存している場合は、必要な広告サービスの権限をマニフェスト ファイルですでに宣言している可能性があります。デフォルトでは、Gradle ビルドはすべてのマニフェスト ファイルを、アプリ内にパッケージ化した単一のマニフェスト ファイルにマージします。[Merged Manifest] ビューを使用して、適切な権限が使用されているか確認します。

SDK などの依存関係を介していずれかの権限がアプリにマージされるのを防ぐには、特定の権限に remove ノードマーカーを含めます。次の例は、Topics 権限のマージを防ぐ方法を示しています。

<uses-permission android:name="android.permission.ACCESS_ADSERVICES_TOPICS"
    tools:node="remove" />

API 固有の広告サービスを構成する

PPAPI のアクセス権限と同様、各 API の広告サービス構成には、対応するエントリがあります。この構成により、アプリまたは埋め込み SDK の API によって管理されるリソースへのアクセス権をきめ細かく制御できます。マニフェストで、次の例のように adservicesConfig プロパティを指定します。

<application ...>
      ...
    <property android:name="android.adservices.AD_SERVICES_CONFIG"
        android:resource="@xml/ad_services_config" />

      ...
</application>

マニフェストで参照される広告サービス XML リソースを指定します(res/xml/ad_services_config.xml など)。アプリ(または埋め込み SDK)に適用されるプライバシー保護 API ごとに、allowAllToAccess 属性を true に設定して、呼び出し元にアクセス権を付与します。

または、allowAdPartnersToAccess 属性を使用して、広告テクノロジーごとにきめ細かい API アクセスを許可することもできます。登録から取得したデベロッパー登録アカウント ID のリストを提示する必要があります。allowAllToAccess 属性が true に設定されている場合、この属性は allowAdPartnersToAccess 属性で指定されたすべての登録アカウント ID よりも優先されます。

広告テクノロジー プラットフォームでは、必要なプライバシー保護 API へのアクセスをアプリ クライアントが広告サービス構成で適切に付与できるようにする必要があります。

次の例は、すべての登録アカウント ID にすべてのプライバシー保護 API へのアクセスを許可する広範なアクセス権を指定する方法を示しています。

<ad-services-config>
   <!-- Attribution API -->
   <attribution allowAllToAccess="true" />

   <!-- Topics API -->
   <topics allowAllToAccess="true" />

   <!-- Protected Audience on Android API -->
   <custom-audiences allowAllToAccess="true" />
</ad-services-config>

次の例は、特定の登録アカウント ID に対して、各プライバシー保護 API へのきめ細かいアクセスを指定する方法を示しています。

<ad-services-config>
    <!-- Attribution API -->
    <attribution allowAdPartnersToAccess="ENROLLMENT-ID" allowAllToAccess="false" />

    <!-- Topics API -->
    <includes-sdk-library name="ENROLLMENT-ID" />
    <topics allowAdPartnersToAccess="ENROLLMENT-ID" allowAllToAccess="false" />

    <!-- Protected Audience on Android API -->
    <custom-audiences allowAdPartnersToAccess="ENROLLMENT-ID" allowAllToAccess="false" />
</ad-services-config>

Jetpack ライブラリの依存関係を宣言する

ads-adservices Jetpack ライブラリ 1.0.0-beta01 以降を使用して、プライバシー サンドボックスのプライバシー保護 API と統合します。このライブラリを使用すると、プラットフォーム レベルの詳細からアプリを抽象化し、プライバシー保護 API との統合を簡素化できます。

  1. プロジェクトに Maven リポジトリを追加します。
  2. アプリまたはモジュールの build.gradle ファイルで ads-adservices Jetpack ライブラリの依存関係を宣言します。
  3. androidx.privacysandbox.ads.adservices.* パッケージの API を使用します。
  4. ads-adservices Jetpack ライブラリは、組み込みの Kotlin コルーチンをサポートします。コルーチン スコープを管理するには、プロジェクトに適したライフサイクル対応の依存関係の組み込みが必要になることがあります。

広告サービス拡張機能のバージョンの可用性を確認する

ads-services Jetpack ライブラリを使用してプライバシー保護 API を統合している場合、ライブラリは obtain() 関数でリクエストされた API が利用可能かどうかを確認します。リクエストされた API がデバイスで利用できない場合、この関数は null を返します。次の例は、Topics API の TopicsManager を初期化する方法を示しています。他のプライバシー保護 API へのアクセスに関しても同様に機能します。

Kotlin

import androidx.privacysandbox.ads.adservices.topics.TopicsManager

// The initialization function will return null if the requested
// functionality is not available on the device.
val topicsManager = TopicsManager.obtain(context)

Java

import androidx.privacysandbox.ads.adservices.topics.TopicsManager;

// The initialization function will return null if the requested
// functionality is not available on the device.
TopicsManager topicsManager = TopicsManager.obtain(context);

拡張機能 SDK で AdServices API を直接使用している場合は、使用する AdServices API が含まれている広告サービス拡張機能のバージョンを確認します。API リファレンスでは、特定の AdServices API が導入されているバージョンを確認できます。たとえば、TopicsManager クラスの API リファレンスは、「広告サービス拡張機能 4 に追加されている」ことを示します。次の条件チェックを使用して、AdServices API を含む SDK 拡張機能を検証します。

Kotlin

import android.os.ext.SdkExtensions

if (SDK_INT >= Build.VERSION_CODES.R && // The extensions API is available since R.
   SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4) {

    // AdServices API is available.
...
}

Java

import android.os.ext.SdkExtensions;

if (SDK_INT >= Build.VERSION_CODES.R && // The extensions API is available since R.
   SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4) {

    // AdServices API is available.
...
}

フォアグラウンド アクセスの制限

透明性を確保するため、SDK ランタイムとプライバシー保護 API にアクセスできるアプリは、アクティビティが公開されているアプリ、または RunningAppProcessInfoIMPORTANCE_FOREGROUND のアプリに限定されます。