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

При изучении документации по Privacy Sandbox на Android используйте кнопку «Предварительная версия для разработчиков» или «Бета-версия» , чтобы выбрать версию программы, с которой вы работаете, поскольку инструкции могут отличаться.

API защищенной аудитории на Android (ранее известный как FLEDGE) включает в себя API пользовательской аудитории и API выбора рекламы. Платформы рекламных технологий и рекламодатели могут использовать эти API для показа персонализированной рекламы на основе предыдущего взаимодействия с приложением, что ограничивает обмен идентификаторами между приложениями и передачу информации о взаимодействии пользователя с приложением третьим сторонам.

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

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

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

В этом руководстве описано, как работать с API защищенной аудитории на Android для выполнения следующих действий:

1. Управление пользовательскими аудиториями
2. Настройка и запуск выбора рекламы на устройстве.
3. Сообщить о показах рекламы

Прежде чем начать

Прежде чем начать, выполните следующие действия:

1. Настройте среду разработки для «Песочницы конфиденциальности» на Android.
2. Либо установите образ системы на поддерживаемое устройство , либо настройте эмулятор , который поддерживает Privacy Sandbox на Android.

3. В терминале включите доступ к API защищенной аудитории (по умолчанию отключен) с помощью следующей команды adb.

     adb shell device_config put adservices ppapi_app_allow_list \"*\"
   

4. В терминале включите отправку сообщений через маяк с помощью следующих команд adb.

    adb shell device_config put adservices fledge_beacon_reporting_metrics_enabled true
    adb shell device_config put adservices fledge_register_ad_beacon_enabled true
   

5. Добавьте в манифест вашего приложения разрешение ACCESS_ADSERVICES_CUSTOM_AUDIENCE :

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

6. Укажите конфигурацию рекламных сервисов в элементе <application> вашего манифеста:

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

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

     <ad-services-config>
       <custom-audiences allowAllToAccess="true" />
     </ad-services-config>
   

8. По умолчанию API выбора объявлений устанавливает ограничения на максимальный объем памяти, который может выделить скрипт аукциона или отчета о показах. Функция ограничения памяти требует WebView версии 105.0.5195.58 или выше. Платформа проверяет версию, и вызовы API selectAds и reportImpression завершаются с ошибкой, если это условие не выполняется. Существует два варианта настройки:

   • Вариант 1: Выполните следующую команду adb, чтобы отключить эту проверку:

     adb device_config put fledge_js_isolate_enforce_max_heap_size false
     

   • Вариант 2: Установите бета-версию WebView из магазина Google Play. Версия должна быть не ниже указанной ранее.

Присоединиться к пользовательской аудитории

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

1. Инициализируйте объект CustomAudienceManager .
2. Создайте объект CustomAudience , указав ключевые параметры, такие как пакет услуг покупателя и соответствующее имя. Затем инициализируйте объект JoinCustomAudienceRequest объектом CustomAudience .
3. Вызовите асинхронный joinCustomAudience() с объектом JoinCustomAudienceRequest и соответствующими объектами Executor и OutcomeReceiver .

val customAudienceManager: CustomAudienceManager =
    context.getSystemService(CustomAudienceManager::class.java)

// Initialize a custom audience.
val audience = CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    ...
    .build()

// Initialize a custom audience request.
val joinCustomAudienceRequest: JoinCustomAudienceRequest =
    JoinCustomAudienceRequest.Builder().setCustomAudience(audience).build()

// Request to join a custom audience.
customAudienceManager.joinCustomAudience(joinCustomAudienceRequest,
    executor,
    outcomeReceiver)

CustomAudienceManager customAudienceManager =
    context.getSystemService(CustomAudienceManager.class);

// Initialize a custom audience.
CustomAudience audience = new CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    ...
    .build();

// Initialize a custom audience request.
JoinCustomAudienceRequest joinCustomAudienceRequest =
    new JoinCustomAudienceRequest.Builder().setCustomAudience(audience).build();

// Request to join a custom audience.
customAudienceManager.joinCustomAudience(joinCustomAudienceRequest,
    executor,
    outcomeReceiver);

Сочетание следующих параметров однозначно идентифицирует каждый объект CustomAudience на устройстве:

• owner : Имя пакета приложения-владельца. По умолчанию устанавливается имя пакета вызывающего приложения.
• buyer : Идентификатор рекламной сети покупателя, которая управляет показом рекламы для этой пользовательской аудитории.
• name : Произвольное имя или идентификатор для пользовательской аудитории.

Многократный вызов метода joinCustomAudience() с разными экземплярами CustomAudience обновляет существующий CustomAudience , добавляя к нему совпадающие параметры owner, buyer и name . Для обеспечения конфиденциальности результат работы API не различает операции «создание» и «обновление».

Кроме того, необходимо создать объект CustomAudience со следующими обязательными параметрами:

• URL для ежедневного обновления : HTTPS-адрес, который ежедневно запрашивается в фоновом режиме для обновления сигналов ставок пользователей пользовательской аудитории, достоверных данных о ставках, а также URL-адресов отображения и метаданных для объявлений.
• URL-адрес логики назначения ставок : HTTPS-адрес, запрашиваемый во время выбора объявления для получения логики назначения ставок покупателя в JavaScript. См. необходимые сигнатуры функций в этом JavaScript-коде.
• Идентификаторы рендеринга рекламы : произвольный идентификатор, устанавливаемый рекламной платформой покупателя. Это оптимизация для генерации полезной нагрузки для B&A .

В качестве необязательных параметров для объекта CustomAudience могут выступать следующие:

• Время активации : Пользовательская аудитория может участвовать в выборе рекламы и ежедневных обновлениях только после времени активации. Это может быть полезно, например, для привлечения пользователей, которые перестали пользоваться приложением.
• Срок действия : Будущий момент времени, по истечении которого пользовательская аудитория будет удалена с устройства.
• Сигналы для ставок пользователя : строка JSON, содержащая сигналы пользователя, такие как предпочитаемая языковая версия, которые JavaScript-код логики ставок покупателя использует для генерации ставок в процессе выбора рекламы. Этот формат помогает платформам рекламных технологий повторно использовать код на разных платформах и упрощает его использование в функциях JavaScript.
• Достоверные данные для торгов : URL-адрес HTTPS и список строк, используемых в процессе выбора объявлений для получения сигналов торгов от доверенного сервиса «ключ/значение».
• Ads : Список объектов AdData , соответствующих объявлениям, участвующим в выборе рекламы. Каждый объект AdData состоит из:
  • URL для отображения : HTTPS-адрес, используемый для отображения конечного рекламного объявления.
  • Метаданные : JSON-объект, сериализованный в строку, содержащий информацию, используемую логикой формирования ставок покупателями в процессе выбора объявления.
  • Фильтры рекламы : Класс, содержащий всю необходимую информацию для фильтрации рекламы при установке приложений и ограничения частоты показа рекламы во время её выбора.

Вот пример создания экземпляра объекта CustomAudience :

// Minimal initialization of a CustomAudience object
val customAudience: CustomAudience = CustomAudience.Builder()
    .setBuyer(AdTechIdentifier.fromString("my.buyer.domain.name"))
    .setName("example-custom-audience-name")
    .setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
    .setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
    .build()

// Minimal initialization of a CustomAudience object
CustomAudience customAudience = CustomAudience.Builder()
    .setBuyer(AdTechIdentifier.fromString("my.buyer.domain.name"))
    .setName("example-custom-audience-name")
    .setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
    .setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
    .build();

Обрабатывайте результаты функции joinCustomAudience()

Асинхронный метод joinCustomAudience() использует объект OutcomeReceiver для передачи результата вызова API.

• Функция обратного вызова onResult() означает, что пользовательская аудитория успешно создана или обновлена.
• Функция обратного вызова onError() указывает на два возможных условия.
  • Если объект JoinCustomAudienceRequest инициализирован недопустимыми аргументами, в сообщении AdServicesException будет указано исключение IllegalArgumentException как причина.
  • Все остальные ошибки сопровождаются исключением AdServicesException с указанием причины IllegalStateException .

Вот пример обработки результата вызова joinCustomAudience() :

var callback: OutcomeReceiver<Void, AdServicesException> =
    object : OutcomeReceiver<Void, AdServicesException> {
    override fun onResult(result: Void) {
        Log.i("CustomAudience", "Completed joinCustomAudience")
    }

    override fun onError(error: AdServicesException) {
        // Handle error
        Log.e("CustomAudience", "Error executing joinCustomAudience", error)
    }
};

