Реализация API тем на Android

Настраивать

Чтобы реализовать API Topics, вам необходимо сначала настроить среду разработки. чтобы выполнить следующие шаги настройки:

  1. Используйте последнюю версию Android Privacy Sandbox SDK , чтобы получить самую актуальную версию API, обеспечивающих конфиденциальность.

  2. Добавьте в свой манифест следующее:

    • Разрешение: включите разрешение ACCESS_ADSERVICES_TOPICS , чтобы разрешить вашему приложению доступ к API тем:

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

    • Конфигурация рекламных служб: укажите файл конфигурации рекламных служб в элементе <application> вашего манифеста.

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

      Укажите XML-ресурс рекламных служб, указанный в манифесте, например res/xml/ad_services_config.xml . Используйте allowAllToAccess , чтобы предоставить доступ ко всем SDK, или allowSdksToAccess , чтобы предоставить доступ к отдельным SDK. Узнайте больше о разрешениях для рекламных служб и управлении доступом к SDK .

      <ad-services-config>
    <topics allowAllToAccess="true"/>
</ad-services-config>

  3. Зарегистрируйте свою рекламную технологию в Privacy Sandbox, чтобы вызывать API Topics в вашем SDK. Для локального тестирования вы можете отключить проверку регистрации в темах с помощью следующих команд:

    adb shell setprop debug.adservices.disable_topics_enrollment_check true

  4. Включите доступ к API тем. По умолчанию API тем отключен. Вам необходимо включить его с помощью команд ADB:

    adb shell device_config put adservices ppapi_app_signature_allow_list \"\*\"
    adb shell setprop debug.adservices.disable_topics_enrollment_check true

  5. Начните реализацию с создания нашей версии примера приложения на Java или Kotlin , чтобы ознакомиться с тем, как получать темы на устройстве.

Запросить набор тем

Основная функциональность Topics API находится в методе getTopics() внутри объекта TopicsManager , как показано в этом примере:

Котлин Ява 
fun getTopics(
        getTopicsRequest: GetTopicsRequest,
        executor: Executor,
        callback: OutcomeReceiver<GetTopicsResponse, Exception>
    ) { }

public void getTopics (@NonNull GetTopicsRequest getTopicsRequest,
    @NonNull Executor executor,
    @NonNull OutcomeReceiver<GetTopicsResponse, Exception> callback)

Чтобы использовать этот метод, инициализируйте объект TopicsManager и параметры, необходимые для получения данных тем. GetTopicsRequest передает необходимую информацию для получения данных API Topics, включая флаг, указывающий, будет ли вызывающий объект действовать в качестве наблюдателя или нет. Если вызов getTopics не действует в качестве наблюдателя, он возвращает тему из предыдущей эпохи, но не влияет на данные тем для следующей. Обратный вызов OutcomeReceiver обрабатывает результат асинхронно. Например:

Котлин Ява 
private fun topicGetter() {
    val mContext = baseContext
    val mTopicsManager = mContext.getSystemService(TopicsManager::class.java)
    val mExecutor: Executor = Executors.newCachedThreadPool()
    val shouldRecordObservation = false
    val mTopicsRequestBuilder: GetTopicsRequest.Builder = GetTopicsRequest.Builder()
    mTopicsRequestBuilder.setAdsSdkName(baseContext.packageName)
    mTopicsRequestBuilder.setShouldRecordObservation(shouldRecordObservation)
    mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor,
        mCallback as OutcomeReceiver<GetTopicsResponse, Exception>)
}
private var mCallback: OutcomeReceiver<GetTopicsResponse, java.lang.Exception> =
object : OutcomeReceiver<GetTopicsResponse, java.lang.Exception> {
    override fun onResult(result: GetTopicsResponse) {
        // handle successful result
        val topicsResult = result.topics
        for (i in topicsResult.indices) {
            Log.i("Topic", topicsResult[i].getTopicId().toString())
        }
        if (topicsResult.size == 0) {
            Log.i("Topic", "Returned Empty")
        }
    }
    override fun onError(error: java.lang.Exception) {
        // handle error
        Log.i("Topic", "Error, did not return successfully")
    }
}

