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

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

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

См. также

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