OutcomeReceiver callback = new OutcomeReceiver<Void, AdServicesException>() {
    @Override
    public void onResult(@NonNull Void result) {
        Log.i("CustomAudience", "Completed joinCustomAudience");
    }

    @Override
    public void onError(@NonNull AdServicesException error) {
        // Handle error
        Log.e("CustomAudience", "Error executing joinCustomAudience", error);
    }
};

Укажите пользовательскую аудиторию

Если пользователь больше не соответствует бизнес-критериям для заданной пользовательской аудитории, приложение или SDK могут вызвать метод leaveCustomAudience() для удаления пользовательской аудитории с устройства. Чтобы удалить CustomAudience на основе ее уникальных параметров, выполните следующие действия:

1. Инициализируйте объект CustomAudienceManager .
2. Инициализируйте объект LeaveCustomAudienceRequest указав buyer и name пользовательской аудитории. Для получения дополнительной информации об этих полях ввода, прочитайте раздел « Присоединение к пользовательской аудитории ».
3. Вызовите асинхронный метод leaveCustomAudience() с объектом LeaveCustomAudienceRequest и соответствующими объектами Executor и OutcomeReceiver .

val customAudienceManager: CustomAudienceManager =
    context.getSystemService(CustomAudienceManager::class.java)

// Initialize a LeaveCustomAudienceRequest
val leaveCustomAudienceRequest: LeaveCustomAudienceRequest =
    LeaveCustomAudienceRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .build()

// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
    leaveCustomAudienceRequest,
    executor,
    outcomeReceiver)

CustomAudienceManager customAudienceManager =
    context.getSystemService(CustomAudienceManager.class);

// Initialize a LeaveCustomAudienceRequest
LeaveCustomAudienceRequest leaveCustomAudienceRequest =
    new LeaveCustomAudienceRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .build();

// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
    leaveCustomAudienceRequest,
    executor,
    outcomeReceiver);

Аналогично вызову joinCustomAudience() , OutcomeReceiver сигнализирует об окончании вызова API. Для защиты конфиденциальности результат ошибки не различает внутренние ошибки и недопустимые аргументы. Функция обратного вызова onResult() вызывается после завершения вызова API, независимо от того, было ли успешно удалено соответствующее пользовательское окружение.

Запустить выбор рекламы

Чтобы использовать API защищенной аудитории для выбора объявлений, вызовите метод selectAds() :

1. Инициализируйте объект AdSelectionManager .
2. Создайте объект AdSelectionConfig .
3. Вызовите асинхронный метод selectAds() с объектом AdSelectionConfig и соответствующими объектами Executor и OutcomeReceiver .

val adSelectionManager: AdSelectionManager =
  context.getSystemService(AdSelectionManager::class.java)

// Initialize AdSelectionConfig
val adSelectionConfig: AdSelectionConfig =
  AdSelectionConfig.Builder().setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .setBuyerContextualAds(
      Collections.singletonMap(
        contextualAds.getBuyer(), contextualAds
      )
    ).build()

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
  adSelectionConfig, executor, outcomeReceiver
)

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize AdSelectionConfig
AdSelectionConfig adSelectionConfig =
  new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .setBuyerContextualAds(
      Collections.singletonMap(contextualAds.getBuyer(), contextualAds)
    )
    .build();

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(adSelectionConfig, executor, outcomeReceiver);

Метод selectAds() требует ввода параметра AdSelectionConfig , в котором необходимо указать следующие обязательные параметры:

• Продавец : Идентификатор рекламной сети продавца, инициирующей выбор объявления.
• URL-адрес логики принятия решений : HTTPS-адрес, используемый для получения JavaScript-логики рекламной сети продавца.
  • URL-адрес HTTPS : используется для получения логики JavaScript рекламной сети продавца. См. необходимые сигнатуры функций .
  • Предварительно сформированный URI : соответствует формату выбора рекламы FLEDGE. В случае передачи неподдерживаемого или некорректного предварительно сформированного URI будет выброшено исключение IllegalArgumentException .
• Покупатели пользовательских аудиторий : полный список идентификаторов рекламных сетей покупателей, которым продавец разрешил участвовать в процессе выбора рекламы. Эти идентификаторы покупателей соответствуют методу CustomAudience.getBuyer() для участвующих пользовательских аудиторий.

Для более точной настройки выбора рекламы можно дополнительно указать следующие параметры:

• Сигналы выбора объявления : JSON-объект, сериализованный в строку, содержащий сигналы, которые будут использоваться логикой торгов покупателя (JavaScript), получаемой из CustomAudience.getBiddingLogicUrl() .
• Сигналы продавца : JSON-объект, сериализованный в виде строки, содержащий сигналы, обрабатываемые логикой принятия решений продавца на основе JavaScript, полученной из AdSelectionConfig.getDecisionLogicUrl() .
• Сигналы для каждого покупателя : Карта объектов JSON, сериализованных в виде строк, содержащих сигналы, которые должны обрабатываться JavaScript-кодом логики торгов конкретных покупателей, получаемым из CustomAudience.getBiddingLogicUrl() , и которые идентифицируются по полям покупателей участвующих пользовательских аудиторий.
• Контекстная реклама: набор рекламных объявлений, которые собираются непосредственно от покупателей во время аукциона, проводимого вне рамок аукциона защищенной аудитории.

После выбора объявления результаты, ставки и сигналы сохраняются внутри системы для формирования отчетов. Функция обратного вызова OutcomeReceiver.onResult() возвращает объект AdSelectionOutcome , содержащий:

• URL-адрес для отображения выигрышного объявления, полученный с помощью AdData.getRenderUrl() .
• Уникальный для пользователя устройства идентификатор выбранной рекламы. Этот идентификатор используется для формирования отчетов о показах рекламы.

Если выбор рекламы не может быть успешно завершен по таким причинам, как недопустимые аргументы, тайм-ауты или чрезмерное потребление ресурсов, функция обратного вызова OutcomeReceiver.onError() генерирует исключение AdServicesException со следующим поведением:

• Если выбор рекламного объявления инициируется с недопустимыми аргументами, AdServicesException указывается IllegalArgumentException как причина.
• Все остальные ошибки сопровождаются исключением AdServicesException с указанием причины IllegalStateException .

Контекстная реклама

В рамках защищенной аудитории можно интегрировать контекстную рекламу в защищенный аукцион. Контекстная реклама должна быть выбрана на сервере рекламных технологий и возвращена на устройство вне API защищенной аудитории. Затем контекстную рекламу можно включить в аукцион с помощью AdSelectionConfig после чего она будет функционировать так же, как и реклама на устройстве, включая возможность фильтрации минус-слов. После завершения аукциона в защищенной аудитории необходимо вызвать reportImpression() . Это вызовет reportWin() для выигрышной контекстной рекламы, по тому же принципу, что и отчеты о показах , чтобы получить выигрышную рекламу на устройстве. Каждая контекстная реклама должна содержать покупателя, ставку, ссылку на логику отчетности, URL-адрес рендеринга и метаданные объявления.

Для размещения контекстной рекламы в приложении целевому приложению необходимо создать объект ContextualAds :

val contextualAds: ContextualAds =
  Builder().setBuyer(AdTechIdentifier.fromString(mBiddingLogicUri.getHost()))
    //Pass in your valid app install ads
    .setDecisionLogicUri(mContextualLogicUri)
    .setAdsWithBid(appInstallAd)
    .build()

ContextualAds contextualAds = new ContextualAds.Builder()
  .setBuyer(AdTechIdentifier.fromString(mBiddingLogicUri.getHost()))
  .setDecisionLogicUri(mContextualLogicUri)
  //Pass in your valid app install ads
  .setAdsWithBid(appInstallAd)
  .build();

Полученный объект ContextualAds затем можно передать при создании объекта AdSelectionConfig :

// Create a new ad
val noFilterAd: AdData = Builder()
  .setMetadata(JSONObject().toString())
  .setRenderUri(Uri.parse(baseUri + NO_FILTER_RENDER_SUFFIX))
  .build()
val noFilterAdWithBid = AdWithBid(noFilterAd, NO_FILTER_BID)
contextualAds.getAdsWithBid().add(noFilterAdWithBid)

// Create a new ad
AdData noFilterAd = new AdData.Builder()
  .setMetadata(new JSONObject().toString())
  .setRenderUri(Uri.parse(baseUri + NO_FILTER_RENDER_SUFFIX))
  .build();
AdWithBid noFilterAdWithBid = new AdWithBid(noFilterAd, NO_FILTER_BID);
contextualAds.getAdsWithBid().add(noFilterAdWithBid);

Фильтрация рекламы при установке приложений