public void TopicGetter() {
    @NonNull Context mContext = getBaseContext();
    TopicsManager mTopicsManager = mContext.getSystemService(TopicsManager.class);
    Executor mExecutor = Executors.newCachedThreadPool();
    boolean shouldRecordObservation = false;
    GetTopicsRequest.Builder mTopicsRequestBuilder = new GetTopicsRequest.Builder();
    mTopicsRequestBuilder.setAdsSdkName(getBaseContext().getPackageName());
    mTopicsRequestBuilder.setShouldRecordObservation(shouldRecordObservation);
    mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor, mCallback);
}
OutcomeReceiver mCallback = new OutcomeReceiver<GetTopicsResponse, Exception>() {
    @Override
    public void onResult(@NonNull GetTopicsResponse result) {
        //Handle Successful Result
        List<Topic> topicsResult = result.getTopics();
        for (int i = 0; i < topicsResult.size(); i++) {
            Log.i("Topic", topicsResult.get(i).getTopicId().toString());
        }
        if (topicsResult.size() == 0) {
            Log.i("Topic", "Returned Empty");
        }
    }
    @Override
    public void onError(@NonNull Exception error) {
        // Handle error
        Log.i("Topic", "Experienced an error, and did not return successfully");
    }
};

Как только ваша настройка будет готова, вы можете выполнить вызов для получения GetTopicsResponse в результате метода getTopics() :

Котлин Ява 
mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor,
        mCallback as OutcomeReceiver<GetTopicsResponse, java.lang.Exception>)

mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor, mCallback);

Этот вызов предоставит список объектов Topics, содержащих значения идентификаторов, которые соответствуют темам в таксономии с открытым исходным кодом, которые имеют отношение к пользователю, или соответствующей ошибке. Темы будут похожи на этот пример: 

/Internet & Telecom/Text & Instant Messaging

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

Тестирование

API тем предоставляет актуальные и свежие темы на основе использования приложения. Эта ранняя версия дает предварительный просмотр поведения API, и мы улучшим качество тем в будущих выпусках.

Чтобы получить максимальную отдачу от опыта, мы рекомендуем среду тестирования с несколькими приложениями, в которой вы вызываете getTopics() чтобы увидеть, как выбираются темы. Репозиторий API среды выполнения и сохранения конфиденциальности SDK на GitHub содержит набор отдельных проектов Android Studio, которые помогут вам начать работу, включая примеры, демонстрирующие, как инициализировать и вызывать API тем.

Подсчет тем происходит в конце эпохи. По умолчанию каждая эпоха длится 7 дней, но вы можете изменить этот интервал, чтобы получить результат. Эта команда оболочки Android Debug Bridge сокращает продолжительность эпохи до 5 минут: 

adb shell device_config put adservices topics_epoch_job_period_ms 300000

Вы можете подтвердить значение topics_epoch_job_period_ms с помощью get : 

adb shell device_config get adservices topics_epoch_job_period_ms

Чтобы вручную запустить вычисление эпохи, выполните следующую команду: 

adb shell cmd jobscheduler run -f com.google.android.adservices.api 2

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

Детали шифрования

С введением шифрования вызовы GetTopics() теперь будут генерировать ответ со списком объектов EncryptedTopic . Расшифровка этих результатов приведет к созданию объекта с тем же форматом JSON, что и у предыдущего объекта Topic .

API Topics поддерживает однократную реализацию HPKE (гибридное шифрование с открытым ключом). Мы ожидаем, что зарегистрированный абонент разместит 32-битный открытый ключ в конечной точке URL-адреса общедоступного шифрования, указанной во время регистрации. Ожидается, что эти ключи будут закодированы Base64.

Объект EncryptedTopic имеет 3 поля. Список возвращаемых тем можно получить, используя соответствующий закрытый ключ для открытого ключа.

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

Ограничения

Список текущих возможностей API Topics см. в примечаниях к выпуску .

Сообщайте об ошибках и проблемах

Ваш отзыв – важная часть Privacy Sandbox на Android. Сообщайте нам о любых обнаруженных проблемах или идеях по улучшению Privacy Sandbox на Android.

Next steps

Learn how users and developers can manage and customize the Topics API to suit user's preferences and needs.
Understand how Topics works on Android and lear about the core steps of the API flow.

See also

Check out our resources to better understand the Topics API on Android.