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>
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.
- Add a Maven repository to your project.
- Declare ads-adservices Jetpack library dependencies in the
build.gradle
file for your app or module. - Use APIs from the
androidx.privacysandbox.ads.adservices.*
packages. - 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
.