Фильтрация рекламы при установке приложений помогает отфильтровывать рекламу, рекламируемую при установке приложений, которые уже установлены на устройстве.

Первый шаг в этом процессе — определить, какие рекламодатели имеют возможность фильтровать установленные пакеты. Это необходимо сделать в приложении, на которое вы хотите нацелить рекламу.

//Create a request for setting the app install advertisers
val adtech = AdTechIdentifier.fromString("your.enrolled.uri")
val adtechSet = setOf(adtech)
val request = SetAppInstallAdvertisersRequest(adtechSet)

//Set the app install advertisers in the ad selection manager
mAdSelectionManager.setAppInstallAdvertisers(
  request,
  mExecutor,
  object : OutcomeReceiver<Any?, Exception?>() {
    fun onResult(@NonNull ignoredResult: Any?) {
      Log.v("[your tag]", "Updated app install advertisers")
    }

    fun onError(@NonNull error: Exception?) {
      Log.e("[your tag]", "Failed to update app install advertisers", error)
    }
  })

//Create a request for setting the app install advertisers
AdTechIdentifier adtech = AdTechIdentifier.fromString("your.enrolled.uri");
Set<AdTechIdentifier> adtechSet = Collections.singleton(adtech);
SetAppInstallAdvertisersRequest request = new SetAppInstallAdvertisersRequest(adtechSet);

//Set the app install advertisers in the ad selection manager
mAdSelectionManager.setAppInstallAdvertisers(
  request,
  mExecutor,
  new OutcomeReceiver<Object, Exception>() {
    @Override
    public void onResult(@NonNull Object ignoredResult) {
      Log.v("[your tag]", "Updated app install advertisers");
    }

    @Override
    public void onError(@NonNull Exception error) {
      Log.e("[your tag]", "Failed to update app install advertisers", error);
    }
  });

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

Следующий шаг — настройка фильтрации рекламы внутри приложения издателя. Сторона, показывающая рекламу в приложении издателя (скорее всего, это SDK для поставщиков рекламы), должна инициализировать свой объект AdFilters информацией о том, какие объявления, связанные с приложениями, они хотят отфильтровать:

// Instantiate AdFilters object with package names.
val filters: AdFilters = Builder().setAppInstallFilters(
    Builder().setPackageNames(setOf("example.target.app")).build()
  ).build()

// Instantiate AdFilters object with package names.
AdFilters filters = new AdFilters.Builder()
.setAppInstallFilters(
  new AppInstallFilters.Builder()
  .setPackageNames(Collections.singleton("example.target.app"))
  .build())
.build();

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

AdFilters также можно передать при создании нового объекта AdData :

// Instantiate an AdData object with the AdFilters created in the
// previous example.
val appInstallAd: AdData =
  Builder().setMetadata("{ ... }") // Valid JSON string
    .setRenderUri(Uri.parse("www.example-dsp1.com/.../campaign123.html"))
    .setAdFilters(filters).build()

// Instantiate an AdData object with the AdFilters created in the
// previous example.
AdData appInstallAd = new AdData.Builder()
.setMetadata("{ ... }") // Valid JSON string
.setRenderUri(Uri.parse("www.example-dsp1.com/.../campaign123.html"))
    .setAdFilters(filters)
    .build();

Фильтрация частотного ограничения

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

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

• Выигрыш : Событие «Выигрыш» указывает на то, что объявление выиграло аукцион. События «Выигрыш» автоматически обновляются API защищенной аудитории и не могут быть вызваны напрямую разработчиком. Данные о выигрыше видны только объявлениям в рамках заданной пользовательской аудитории.
• Показы : В отличие от reportImpression , вызывающая сторона на устройстве (SSP или MMP) использует updateAdCounterHistogram() для вызова событий показов в выбранной ею точке кода. События показов видны всем объявлениям, принадлежащим данной DSP, и не ограничиваются объявлениями в одной и той же пользовательской аудитории.
• Событие View вызывается устройством-вызывателем (SSP или MMP) в выбранной им точке кода с помощью вызова функции updateAdCounterHistogram() . События View видны всем объявлениям, принадлежащим данной DSP, и не ограничиваются объявлениями в одной и той же пользовательской аудитории.
• Клик : Событие вызывается устройством-вызывателем (SSP или MMP) в выбранной им точке кода с помощью вызова функции updateAdCounterHistogram() . События клика видны всем объявлениям, принадлежащим данной DSP, и не ограничиваются объявлениями в одной и той же пользовательской аудитории.

В приложении издателя SSP или MMP, присутствующий на устройстве, инициирует рекламные события. При вызове функции updateAdCounterHistogram() счетчик фильтра ограничения частоты увеличивается, чтобы будущие аукционы имели актуальную информацию о показе пользователем данной рекламы. Типы рекламных событий не привязаны к соответствующему действию пользователя и представляют собой рекомендации, помогающие разработчикам структурировать свою систему событий. Для увеличения счетчиков рекламы во время события, действующее на устройстве устройство предоставляет идентификатор выбранной рекламы в аукционе, выигравшем аукцион.

Ключи счетчика объявлений — это произвольные 32-битные знаковые целые числа, присваиваемые рекламной платформой покупателя, и они соответствуют заданному набору объявлений, определенному DSP. Поскольку ключи счетчика объявлений ограничены только объявлениями, принадлежащими данной DSP, эти ключи могут быть выбраны без пересечения с гистограммами другой рекламной платформы. Ключи счетчика объявлений используются для увеличения идентификаторов, специфичных для DSP, в объявлениях DSP или в рамках заданной пользовательской аудитории, чтобы отфильтровывать объявления из будущих аукционов.

Ключи счетчика можно использовать для определения приоритетности объявлений, которые с большей вероятностью будут интересны конкретному пользователю, исходя из его взаимодействия с другими объявлениями от той же рекламной платформы. Например, объявление, получившее высокий уровень вовлеченности благодаря выигрышным аукционам, просмотрам и кликам, представляет собой косвенный показатель. Для наглядности: объявление о клюшках для гольфа для левшей может указывать на то, что пользователь не заинтересуется клюшками для правшей. Фильтр ограничения частоты, установленный для ключа счетчика, назначенного для объявлений для левшей, может отфильтровать объявления для клюшек для правшей.

Для использования ограничения частоты аукциона необходимо сначала создать объекты KeyedFrequencyCap :

// Value used when incrementing frequency counter
val adCounterKey = 123

// Frequency cap exceeded after 2 counts
val keyedFrequencyCapForImpression: KeyedFrequencyCap = Builder(
  adCounterKey, 2, Duration.ofSeconds(10)
).build()

// Frequency cap exceeded after 1 counts
val keyedFrequencyCapForImpression: KeyedFrequencyCap = Builder(
  adCounterKey, 1, Duration.ofSeconds(10)
).build()

// Value used when incrementing frequency counter
int adCounterKey = 123;

// Frequency cap exceeded after 2 counts
KeyedFrequencyCap keyedFrequencyCapForImpression =
  new KeyedFrequencyCap.Builder(
    adCounterKey, 2, Duration.ofSeconds(10)
  ).build();

// Frequency Cap exceeded after 1 counts
KeyedFrequencyCap keyedFrequencyCapForClick =
  new KeyedFrequencyCap.Builder(
    adCounterKey, 1, Duration.ofSeconds(10)
  ).build();

После создания объектов KeyedFrequencyCap вы можете передать их в объект AdFilters .

val filters: AdFilters = Builder()
  .setFrequencyCapFilters(
    Builder()
      .setKeyedFrequencyCapsForImpressionEvents(
        ImmutableObject.of(keyedFrequencyCapForImpression)
      )
      .setKeyedFrequencyCapsForClickEvents(
        ImmutableObject.of(keyedFrequencyCapForClick)
      )
  ).build()

AdFilters filters = new AdFilters.Builder()
    .setFrequencyCapFilters(new FrequencyCapFilters.Builder()
        .setKeyedFrequencyCapsForImpressionEvents(
            ImmutableObject.of(keyedFrequencyCapForImpression)
        )
        .setKeyedFrequencyCapsForClickEvents(
            ImmutableObject.of(keyedFrequencyCapForClick)
        )
    ).build();

Если объект AdFilters заполнен фильтрами ограничения частоты показов, его можно передать при создании пользовательской аудитории:

// Initialize a custom audience.
val audience: CustomAudience = Builder()
  .setBuyer(buyer)
  .setName(name)
  .setAds(
    listOf(
      Builder()
        .setRenderUri(renderUri)
        .setMetadata(JSONObject().toString())
        .setAdFilters(filters)
        .setAdCounterKeys(adCounterKeys)
        .build()
    )
  ).build()

