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

Настраивать

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

  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-ресурс Ad Services, на который ссылается манифест, например, res/xml/ad_services_config.xml . Используйте атрибут allowAllToAccess для предоставления доступа ко всем SDK или атрибут allowSdksToAccess для предоставления доступа к отдельным SDK. Подробнее о разрешениях Ad Services и контроле доступа к SDK см . здесь.

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

  3. Зарегистрируйте свою рекламную технологию в «Песочнице конфиденциальности», чтобы вызывать API тем из вашего 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- версии демонстрационного приложения, чтобы ознакомиться с темами, которые можно получить на устройстве.

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

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

Котлин 

fun getTopics(
        getTopicsRequest: GetTopicsRequest,
        executor: Executor,
        callback: OutcomeReceiver<GetTopicsResponse, Exception>
    ) { }

Java 

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")
    }
}

Java 

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

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

Котлин 

mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor,
        mCallback as OutcomeReceiver<GetTopicsResponse, java.lang.Exception>)

Java 

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

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

/Internet & Telecom/Text & Instant Messaging

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

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

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

Для получения максимальной пользы мы рекомендуем использовать тестовую среду с несколькими приложениями, где вы можете вызвать метод getTopics() чтобы увидеть, как выбираются темы. В репозитории SDK Runtime and Privacy Preserving APIs на GitHub содержится набор отдельных проектов Android Studio, которые помогут вам начать работу, включая примеры, демонстрирующие инициализацию и вызов API Topics.

Расчет тем происходит в конце эпохи. По умолчанию каждая эпоха длится 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

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

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

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

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

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

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

Ограничения

Список разрабатываемых функций API для тем можно найти в примечаниях к выпуску .

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

Ваши отзывы играют решающую роль в работе 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.

См. также

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