Руководство разработчика API тем

Предварительная

Читая документацию Privacy Sandbox для Android, используйте кнопку Developer Preview или Beta , чтобы выбрать версию программы, с которой вы работаете, поскольку инструкции могут отличаться.

Обеспечить обратную связь

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

Настраивать

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

Кроме того, вы должны включить доступ к API тем (отключено по умолчанию) с помощью этих команд adb.

adb shell device_config put adservices ppapi_app_signature_allow_list \"*\"

adb shell setprop debug.adservices.disable_topics_enrollment_check true

Основная функциональность 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 .

Ограничения

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

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

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

{% дословно %} {% дословно %}