// Initialize a custom audience.
CustomAudience audience = new CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    .setAds(Collections.singletonList(new AdData.Builder()
        .setRenderUri(renderUri)
        .setMetadata(new JSONObject().toString())
        .setAdFilters(filters)
        .setAdCounterKeys(adCounterKeys)
        .build()))
    .build();

Когда в пользовательскую аудиторию внедряются фильтры ограничения частоты показов, SSP может инициировать необходимые события клика, просмотра или показа.

val callerAdTech: AdTechIdentifier = mAdSelectionConfig.getSeller()

val request: UpdateAdCounterHistogramRequest = Builder(
  adSelectionId,
  FrequencyCapFilters.AD_EVENT_TYPE_CLICK,  //CLICK, VIEW, or IMPRESSION
  callerAdTech
).build()

AdTechIdentifier callerAdTech = mAdSelectionConfig.getSeller();

UpdateAdCounterHistogramRequest request =
  new UpdateAdCounterHistogramRequest.Builder(
      adSelectionId,
      FrequencyCapFilters.AD_EVENT_TYPE_CLICK, //CLICK, VIEW, or IMPRESSION
      callerAdTech
).build();

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

Контекстная фильтрация рекламы без сетевых вызовов

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

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

Для выбора рекламных объявлений без сетевых запросов:

1. Настройте фильтрацию рекламы.
2. Создавайте контекстную рекламу

3. Создайте объект AdSelectionConfig со следующим содержимым:

   1. Пустой список покупателей
   2. Предварительно сформированный URI для выбора наивысшей ставки
   3. Контекстная реклама
   4. Пустой URI для сигналов оценки. Пустой URI может указывать на то, что вы не хотите использовать получение доверенных сигналов для оценки:

   Uri prebuiltURIScoringUri = Uri.parse("ad-selection-prebuilt://ad-selection/highest-bid-wins/?reportingUrl=your.registered.uri/reporting");
   // Initialize AdSelectionConfig
   AdSelectionConfig adSelectionConfig =
     new AdSelectionConfig.Builder()
       .setSeller(seller)
       .setDecisionLogicUri(prebuiltURIScoringUri)
       .setCustomAudienceBuyers(Collections.emptyList())
       .setAdSelectionSignals(adSelectionSignals)
       .setSellerSignals(sellerSignals)
       .setPerBuyerSignals(perBuyerSignals)
       .setBuyerContextualAds(buyerContextualAds)
       .setTrustedScoringSignalsUri(Uri.EMPTY)
       .build();
   

4. Выполнить выбор рекламы:

   adSelectionManager.selectAds(
       adSelectionConfig,
       executor,
       outcomeReceiver);
   

Запускайте собственные отчеты на JavaScript, используя предварительно созданные URI.

На сегодняшний день платформа Privacy Sandbox предлагает только базовую реализацию JavaScript для создания отчетов с использованием предварительно созданных URI. Если вы хотите запускать собственный JavaScript для создания отчетов, используя при этом предварительно созданные URI для выбора рекламы с низкой задержкой, вы можете переопределить параметр DecisionLogicUri между выбором рекламы и запуском создания отчетов.

1. Выполните шаги для выбора контекстной рекламы с использованием предварительно созданных URI.

2. Перед запуском формирования отчетов создайте копию файла AdSelectionConfig

   adSelectionConfigWithYourReportingJS = adSelectionConfig.cloneToBuilder()
     // Replace <urlToFetchYourReportingJS> with your own URL:
     .setDecisionLogicUri(Uri.parse(<urlToFetchYourReportingJS>))
     .build();
   

3. Запуск системы формирования отчетов о просмотрах

   // adSelectionId is from the result of the previous selectAds run
   ReportImpressionRequest request = new ReportImpressionRequest(
     adSelectionId,
     adSelectionConfigWithYourReportingJS);
   adSelectionManager.reportImpression(
     request,
     executor,
     outcomeReceiver);
   

Проведение каскадной медиации

Для каскадной медиации требуется, чтобы несколько сторонних SDK (3P-сетей) управлялись сетью медиации на основе SDK первого поколения. Каскадная медиация выполняется одинаково независимо от того, проводился ли аукцион на устройстве или запускался на сервисах торгов и аукционов (B&A).

3P-сети

Сторонним сетям необходимо предоставить адаптер, позволяющий сети-посреднику вызывать необходимые методы для проведения аукциона:

• Запустить выбор рекламы
• Отчет о впечатлениях

Вот пример сетевого адаптера для посредничества:

class NetworkAdaptor {
    private val adSelectionManager : AdSelectionManager

    init {
        adSelectionManager = context.getSystemService(AdSelectionManager::class.java)
    }

    fun selectAds() {...}

    fun reportImpressions() {...}
}

class NetworkAdaptor {
    AdSelectionManager adSelectionManager;

    public NetworkAdaptor() {
        AdSelectionManager adSelectionManager =
            context.getSystemService(AdSelectionManager.class);
    }

    public void selectAds() {...}

    public void reportImpressions() {...}
}

Каждый SDK имеет собственные менеджеры и клиенты для выбора рекламы, а также собственную реализацию selectAds и reportImpressions . Поставщики SDK могут обратиться к разделам о том, как запускать выбор рекламы для аукционов на устройствах , или к пояснению B&A для аукционов B&A. Следуйте инструкциям по формированию отчетов по показам рекламы (следуйте инструкциям по формированию отчетов по показам на одном SSP ).

Сеть посредничества

Подобно сетям 3P, для сетей посредничества необходимы реализации функций selectAds и reportImpression . Более подробную информацию можно найти в разделах о том, как осуществлять выбор объявлений и как формировать отчеты о показах объявлений .

Сети медиаторов отвечают за организацию цепочки медиации и включение себя в эту цепочку. В следующем разделе рассматривается, как настроить и осуществить этот процесс.

Восстановить цепочку медиации и минимальные уровни торгов.

Сеть посредничества отвечает за получение контекстной рекламы от первого лица (1P), цепочки посредничества и минимальных ставок сетей третьих лиц (3P). Это может происходить в запросе на получение контекстной рекламы, выполняемом сетью посредничества. Цепочка посредничества определяет, как итерировать по сетям 3P, а минимальные ставки могут передаваться в процесс аукциона в качестве adSelectionSignals .

Размещение в сети в цепочке медиации

SDK для медиации может размещать себя в цепочке медиации на основе своего текущего eCPM ставок рекламы 1P. В API защищенной аудитории ставки рекламы непрозрачны. SDK для медиации должен использовать AdSelectionFromOutcomesConfig , чтобы иметь возможность сравнивать ставку данной рекламы 1P с минимальной ставкой следующей сети 3P в цепочке. Если ставка 1P выше минимальной ставки, это означает, что SDK для медиации размещается перед этой сетью 3P.

Запустить выбор рекламы

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

Создайте объект AdSelectionFromOutcomesConfig.

Объект AdSelectionFromOutcomesConfig позволяет сети посредничества передавать список AdSelectionIds (результаты предыдущих аукционов), сигналы выбора объявлений и URI для загрузки JavaScript, который выбирает объявление из нескольких кандидатов. Список AdSelectionIds вместе с их ставками и сигналами передается в JavaScript, который может вернуть один из AdSelectionIds , если он превышает минимальную ставку, или ничего, если цепочка посредничества должна продолжаться.

Сети медиации создают объект AdSelectionFromOutcomesConfig используя AdSelectionId 1P из предыдущего раздела и минимальную ставку для рассматриваемой сети 3P. Новый объект AdSelectionFromOutcomesConfig следует создавать для каждого этапа цепочки медиации.

fun  runSelectOutcome(
    adSelectionClient : AdSelectionClient,
    outcome1p : AdSelectionOutcome,
    network3p : NetworkAdapter) : ListenableFuture<AdSelectionOutcome?> {
    val config = AdSelectionFromOutcomesConfig.Builder()
        .setSeller(seller)
        .setAdSelectionIds(listOf(outcome1p))
        .setSelectionSignals({"bid_floor": bid_floor})
        .setSelectionLogicUri(selectionLogicUri)
        .build()
    return adSelectionClient.selectAds(config)
}

public ListenableFuture<AdSelectionOutcome> runSelectOutcome(AdSelectionOutcome outcome1p,
                                              NetworkAdapter network3p) {
    AdSelectionFromOutcomesConfig config = new AdSelectionFromOutcomesConfig.Builder()
            .setSeller(seller)
            .setAdSelectionIds(Collection.singletonList(outcome1p))
            .setSelectionSignals({"bid_floor": bid_floor})
            .setSelectionLogicUri(selectionLogicUri)
            .build();

    return adSelectionClient.selectAds(config){}
}

