AdServices を構成する

Android 版プライバシーサンドボックスのドキュメントをご覧になる際は、[デベロッパープレビュー] または [ベータ版] ボタンで対象のプログラムバージョンを選択してください（手順が異なる場合があります）。

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

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

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

Attribution Reporting API:

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

FLEDGE / Custom Audience API:

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

Topics API:

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

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" />

   <!-- FLEDGE 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" />

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

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

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

プロジェクトに Maven リポジトリを追加します。
アプリまたはモジュールの build.gradle ファイルで ads-adservices Jetpack ライブラリの依存関係を宣言します。
androidx.privacysandbox.ads.adservices.* パッケージの API を使用します。
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 へのアクセスは、アクティビティが公開されるアプリ、または IMPORTANCE_FOREGROUND の RunningAppProcessInfo があるアプリに制限されます。