Настройка AdServices для Android

Следуйте инструкциям ниже, чтобы объявить разрешения для API и настроить доступ SDK к ресурсам, управляемым целевым API.

Примечание. Существует новая библиотека Jetpack , которая обеспечивает интеграцию с API-интерфейсами Privacy Sandbox, сохраняющими конфиденциальность ( темы , защищенная аудитория и отчеты по атрибуции) . Вы можете использовать эту библиотеку в качестве полной замены API-интерфейсов Privacy Sandbox, представленных в Extension SDK .

Объявить разрешения, специфичные для API AdServices

Для доступа к каждому PPAPI требуется normal разрешение Ad Services. В своем манифесте объявите соответствующие разрешения на доступ, соответствующие API, необходимым в вашем приложении или SDK.

API отчетов по атрибуции:

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

API отчетов об атрибуции (с отчетами об отладке):

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

API защищенной аудитории/индивидуальной аудитории:

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

API тем:

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

При желании, чтобы получать отчеты об отладке с помощью API отчетов об атрибуции, включите разрешение AD_ID:

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

Если ваш проект зависит от модулей или SDK, они могут уже объявить необходимые разрешения для рекламных служб в своих файлах манифеста. По умолчанию сборка Gradle объединяет все файлы манифеста в один файл манифеста, который упаковывается в ваше приложение. Используйте представление «Объединенный манифест» , чтобы убедиться, что используются правильные разрешения.

Если вам необходимо предотвратить объединение каких-либо разрешений в ваше приложение с помощью зависимостей, таких как SDK, включите маркер узла remove для конкретных разрешений. В следующем примере показано, как предотвратить объединение разрешений «Темы».

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

Настройка рекламных служб для конкретного API

Подобно разрешениям доступа PPAPI, каждый API имеет соответствующую запись в конфигурации рекламных сервисов. Эта конфигурация дает вам детальный контроль доступа к ресурсам, управляемым 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 . Для каждого API, обеспечивающего конфиденциальность, применимого к вашему приложению (или встроенному SDK), установите для allowAllToAccess значение true , чтобы предоставить доступ всем вызывающим объектам.

Альтернативно вы можете использовать allowAdPartnersToAccess , чтобы предоставить детальный доступ к API для каждой рекламной технологии. Вам потребуется предоставить список идентификаторов учетных записей регистрации разработчиков, полученных в результате регистрации . Если allowAllToAccess присвоено значение true , этот атрибут имеет приоритет над любыми идентификаторами учетных записей регистрации, указанными в allowAdPartnersToAccess .

Примечание. Чтобы получить доступ к API Privacy Sandbox в последней версии расширения AdServices SDK Extension и в версии Developer Preview, вам необходимо завершить процесс регистрации .

Платформы рекламных технологий также должны убедиться, что их клиенты приложений должным образом предоставляют доступ к необходимым API-интерфейсам, обеспечивающим конфиденциальность, в конфигурации рекламных служб.

Примечание. Из-за известной ошибки вам следует установить для allowAllToAccess значение true при локальном тестировании.

В следующем примере показано, как указать широкий доступ, чтобы разрешить любому идентификатору учетной записи регистрации доступ ко всем 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>

В следующем примере показано, как указать детальный доступ к каждому 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>

Примечание. Если регистрация для API тем или API защищенной аудитории отключена с помощью команд adb, приложение сможет получить доступ к связанным API независимо от элементов управления доступом, указанных в ad-services-config .

Объявить зависимости библиотеки Jetpack

Используйте библиотеку рекламных услуг Jetpack 1.0.0-beta01 или более поздней версии для интеграции с API-интерфейсами Privacy Sandbox, сохраняющими конфиденциальность. Вы можете использовать эту библиотеку, чтобы абстрагировать свое приложение от деталей уровня платформы и упростить интеграцию с API-интерфейсами, сохраняющими конфиденциальность.

1. Добавьте репозиторий Maven в свой проект.
2. Объявите зависимости библиотеки Jetpackads-adservices в файле build.gradle для вашего приложения или модуля.
3. Используйте API из пакетов androidx.privacysandbox.ads.adservices.* .
4. Библиотека рекламных услуг Jetpack обеспечивает встроенную поддержку сопрограмм Kotlin. Возможно, вам придется включить соответствующие зависимости с учетом жизненного цикла, подходящие для вашего проекта, для управления областями сопрограмм.

Проверьте доступность версии расширений рекламных служб.

Если вы используете библиотеку рекламных сервисов Jetpack для интеграции с API-интерфейсами, обеспечивающими конфиденциальность, библиотека проверяет доступность запрошенных API-интерфейсов в функции obtain() . Функция возвращает значение null, если запрошенный API недоступен на устройстве. В следующем примере показано, как инициализировать TopicsManager для API тем. Аналогично он работает и для доступа к другим API, обеспечивающим конфиденциальность.

Котлин

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)

Ява

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

Если вы используете API-интерфейсы AdServices непосредственно в SDK расширений, проверьте версию расширений AdServices, которая включает API-интерфейсы AdServices, которые вы хотите использовать. В справочнике API вы можете определить версию, в которой представлен конкретный API AdServices. Например, в справочнике API для класса TopicsManager указано, что он «Добавлен в расширениях рекламных служб 4». Используйте следующие условные проверки для проверки расширений SDK, содержащих API AdServices.

Котлин

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

Ява

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-интерфейсам, обеспечивающим конфиденциальность, ограничен приложениями с видимым действием или с RunningAppProcessInfo со значением IMPORTANCE_FOREGROUND .