Для переопределения метода selectAds() для каскадной медиации требуется входной параметр AdSelectionFromOutcomesConfig , в котором необходимо указать следующие обязательные параметры:

• Продавец : Идентификатор рекламной сети продавца, инициирующей выбор объявления.
• AdSelectionIds : Список из одного элемента, содержащий предыдущие selectAds() для одностраничной рекламы.
• Сигналы выбора рекламы : JSON-объект, сериализованный в строку, содержащий сигналы, используемые логикой назначения ставок покупателем. В данном случае включает минимальную ставку, полученную для данной 3P-сети.
• URI логики выбора : URL-адрес HTTPS, запрашиваемый во время выбора объявления для получения JavaScript-кода сети посредничества для выбора выигрышного объявления. См. необходимые сигнатуры функций в этом JavaScript-коде. JavaScript должен возвращать объявление стороннего поставщика, если ставка выше минимальной ставки, или возвращать null в противном случае. Это позволяет SDK посредничества обрезать цепочку посредничества, когда найден победитель.

После создания объекта AdSelectionOutcomesConfig вызовите метод selectAds() той 3P-сети, которая находится первой в цепочке.

val adSelectionManager = context.getSystemService(AdSelectionManager::class.java)

// Initialize AdSelectionFromOutcomesConfig
AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig =
  AdSelectionFromOutcomesConfig.Builder()
    .setSeller(seller)
    .setAdSelectionIds(listof(outcome1p))
    .setSelectionSignals({"bid_floor": bid_floor})
    .setSelectionLogicUri(selectionLogicUri)
    .setAdSelectionIds(outcomeIds)
    .build()

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
    adSelectionFromOutcomesConfig,
    executor,
    outcomeReceiver)

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize AdSelectionFromOutcomesConfig
AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig =
        new AdSelectionFromOutcomesConfig.Builder()
            .setSeller(seller)
            .setAdSelectionIds(Collection.singletonList(outcome1p))
            .setSelectionSignals({"bid_floor": bid_floor})
            .setSelectionLogicUri(selectionLogicUri)
            .setAdSelectionIds(outcomeIds)
            .build();

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
    adSelectionFromOutcomesConfig,
    executor,
    outcomeReceiver);

Организовать каскадную медиацию

Ниже представлена ​​последовательность действий, необходимых для проведения процесса медиации.

