Configure AdServices

As you read through the Privacy Sandbox on Android documentation, use the Developer Preview or Beta button to select the program version that you're working with, as instructions may vary.


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

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

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.

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>