Реализация 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.

Следующие шаги

Узнайте, как пользователи и разработчики могут управлять API Topics и настраивать его в соответствии с предпочтениями и потребностями пользователей.
Узнайте, как Topics работает на Android, и узнайте об основных этапах работы API.

См. также

Ознакомьтесь с нашими ресурсами, чтобы лучше понять API Topics на Android.