1. Запустить подборку объявлений 1P.
2. Пройдите по цепочке посредничества. Для каждой сети 3P выполните следующие действия:
   1. Создайте AdSelectionFromOutcomeConfig включив в него идентификатор результата (1P outcomeId и минимальную ставку (bid floor) из SDK стороннего разработчика.
   2. Вызовите функцию selectAds() с настройками, полученными на предыдущем шаге.
   3. Если результат не пустой, верните объявление.
   4. Вызовите метод selectAds() текущего сетевого адаптера SDK. Если результат не пустой, верните объявление.
3. Если победитель в цепочке не найден, верните объявление 1P.

fun runWaterfallMediation(mediationChain : List<NetworkAdapter>)
  : Pair<AdSelectionOutcome, NetworkAdapter> {
    val outcome1p = runAdSelection()

    var outcome : AdSelectionOutcome
    for(network3p in mediationChain) {
      outcome = runSelectOutcome(outcome1p, network3p)
      if (outcome1p.hasOutcome() && outcome.hasOutcome()) {
          return Pair(outcome, this)
      }

      outcome = network3p.runAdSelection()
      if(outcome.hasOutcome()) {
          return Pair(outcome, network3p)
      }
    }
  return Pair(outcome1p, this)
}

class MediationNetwork {
    AdSelectionManager adSelectionManager;

    public MediationNetwork() {
        AdSelectionManager adSelectionManager =
            context.getSystemService(AdSelectionManager.class);
    }

    public void runAdSelection() {...}

    public void reportImpressions() {...}

    public Pair<AdSelectionOutcome, NetworkAdapter> runWaterfallMediation(
            List<NetworkAdapter> mediationChain) {
        AdSelectionOutcome outcome1p = runAdSelection();

        AdSelectionOutcome outcome;
        for(NetworkAdapter network3p: mediationChain) {
            if (outcome1p.hasOutcome() &&
              (outcome = runSelectOutcome(outcome1p, network3p)).hasOutcome()) {
                return new Pair<>(outcome, this);
            }

            if((outcome = network3p.runAdSelection()).hasOutcome()) {
                return new Pair<>(outcome, network3p);
            }
        }
        return new Pair<>(outcome1p, this);
    }

    /* Runs comparison by creating an AdSelectionFromOutcomesConfig */
    public AdSelectionOutcome runSelectOutcome(AdSelectionOutcome outcome1p,
                                              NetworkAdapter network3p) { ... }
}

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

Существует два способа формирования отчетов о показах рекламы в зависимости от способа проведения аукциона. Если вы используете одну SSP-платформу для проведения аукциона, следуйте инструкциям в этом разделе. Если вы собираетесь внедрить каскадную медиацию, следуйте шагам, описанным в разделе, посвященном формированию отчетов о показах при каскадной медиации .

Отчетность по результатам одного SSP

После выбора наиболее подходящего объявления в процессе отбора вы можете сообщить о показе на участвующие платформы покупателей и продавцов с помощью метода AdSelectionManager.reportImpression() . Чтобы сообщить о показе объявления:

1. Инициализируйте объект AdSelectionManager .
2. Создайте объект ReportImpressionRequest с идентификатором выбранного объявления.
3. Вызовите асинхронный метод reportImpression() передав ему объект ReportImpressionRequest и соответствующие объекты Executor и OutcomeReceiver .

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize a ReportImpressionRequest
ReportImpressionRequest reportImpressionRequest =
        new ReportImpressionRequest.Builder()
                .setAdSelectionId(adSelectionId)
                .setAdSelectionConfig(adSelectionConfig)
                .build();

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportImpression(
    reportImpressionRequest,
    executor,
    outcomeReceiver);

val adSelectionManager = context.getSystemService(AdSelectionManager::class.java)

// Initialize a ReportImpressionRequest
val adSelectionConfig: ReportImpressionRequest =
    ReportImpressionRequest.Builder()
        .setAdSelectionId(adSelectionId)
        .setAdSelectionConfig(adSelectionConfig)
        .build()

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportImpression(
    reportImpressionRequest,
    executor,
    outcomeReceiver)

Инициализируйте объект ReportImpressionRequest указав следующие необходимые параметры:

• Идентификатор выбора рекламы : уникальный идентификатор, присваиваемый только пользователю устройства, который подтверждает успешный выбор рекламы.
• Конфигурация выбора объявлений : та же конфигурация, что и в вызове функции selectAds() идентифицируемой по предоставленному идентификатору выбора объявлений.

Асинхронный метод reportImpression() использует объект OutcomeReceiver для передачи результата вызова API.

• Функция обратного вызова onResult() указывает, были ли созданы URL-адреса для формирования отчетов о показах и был ли запланирован запрос.
• Функция обратного вызова onError() указывает на следующие возможные условия:
  • Если вызов инициализирован с недопустимым входным аргументом, в сообщении AdServicesException в качестве причины будет указано исключение IllegalArgumentException .
  • Все остальные ошибки сопровождаются исключением AdServicesException с указанием причины IllegalStateException .

Отчетность о впечатлениях от посредничества по методу водопада

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

Поставщики услуг хостинга могут использовать этот пример кода стороннего SDK в качестве прототипа того, как присоединяться к потокам посредничества:

Pair<AdSelectionOutcome, NetworkAdapter> winnerOutcomeAndNetwork =
         mediationSdk.orchestrateMediation(mediationChain);

if (winner.first.hasOutcome()) {
      winner.second.reportImpressions(winner.first.getAdSelectionId());

Конечные точки отчетности о показах

API для отображения отчетов отправляет HTTPS GET-запросы к конечным точкам, предоставленным платформой продавца и платформой покупателя, выигравшего сделку:

Конечная точка платформы для покупателей:

• API использует URL-адрес логики назначения ставок, указанный в пользовательской аудитории, для получения предоставленного покупателем JavaScript-кода, который включает логику для возврата URL-адреса отчета о показах.
• Вызовите функцию JavaScript reportWin() , которая должна вернуть URL-адрес отчета о показах покупателя.

Конечная точка платформы для продавцов:

• Используйте URL-адрес логики принятия решений, указанный в объекте AdSelectionConfig , чтобы получить JavaScript-код логики принятия решений продавцом.
• Вызовите функцию JavaScript reportResult() , которая должна вернуть URL-адрес отчета о показах продавца.

Отчетность по услугам торгов и аукционов

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

Отчет о впечатлениях, составленный с максимальной тщательностью

Метод reportImpression() предназначен для обеспечения максимально быстрого завершения формирования отчетов.

Сообщить о взаимодействии с рекламой

Функция «Защищенная аудитория» позволяет создавать отчеты по более детальным взаимодействиям с отображаемой рекламой. Это может включать такие взаимодействия, как время просмотра, клики, наведение курсора или любые другие полезные показатели, которые можно собрать. Процесс получения этих отчетов состоит из двух шагов. Во-первых, покупатели и продавцы должны зарегистрироваться для получения этих отчетов в своем JavaScript-коде для создания отчетов. Затем клиенту необходимо будет отправлять отчеты об этих событиях.

Регистрация для получения информации о мероприятиях взаимодействия.

Регистрация для получения событий взаимодействия происходит в функциях JavaScript ` reportWin() покупателя и reportResult() продавца с помощью функции JavaScript, предоставляемой платформой: registerAdBeacon . Чтобы зарегистрироваться для получения отчета о событиях, вызовите функцию JavaScript платформы из вашего JavaScript-кода для создания отчетов. В следующем фрагменте кода используется функция reportWin() покупателя, но тот же подход применим и к reportResult() .

reportWin(
  adSelectionSignals,
  perBuyerSignals,
  signalsForBuyer,
  contextualSignals,
  customAudienceSignals) {
    ...
    // Calculate reportingUri, clickUri, viewUri, and hoverUri

    registerAdBeacon({"click": clickUri, "view": viewUri, "hover": hoverUri});

    return reportingUri;
}

Сообщение о событиях взаимодействия

После отправки отчета о показе клиенты могут передать информацию о взаимодействиях на ранее зарегистрированные выигрышные платформы для покупателей и продавцов с помощью метода AdSelectionManager.reportInteraction() . Чтобы отправить отчет о событии показа рекламы:

1. Инициализируйте объект AdSelectionManager .
2. Создайте объект ReportInteractionRequest содержащий идентификатор выбранного объявления, ключ взаимодействия, данные взаимодействия и место назначения для создания отчета.
3. Вызовите асинхронный метод reportInteraction() с объектом request и соответствующими объектами Executor и OutcomeReceiver .

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize a ReportInteractionRequest
ReportInteractionRequest request =
  new ReportInteractionRequest.Builder()
    .setAdSelectionId(adSelectionId)
    .setInteractionKey("view")
    .setInteractionData("{ viewTimeInSeconds : 1 }") // Can be any string
    .setReportingDestinations(
      FLAG_REPORTING_DESTINATION_BUYER | FLAG_REPORTING_DESTINATION_SELLER
    )
    .build();

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportInteraction(
  reportImpressionRequest,
  executor,
  outcomeReceiver);

Инициализируйте объект ReportInteractionRequest указав следующие необходимые параметры:

• Идентификатор выбранного объявления : идентификатор выбранного объявления, полученный из ранее возвращенного AdSelectionOutcome .
• Ключ взаимодействия : строковый ключ, определенный клиентом и описывающий сообщаемое действие. Он должен совпадать с ключом, зарегистрированным продавцом или покупателем в функциях JavaScript для формирования отчетов.
• Данные взаимодействия : строка, содержащая данные, которые должны быть включены в отчет о событии и отправлены методом POST обратно на серверы отчетности.
• Адреса для отправки отчетов : битовая маска, указывающая, следует ли отправлять отчеты о событиях покупателю, продавцу или обоим. Эти флаги предоставляются платформой, а окончательную маску адресата можно создать с помощью побитовых операций. Для отправки отчета одному адресату можно использовать флаг, предоставленный платформой напрямую. Для отправки отчета нескольким адресатам можно использовать побитовое ИЛИ ( | ) для объединения значений флагов.

Асинхронный метод reportInteraction() использует объект OutcomeReceiver для передачи результата вызова API.

• Функция обратного вызова onResult() указывает на то, что вызов взаимодействия с отчетом является допустимым.
• Функция обратного вызова onError() указывает на следующие возможные условия:
  • Если вызов выполняется, когда приложение работает в фоновом режиме, возвращается исключение IllegalStateException с описанием причины ошибки.
  • Если клиенту запрещается вызывать reportInteraction() , возвращается исключение LimitExceededException .
  • Если пакет не зарегистрирован для вызова API, обеспечивающих сохранение конфиденциальности, возвращается исключение SecurityException() .
  • Если приложение, сообщающее о взаимодействиях, отличается от приложения, вызвавшего selectAds() , возвращается исключение IllegalStateException .
• Если пользователь не дал согласия на включение API «Песочницы конфиденциальности», вызов завершится без уведомления об ошибке.

Конечные точки для формирования отчетов о взаимодействиях

API взаимодействия с отчетами отправляет HTTPS POST-запросы на конечные точки, предоставленные платформой продавца и платформой покупателя, выигравшего сделку. Protected Audience сопоставляет ключи взаимодействия с URI, указанными в JavaScript-коде отчетов, и отправляет POST-запрос на каждую конечную точку для каждого взаимодействия, о котором ведется отчет. Content-Type запроса — обычный текст, а тело запроса — данные взаимодействия.

Best effort Interaction reporting

The reportInteraction() is designed to offer a best-effort completion of reporting through HTTP POST.

Daily background update

When creating a custom audience, your app or SDK can initialize custom audience metadata. Additionally, the platform can update the following pieces of custom audience metadata with a daily background update process.

• User bidding signals
• Trusted bidding data
• AdData list

This process queries against the Daily update URL defined in the custom audience and the URL may return a JSON response.

• The JSON response may contain any of the supported metadata fields that needs to be updated.
• Each JSON field is validated independently. The client ignores any malformed fields which results in no updates to that particular field in the response.
• An empty HTTP response or an empty JSON object " {} " results in no metadata updates.
• The response message size must be limited to 10 KB.
• All URIs are required to use HTTPS.
• trusted_bidding_uri must share the same ETLD+1 as the buyer.

Example: JSON response for background daily update

{
    "user_bidding_signals" : { ... },  // Valid JSON object
    "trusted_bidding_data" : {
        "trusted_bidding_uri" : 'example-dsp1-key-value-service.com',
        "trusted_bidding_keys" : [ 'campaign123', 'campaign456', ... ]
    },
    'ads' : [
        {
            "render_uri" : 'www.example-dsp1.com/.../campaign123.html',
            'metadata' : { ... }  // Valid JSON object
        },
        {
            "render_uri" : 'www.example-dsp1.com/.../campaign456.html',
            'metadata' : { ... }  // Valid JSON object
        },
        ...
    ]
}

JavaScript for ad selection

The ad selection workflow orchestrates the execution of buyer-provided and seller-provided JavaScript.

Buyer-provided JavaScript is fetched from the Bidding logic URL specified in the custom audience. The returned JavaScript should include the following functions:

• generateBid()
• reportWin()

Seller-provided JavaScript is fetched from the decision logic URL specified in the AdSelectionConfig parameter for the ad selection API. The returned JavaScript should include the following functions:

• scoreAd()
• reportResult()

generateBid()

function generateBid(
  ad,
  auction_signals,
  per_buyer_signals,
  trusted_bidding_signals,
  contextual_signals,
  user_signals,
  custom_audience_bidding_signals) {
  return {'status': 0, 'ad': ad, 'bid': ad.metadata.result };
}

Input parameters:

• ad : a JSON object with the format var ad = { 'render_url': url, 'metadata': json_metadata };
• auction_signals, per_buyer_signals : JSON objects specified in the auction configuration object

• custom_audience_bidding_signals : JSON object generated by the platform. The format for this JSON object is:

  var custom_audience_signals = {
    "owner":"ca_owner",
    "buyer":"ca_buyer",
    "name":"ca_name",
    "activation_time":"ca_activation_time_epoch_ms",
    "expiration_time":"ca_expiration_time_epoch_ms",
    "user_bidding_signals":"ca_user_bidding_signals"
  }
  

  где:

  • owner , buyer , and name are string taken from the properties with the same name of the Custom Audience participating to the ad selection
  • activation_time and expiration_time are the time of activation and expiration of the custom audience, expressed as seconds since the Unix epoch
  • ca_user_bidding_signals is a JSON string specified in the userBiddingSignals field of the CustomAudience at creation time
  • trusted_bidding_signals, contextual_signals , and user_signals are JSON objects. They are passed as empty objects and will be filled up in future releases. Their format is not enforced by the platform and is managed by the ad tech.

Результат:

• ad : is the ad the bid refers to. The script is allowed to return a copy of the ad it received with different metadata. The render_url property of the ad is expected to be unaltered.
• bid : a float value representing the bid value for this ad
• status : an integer value that can be:
  • 0 : for a successful execution
  • 1 : (or any non-zero value) in case any of the input signals is invalid. In case a non-zero value is returned by generate-bid the bidding process is invalidated for all the CA ads

scoreAd()

function scoreAd(
  ad,
  bid,
  ad_selection_config,
  seller_signals,
  trusted_scoring_signals,
  contextual_signal,
  user_signal,
  custom_audience_signal) {
    return {'status': 0, 'score': score };
}

Input parameters:

• ad : see the generateBid documentation
• bid : the bid value for the ad

• ad_selection_config : a JSON object representing the AdSelectionConfig parameter of the selectAds API. The format is:

  var ad_selection_config = {
    'seller': 'seller',
    'decision_logic_url': 'url_of_decision_logic',
    'custom_audience_buyers': ['buyer1', 'buyer2'],
    'auction_signals': auction_signals,
    'per_buyer_signals': per_buyer_signals,
    'contextual_ads': [ad1, ad2]
  }
  

• seller_signals : JSON objects read from the sellerSignals AdSelectionConfig API parameter

• trusted_scoring_signal : read from the adSelectionSignals field in the AdSelectionConfig API parameter

• contextual_signals, user_signals : JSON objects. They are passed as empty objects and will be filled up in future releases. Their format is not enforced by the platform and is managed by the ad tech.

• per_buyer_signals : JSON object read from the perBuyerSignal map in the AdSelectionConfig API parameter using as key the current Custom Audience buyer. Empty if the map doesn't contain any entry for the given buyer.

Выход:

• score : a float value representing the score value for this ad
• status : an integer value that can be:
  • 0: for a successful execution
  • 1: in case the customAudienceSignals are invalid
  • 2: in case the AdSelectionConfig is invalid
  • 3: in case any of the other signals is invalid
  • Any non-zero value causes the failure of the process, the value determines the type of exception thrown

selectOutcome()

function selectOutcome(
  outcomes,
  selection_signals) {
    return {'status': 0, 'result': null};
}

Input parameters:

• outcomes : a JSON object {"id": id_string, "bid": bid_double}
• selection_signals : JSON objects specified in the auction configuration object

Выход:

• status : 0 for success, non-zero for failure
• result : one of the outcomes passed in or null

reportResult()

function reportResult(ad_selection_config, render_url, bid, contextual_signals) {
   return {
      'status': status,
      'results': {'signals_for_buyer': signals_for_buyer, 'reporting_url': reporting_url }
   };
}

Input parameters:

• ad_selection_config : see the documentation of scoreAds
• render_url : the render URL of the winning ad
• bid : the bid offered for the winning ad
• contextual_signals : see the documentation of generateBid

Выход:

• status: 0 for success and non-zero for failure
• results : a JSON objects containing:
  • signals_for_buyer : a JSON object that is passed to the reportWin function
  • reporting_url : a URL that is used by the platform to notify the impression to the buyer

reportWin()

function reportWin(
   ad_selection_signals,
   per_buyer_signals,
   signals_for_buyer,
   contextual_signals,
   custom_audience_signals) {
   return {'status': 0, 'results': {'reporting_url': reporting_url } };
}

Input parameters:

• ad_selection_signals, per_buyer_signals : see the documentation for scoreAd
• signals_for_buyer : a JSON object returned by reportResult
• contextual_signals, custom_audience_signals : see the documentation for generateBid

Выход:

• status: 0 for success and non-zero for failure
• results : a JSON object containing:
  • reporting_url : a URL that is used by the platform to notify the impression to the seller

registerAdBeacon()

function registerAdBeacon(
  beacons
)

Input Parameters :

• beacons : An object containing key-value pairs of interaction keys and reporting URIs. The format is:

  let beacons = {
    'interaction_key': 'reporting_uri',
    'interaction_key': 'reporting_uri',
    ...
  }
  

  • interaction_key : A string representing the event. This is used by the platform later when reporting event interactions to look up the reporting_uri that should be notified. This key needs to match between what the buyer or seller is registering, and what the seller is reporting.
  • reporting_uri : A URI to receive event reports. This should be specific to the event type being reported. It must accept a POST request to handle any data reported along with the event.

  Например:

    let beacons = {
      'click': 'https://reporting.example.com/click_event',
      'view': 'https://reporting.example.com/view_event'
    }
  

Ad Selection prebuilt URIs

Prebuilt URIs give ad techs the ability to appoint JavaScript functions for ad selection decision logic in the AdSelectionConfig and AdSelectionFromOutcomesConfig classes. Prebuilt URIs don't require network calls to download the corresponding JavaScript. Ad techs can use prebuilt URIs without having to set up an enrolled domain to host the JavaScript.

A prebuilt URI is constructed using the following format:

ad-selection-prebuilt:<use-case>/<name>?<required-script-generation-parameters>

The Privacy Sandbox platform provides JavaScript using the information from this URI in the runtime.

An IllegalArgumentException is thrown if:

• any of the required parameters are not present in the URI
• there are unrecognized parameters in the URI

Supported prebuilt URI use cases and names

Use case 1: ad-selection

Prebuilt URIs under the ad-selection use case are supported in the selectAds(AdSelectionConfig) flow.

Prebuilt URI name: highest-bid-wins

This prebuilt URI provides a JavaScript that picks the ad with the highest bid after bidding. It also provides a basic reporting function to report the winner's render_uri and bid .

Required parameters

reportingUrl : The base reporting URL that is parameterized with the render_uri and the bid of the winning ad:

<reportingUrl>?render_uri=<renderUriOfWinnigAd>&bid=<bidOfWinningAd>

Использование

If your base reporting URL is https://www.ssp.com/reporting then the prebuilt URI would be:

`ad-selection-prebuilt://ad-selection/highest-bid-wins/?reportingUrl=https://www.ssp.com/reporting`

Use case 2: ad-selection-from-outcomes

Prebuilt URIs under the ad-selection-from-outcomes use case support the selectAds(AdSelectionFromOutcomesConfig) workflow.

Prebuilt URI name: waterfall-mediation-truncation

The waterfall-mediation-truncation prebuilt URI provides JavaScript that implements waterfall mediation truncation logic where the JavaScript returns a first-party ad if the bid is higher then or equal to the bid floor , and otherwise returns null .

Required parameters

bidFloor : The key of the bid floor value passed in the getSelectionSignals() that is compared against the mediation SDK's ad.

Использование

If your ad selection signals look like {"bid_floor": 10} then the resulting prebuilt URI would be:

`ad-selection-prebuilt://ad-selection-from-outcomes/waterfall-mediation-truncation/?bidFloor=bid_floor`

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

To help you get started with the Protected Audience API, we've created sample apps in Kotlin and Java, which can be found on GitHub .

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

The Protected Audience API requires some JavaScript during ad selection and impression reporting. There are two methods of providing this JavaScript in a testing environment:

• Run a server with the required HTTPS endpoints that returns the JavaScript
• Override remote fetching by providing the necessary code from a local source

Either approach requires setting up an HTTPS endpoint to handle impression reporting.

HTTPS endpoints

To test ad selection and impression reporting, you need to set up 7 HTTPS endpoints that your test device or emulator can access:

1. Buyer endpoint that serves the bidding logic JavaScript.
2. An endpoint that serves the bidding signals.
3. Seller endpoint that serves the decision logic JavaScript.
4. An endpoint that serves scoring signals.
5. Winning buyer impression reporting endpoint.
6. Seller impression reporting endpoint.
7. An endpoint to serve the daily updates for a custom audience.

For convenience, the GitHub repository provides basic JavaScript code for testing purposes. It also includes OpenAPI service definitions which can be deployed to a supported mock or microservices platform. For more details, see the project README .

Override remote fetching of JavaScript

This feature is intended to be used for end-to-end testing. To override remote fetching, your app must run in debug mode with developer options enabled.

To enable debug mode for your application, add the following line to the application attribute in your AndroidManifest.xml:

<application
  android:debuggable="true">

For an example of how to use these overrides, see the the Protected Audience API sample app on GitHub.

You need to add your own custom JavaScript to handle ad selection routines such as bidding, scoring decisions, and reporting. You can find basic JavaScript code examples that handle all required requests in the GitHub repo . The Protected Audience API sample application demonstrates how to read code from that file and prepare it for use as an override.

It is possible to override sell-side and buy-side JavaScript fetching independently, though you need an HTTPS endpoint to serve any JavaScript you aren't providing overrides for. See the README for information about how to set up a server that handles these cases.

It is only possible to override JavaScript fetching for custom audiences that are owned by your package.

Override sell-side JavaScript

To set up an override of sell-side JavaScript, do the following as demonstrated in the following code example:

1. Initialize an AdSelectionManager object.
2. Get a reference to TestAdSelectionManager from the AdSelectionManager object.
3. Build an AdSelectionConfig object.
4. Build an AddAdSelectionOverrideRequest with the AdSelectionConfig object and a String representing the JavaScript you intend to use as an override.
5. Call the asynchronous overrideAdSelectionConfigRemoteInfo() method with the AddAdSelectionOverrideRequest object and relevant Executor and OutcomeReceiver objects.

val testAdSelectionManager: TestAdSelectionManager =
  context.getSystemService(AdSelectionManager::class.java).getTestAdSelectionManager()

// Initialize AdSelectionConfig =
val adSelectionConfig = new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .build()

// Initialize AddAddSelectionOverrideRequest
val request = AddAdSelectionOverrideRequest.Builder()
    .setAdSelectionConfig(adSelectionConfig)
    .setDecisionLogicJs(decisionLogicJS)
    .build()

// Run the call to override the JavaScript for the given AdSelectionConfig
// Note that this only takes effect in apps marked as debuggable
testAdSelectionManager.overrideAdSelectionConfigRemoteInfo(
    request,
    executor,
    outComeReceiver)

TestAdSelectionManager testAdSelectionManager =
  context.getSystemService(AdSelectionManager.class).getTestAdSelectionManager();

// Initialize AdSelectionConfig =
AdSelectionConfig adSelectionConfig = new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .build();

// Initialize AddAddSelectionOverrideRequest
AddAdSelectionOverrideRequest request = AddAdSelectionOverrideRequest.Builder()
    .setAdSelectionConfig(adSelectionConfig)
    .setDecisionLogicJs(decisionLogicJS)
    .build();

// Run the call to override the JavaScript for the given AdSelectionConfig
// Note that this only takes effect in apps marked as debuggable
testAdSelectionManager.overrideAdSelectionConfigRemoteInfo(
    request,
    executor,
    outComeReceiver);

See the Run ad selection section for more information about what each of the fields in the AdSelectionConfig represent. The key difference is that the decisionLogicUrl can be set to a placeholder value as it will be ignored.

In order to override the JavaScript used during ad selection, the decisionLogicJs must contain the proper seller-side function signatures . For an example of how to read a JavaScript file as a string, see the Protected Audience API sample app on GitHub.

The asynchronous overrideAdSelectionConfigRemoteInfo() method uses the OutcomeReceiver object to signal the result of the API call.

The onResult() callback signifies the override was applied successfully. Future calls to selectAds() will use whatever decision and reporting logic you have passed in as the override.

The onError() callback signifies two possible conditions:

• If the override is attempted with invalid arguments, the AdServiceException indicates an IllegalArgumentException as the cause.
• If the override is attempted with an app not running in debug mode with developer options enabled, the AdServiceException indicates IllegalStateException as the cause.

Reset sell-side overrides

This section assumes that you have overridden the sell-side JavaScript and that you have a reference to the TestAdSelectionManager and AdSelectionConfig used in the previous section.

In order to reset the overrides for all AdSelectionConfigs :

1. Call the asynchronous resetAllAdSelectionConfigRemoteOverrides() method with the relevant OutcomeReceiver object.

// Resets overrides for all AdSelectionConfigs
testAadSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
  outComeReceiver)

// Resets overrides for all AdSelectionConfigs
testAdSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
    outComeReceiver);

