Configure AdServices for Android

Follow the instructions below to declare API-specific permissions and configure SDK access to resources managed by the targeted API.

Note: There is a new Jetpack library that enables integration with Privacy Sandbox's Privacy-Preserving APIs (Topics, Protected Audience and Attribution Reporting. You can use this library as a drop-in replacement for the Privacy Sandbox APIs provided in the Extension SDK.

Declare AdServices API-specific permissions

Access to each PPAPI requires an Ad Services normal permission. In your manifest, declare the appropriate access permissions that correspond to the APIs needed in your app or SDK.

Attribution Reporting API:

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

Attribution Reporting API (with debug reports):

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

Optionally, to receive debug reports with the Attribution Reporting API, include the AD_ID permission:

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

If your project has dependencies on modules or SDKs, they may already declare the required Ad Services permissions in their manifest files. By default, the Gradle build merges all manifest files into a single manifest file that's packaged into your app. Use the Merged Manifest view to verify that the correct permissions are used.

If you need to prevent any of the permissions from getting merged into your app through dependencies such as SDKs, include the remove node marker for the particular permissions. The following example demonstrates how to prevent merging of the Topics permission.

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

Configure API-specific Ad Services

Similar to the PPAPI access permissions, each API has a corresponding entry in the ad services configuration. This configuration gives you fine-grained control access to resources managed by the APIs in your app or embedded SDK.

Note: Configuring specific Ad Services is optional, and only needed when an app developer wants to change or restrict access to an API, as all access is granted by default.

In your manifest, specify an adservicesConfig property as shown in the following example:

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

      ...
</application>

Specify the ad services XML resource referenced in the manifest, such as res/xml/ad_services_config.xml. For each privacy-preserving API applicable to your app (or embedded SDK), set the allowAllToAccess attribute to true to grant access to any callers.

Alternatively, you can use the allowAdPartnersToAccess attribute to grant fine-grained API access for each ad tech. You'll need to provide a list of developer enrollment account IDs obtained through enrollment. If the allowAllToAccess attribute is set to true, this attribute takes precedence over any enrollment account IDs specified in the allowAdPartnersToAccess attribute.

Note: To access the Privacy Sandbox APIs in the latest AdServices SDK Extension release and in the Developer Preview release, you need to complete the enrollment process.

Ad tech platforms should also make sure that their app clients properly grant access to the required privacy-preserving APIs in the ad services configuration.

Note: Because of a known bug, you should set allowAllToAccess to true when testing locally.

The following example shows how to specify broad access to allow any enrollment account ID access to all privacy-preserving APIs:

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

The following example shows how to specify fine-grained access to each privacy-preserving API for specific enrollment account IDs:

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

Note: If enrollment is disabled for the Topics API or Protected Audience API using adb commands, the app is able to access related APIs regardless of access controls specified in ad-services-config.

Declare Jetpack library dependencies

Use the ads-adservices Jetpack library 1.0.0-beta01 or higher to integrate with Privacy Sandbox's privacy-preserving APIs. You can use this library to abstract your app from platform-level details and simplify integration with privacy-preserving APIs.

1. Add a Maven repository to your project.
2. Declare ads-adservices Jetpack library dependencies in the build.gradle file for your app or module.
3. Use APIs from the androidx.privacysandbox.ads.adservices.* packages.
4. The ads-adservices Jetpack library provides built-in Kotlin coroutine support. You may need to incorporate the appropriate lifecycle-aware dependencies suitable for your project to manage coroutine scopes.

Check the availability of the Ad Services Extensions version

If you're using the ads-services Jetpack library to integrate with privacy-preserving APIs, the library checks for the availability of the requested APIs in the obtain() function. The function returns null if the requested API is not available on the device. The following example illustrates how to initialize TopicsManager for the Topics API. It works similarly for accessing other privacy-preserving APIs.

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);

If you're using the AdServices APIs in the Extension SDK directly, check the AdServices Extensions version that includes the AdServices APIs you want to use. In the API reference, you can identify the version that a particular AdServices API is introduced in. For example, the API reference for the TopicsManager class indicates that it is "Added in Ad Services Extensions 4". Use the following conditional checks to validate SDK extensions that contain AdServices APIs.

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.
...
}

Foreground access limitation

To provide transparency, access to the SDK Runtime and privacy-preserving APIs is limited to apps with a visible Activity, or with a RunningAppProcessInfo of IMPORTANCE_FOREGROUND.