After you reset sell-side overrides, calls to selectAds() use whatever decisionLogicUrl is stored in the AdSelectionConfig to attempt to fetch the required JavaScript.

If the call to resetAllAdSelectionConfigRemoteOverrides() fails, the OutComeReceiver.onError() callback provides an AdServiceException . If the removal of overrides is attempted with an app not running in debug mode with developer options enabled, AdServiceException indicates IllegalStateException as the cause.

Override buy-side JavaScript

1. Follow the steps to join a custom audience
2. Build an AddCustomAudienceOverrideRequest with the buyer and name of the custom audience you need to override, in addition to the bidding logic and data you want to use as an override.
3. Call the asynchronous overrideCustomAudienceRemoteInfo() method with the AddCustomAudienceOverrideRequest object and relevant Executor and OutcomeReceiver objects.

val testCustomAudienceManager: TestCustomAudienceManager =
  context.getSystemService(CustomAudienceManager::class.java).getTestCustomAudienceManager()

// Join custom audience

// Build the AddCustomAudienceOverrideRequest
val request = AddCustomAudienceOverrideRequest.Builder()
    .setBuyer(buyer)
    .setName(name)
    .setBiddingLogicJs(biddingLogicJS)
    .setTrustedBiddingSignals(trustedBiddingSignals)
    .build()

// Run the call to override JavaScript for the given custom audience
testCustomAudienceManager.overrideCustomAudienceRemoteInfo(
    request,
    executor,
    outComeReceiver)

TestCustomAudienceManager testCustomAudienceManager =
  context.getSystemService(CustomAudienceManager.class).getTestCustomAudienceManager();

// Join custom audience

// Build the AddCustomAudienceOverrideRequest
AddCustomAudienceOverrideRequest request =
    AddCustomAudienceOverrideRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .setBiddingLogicJs(biddingLogicJS)
        .setTrustedBiddingSignals(trustedBiddingSignals)
        .build();

// Run the call to override JavaScript for the given custom audience
testCustomAudienceManager.overrideCustomAudienceRemoteInfo(
    request,
    executor,
    outComeReceiver);

The values for buyer and name are the same ones used to create the custom audience. Learn more about these fields .

Additionally, you can specify two additional parameters:

• biddingLogicJs : JavaScript that holds the buyer's logic that is used during ad selection. See the required function signatures in this JavaScript.
• trustedBiddingSignals : Bidding signals to be used during ad selection. For testing purposes this can be an empty string.

The asynchronous overrideCustomAudienceRemoteInfo() method uses the OutcomeReceiver object to signal the result of the API call.

The onResult() callback signifies the override was applied successfully. Subsequent calls to selectAds() use whatever bidding and reporting logic you have passed in as the override.

The onError() callback signifies two possible conditions.

• If the override is attempted with invalid arguments, the AdServiceException indicates an IllegalArgumentException as the cause.
• If the override is attempted with an app not running in debug mode with developer options enabled, the AdServiceException indicates IllegalStateException as the cause.

Reset buy-side overrides

This section assumes that you have overridden the buy-side JavaScript and that you have a reference to the TestCustomAudienceManager used in the previous section.

To reset overrides for all custom audiences:

1. Call the asynchronous resetAllCustomAudienceOverrides() method with relevant Executor and OutcomeReceiver objects.

// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
    executor,
    outComeReceiver)

// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
    executor,
    outComeReceiver)

After you reset buy-side overrides, subsequent calls to selectAds() use whatever biddingLogicUrl and trustedBiddingData is stored in the CustomAudience to attempt to fetch the required JavaScript.

If the call to resetCustomAudienceRemoteInfoOverride() fails, the OutComeReceiver.onError() callback provides an AdServiceException . If the removal of overrides is attempted with an app not running in debug mode with developer options enabled, the AdServiceException indicates IllegalStateException as the cause.

Set Up a Reporting Server

When you use remote fetching overrides, you'll still need to set up a server that your device or emulator can reach to respond to reporting events. An endpoint that returns 200 is sufficient for testing. The GitHub repository includes OpenAPI service definitions which can be deployed to a supported mock or microservices platform. For more details, see the project README .

When looking for the OpenAPI definitions, look for the reporting-server.json. This file contains an endpoint that returns 200, representing an HTTP response code. This endpoint is used during selectAds() and signals to the Protected Audience API that impression reporting completed successfully.

Functionality to test

• Exercise joining or leaving and setting up a custom audience based on prior user actions.
• Exercise the initiation of on-device ad selection through JavaScripts hosted remotely.
• Observe how an app's association with custom audience settings may affect ad selection outcomes.
• Exercise impression reporting after ad selection.

Ограничения

The following table lists limitations for the Protected Audience API processing. The limits presented could be subject to change based on feedback. For in-progress capabilities, read the release notes .

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

Your feedback is a crucial part of the Privacy Sandbox on Android! Let us know of any issues you find or ideas for improving Privacy Sandbox on Android.