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

для разработчиков

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


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

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

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

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

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

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

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

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

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

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

  • Время активации . Пользовательская аудитория может участвовать в выборе рекламы и ежедневных обновлениях только после времени ее активации. Это может быть полезно, например, для привлечения устаревших пользователей приложения.
  • Срок действия : будущее время, по истечении которого пользовательская аудитория будет удалена с устройства.
  • Сигналы пользовательских ставок . Строка JSON, содержащая пользовательские сигналы, такие как предпочтительный языковой стандарт пользователя, которые JavaScript-логика назначения ставок покупателя использует для создания ставок в процессе выбора объявления. Этот формат помогает платформам рекламных технологий повторно использовать код на разных платформах и упрощает использование функций JavaScript.
  • Доверенные данные о ставках : URL-адрес HTTPS и список строк, используемых в процессе выбора объявлений, которые получают сигналы ставок от доверенной службы ключей/значений.
  • Объявления : список объектов AdData , соответствующих объявлениям, которые участвуют в выборе объявлений. Каждый объект AdData состоит из:
    • URL-адрес отображения : 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 Protected Audience для выбора рекламы, вызовите метод 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-адрес логики принятия решения : URL-адрес HTTPS, запрошенный для получения логики JavaScript рекламной сети продавца.
    • URL-адрес HTTPS : запрашивается для получения логики JavaScript рекламной сети продавца. См. необходимые сигнатуры функций .
    • Готовый URI : соответствует формату выбора объявлений FLEDGE. IllegalArgumentException выдается, если передается неподдерживаемый или неверный заранее созданный URI.
  • Покупатели индивидуальной аудитории : полный список идентификаторов рекламных сетей покупателей, которым продавец разрешает участвовать в процессе выбора объявлений. Эти идентификаторы покупателей соответствуют 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 после чего она будет работать так же, как и реклама на устройствах, включая право на фильтрацию негативной рекламы. После завершения аукциона Protected Audience вам необходимо вызвать 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();

Фильтрация ограничения частоты показов

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

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

  • Победа : событие победы указывает на то, что объявление выиграло аукцион. События Win автоматически обновляются API Protected Audience и не могут быть вызваны напрямую разработчиком. Данные о победах видны только объявлениям внутри определенной пользовательской аудитории.
  • Impression : отдельно от reportImpression , вызывающий объект на устройстве (SSP или MMP) использует updateAdCounterHistogram() для вызова событий показа в выбранном им месте кода. События показа видны всем объявлениям, принадлежащим данному DSP, и не ограничиваются объявлениями в одной и той же пользовательской аудитории.
  • Представление : событие вызывается вызывающей стороной на устройстве (SSP или MMP) в выбранном им месте кода с помощью вызова updateAdCounterHistogram() . События просмотра видны всем объявлениям, принадлежащим данному DSP, а не только объявлениям в одной и той же индивидуально настроенной аудитории.
  • Click : событие вызывается вызывающей стороной на устройстве (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-сети

Сети 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. Следуйте инструкциям по составлению отчета о показах объявлений (в соответствии с отчетом о показах единого поставщика услуг для отчетности.

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

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

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

Получение цепочки медиации и минимальных ставок

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

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

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

Запустить отбор объявлений

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

Создайте AdSelectionFromOutcomesConfig.

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

Сети-посредники создают AdSelectionFromOutcomesConfig используя 1P AdSelectionId из предыдущего раздела и минимальную ставку для рассматриваемой 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() для объявления 1P.
  • Сигналы выбора объявления : объект JSON, сериализованный в виде строки, содержащий сигналы, которые будут использоваться логикой назначения ставок покупателем. В этом случае включите минимальную ставку, полученную для данной 3P-сети.
  • URI логики выбора : URL-адрес HTTPS, запрашиваемый во время выбора объявления для получения кода JavaScript сети посредничества для выбора выигрышного объявления. См. необходимые сигнатуры функций в этом JavaScript. JavaScript должен возвращать 3P-объявление, если ставка выше минимальной ставки, или в противном случае возвращать 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 включая outcomeId 1P и минимальную ставку SDK 3P.
    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

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

Поставщики общих служб могут использовать этот пример кода 3P 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 для создания отчетов.
  • Данные взаимодействия : строка, содержащая данные, которые должны быть включены в отчет о событии и отправлены обратно на серверы отчетов.
  • Назначения отчетов : битовая маска, определяющая, следует ли сообщать о событиях покупателю, продавцу или обоим. Эти флаги предоставляются платформой, а конечную маску назначения можно создать с помощью побитовых операций. Чтобы сообщить об одном пункте назначения, вы можете напрямую использовать флаг, предоставленный платформой. Чтобы отправить отчет нескольким адресатам, вы можете использовать побитовое ИЛИ ( | ) для объединения значений флагов.

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

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

Конечные точки отчетов о взаимодействии

API взаимодействия с отчетами отправляет запросы HTTPS POST конечным точкам, предоставленным платформой продавца и выигравшей платформой покупателя. Защищенная аудитория сопоставит ключи взаимодействия с URI, объявленными в отчетном JavaScript, и отправит запрос POST каждой конечной точке для каждого взаимодействия, о котором сообщается. Тип контента запроса - это простой текст, а корпус - это данные взаимодействия.

Отчеты об взаимодействии наилучших усилий

reportInteraction() предназначен для того, чтобы предложить наиболее эффективное завершение отчетности через HTTP Post.

Ежедневное обновление фонового обновления

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

  • Пользовательские сигналы
  • Доверенные данные о торгах
  • Список AdData

Этот процесс запросы против URL -адреса Daily Update, определенного в пользовательской аудитории, и URL -адреса может вернуть ответ JSON.

  • Ответ JSON может содержать любое из поддерживаемых полей метаданных, которые необходимо обновить.
  • Каждое поле JSON проверяется независимо. Клиент игнорирует любые утронутые поля, которые не приводят к обновлениям этого конкретного поля в ответе.
  • Пустой HTTP -ответ или пустой объект JSON " {} " приводит к обновлениям метаданных.
  • Размер ответного сообщения должен быть ограничен 10 кб.
  • Все URI должны использовать HTTPS.
  • trusted_bidding_uri должен делиться тем же ETLD+1, что и покупатель.

Пример: ответ JSON для фона ежедневного обновления

{
    "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 для выбора рекламы

Рабочий процесс выбора рекламы организует выполнение предоставленного покупателя и предоставленного продавца JavaScript.

Предоставленный покупателем JavaScript получен из URL-адреса логики ставок, указанного в пользовательской аудитории. Возвращенный JavaScript должен включать следующие функции:

Предоставленный продавцом JavaScript получен из URL-адреса логики решений, указанного в параметре AdSelectionConfig для API выбора AD. Возвращенный JavaScript должен включать следующие функции:

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

Входные параметры:

  • ad : объект JSON с форматом var ad = { 'render_url': url, 'metadata': json_metadata };
  • auction_signals, per_buyer_signals : объекты JSON, указанные в объекте конфигурации аукциона
  • custom_audience_bidding_signals : объект json, сгенерированный платформой. Формат для этого объекта JSON:

    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 и name - строка, взятая из свойств с тем же названием пользовательской аудитории, участвующей в выборе объявления
    • activation_time и expiration_time - это время активации и истечения срока действия пользовательской аудитории, выраженная как секунды с момента эпохи UNIX
    • ca_user_bidding_signals - это строка JSON, указанная в поле userBiddingSignals в CustomAudience во время создания
    • trusted_bidding_signals, contextual_signals и user_signals являются объектами JSON. Они передаются в виде пустых объектов и будут заполнены в будущих выпусках. Их формат не применяется платформой и управляется рекламной технологией.

Результат:

  • ad : Объявление, к которому ссылается ставка. Сценарий разрешено вернуть копию объявления, полученного с различными метаданными. Свойство render_url рекламы, как ожидается, будет неизменным.
  • bid : значение поплавка, представляющее значение ставки для этого объявления
  • status : целочисленное значение, которое может быть:
    • 0 : для успешного исполнения
    • 1 : (или любое ненулевое значение) В случае, если какой-либо из входных сигналов недействителен. В случае, если ненулевое значение возвращается с помощью Generate-BID, процесс торгов неверен для всех объявлений CA

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

Входные параметры:

  • ad : См. Документация generateBid
  • bid : стоимость ставки для объявления
  • ad_selection_config : объект JSON, представляющий параметр AdSelectionConfig API selectAds . Формат:

    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 читается из параметра API AdSelectionConfig sellerSignals

  • trusted_scoring_signal : Читать с поля adSelectionSignals в параметре API AdSelectionConfig

  • contextual_signals, user_signals : JSON Objects. В настоящее время они передаются в виде пустых объектов и будут заполнены в будущих выпусках. Их формат не применяется платформой и управляется рекламной технологией.

  • per_buyer_signals : объект JSON считывается с карты perBuyerSignal в параметре API AdSelectionConfig , используя в качестве ключа текущего покупателя пользовательского аудитории. Пусто, если карта не содержит никакой записи для данного покупателя.

Выход:

  • score : значение поплавка, представляющее значение оценки для этого объявления
  • status : целочисленное значение, которое может быть:
    • 0: для успешного исполнения
    • 1: Если customAudienceSignals недействительны
    • 2: В случае, если AdSelectionConfig недействителен
    • 3: В случае, если любой из других сигналов недействителен
    • Любое ненулевое значение вызывает неудачу процесса, значение определяет тип исключения

selectOutcome ()

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

Входные параметры:

  • outcomes : объект json {"id": id_string, "bid": bid_double}
  • selection_signals : объекты JSON, указанные в объекте конфигурации аукциона

Выход:

  • status : 0 для успеха, ненулевая за неудача
  • result : один из результатов прошел или нулевой

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

Входные параметры:

  • ad_selection_config : см. Документацию scoreAds
  • render_url : рендеринг URL победного объявления
  • bid : предложение, предлагаемое на победную рекламу
  • contextual_signals : см. Документацию generateBid

Выход:

  • status: 0 для успеха и ненулевой
  • results : объекты JSON, содержащие:
    • signals_for_buyer : объект JSON, который передается в функцию reportWin
    • reporting_url : URL, который используется платформой, чтобы уведомить впечатление для покупателя

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

Входные параметры:

  • ad_selection_signals, per_buyer_signals : см. Документацию для scoreAd
  • signals_for_buyer : объект JSON, возвращенный reportResult
  • contextual_signals, custom_audience_signals : см. Документацию для generateBid

Выход:

  • status: 0 для успеха и ненулевой
  • results : объект JSON, содержащий:
    • reporting_url : URL, который используется платформой, чтобы уведомить впечатление продавцу

RegisterAdbeacon ()

function registerAdBeacon(
  beacons
)

Входные параметры :

  • beacons : объект, содержащий пары ключей клавиш взаимодействия и сообщать URI. Формат:

    let beacons = {
      'interaction_key': 'reporting_uri',
      'interaction_key': 'reporting_uri',
      ...
    }
    
    • interaction_key : строка, представляющая событие. Это используется платформой позже, когда сообщают о взаимодействиях событий, чтобы найти reporting_uri , который должен быть уведомлен. Этот ключ должен соответствовать тому, что регистрирует покупатель или продавец, и тем, что продавец сообщает.
    • reporting_uri : URI для получения отчетов о событиях. Это должно быть специфичным для сообщаемого типа события. Он должен принять запрос POST для обработки любых сообщенных данных вместе с событием.

    Например:

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

Выбор рекламы

Предварительно построенные URI дают AD Techs возможность назначать функции JavaScript для логики решений о выборе AD в классах AdSelectionConfig и AdSelectionFromOutcomesConfig . Предварительно построенные URI не требуют сетевых вызовов для загрузки соответствующего JavaScript. AD Techs могут использовать предварительно построенные URI, не настраивая зарегистрированный домен для размещения JavaScript.

Предварительно построенный URI построен с использованием следующего формата:

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

Платформа Sandbox Privacy Sandbox предоставляет JavaScript с использованием информации из этого URI во время выполнения.

IllegalArgumentException отбрасывается, если:

  • Любой из необходимых параметров не присутствует в URI
  • В URI есть нераспознанные параметры

Поддерживаемые предварительно построенные варианты использования URI и имена

Использование 1: выбор рекламы

Предварительно построенные URI в рамках ad-selection поддерживаются в потоке selectAds(AdSelectionConfig) .

Предварительно построенное Имя URI: highest-bid-wins

Этот предвенный URI предоставляет JavaScript, который выбирает объявление с самой высокой ставкой после торга. Он также предоставляет основную функцию отчетности для сообщений render_uri и bid победителя.

Требуемые параметры

reportingUrl : базовый URL -адрес отчетности, который параметризован с помощью render_uri , и bid победившей рекламы:

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

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

Если ваш базовый URL -адрес отчетности будет https://www.ssp.com/reporting , тогда будет предварительно построенный URI:

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

Использование 2: рекламный выбор из-за выбора

Предварительно построенный URI в рамках варианта использования ad-selection-from-outcomes selectAds(AdSelectionFromOutcomesConfig)

Предварительно построенное имя URI: waterfall-mediation-truncation

Предварительный URI-URI waterfall-mediation-truncation обеспечивает JavaScript, который реализует логику усечения водопада, где JavaScript возвращает первую сторону AD, если bid выше, или равна bid floor , и в противном случае возвращает null .

Требуемые параметры

bidFloor : Ключ значения пола заявки, пройденного в getSelectionSignals() , который сравнивается с рекламой Mediation SDK.

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

Если ваши сигналы выбора рекламы выглядят как {"bid_floor": 10} то полученное предварительно построенное URI будет:

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

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

Чтобы помочь вам начать работу с API защищенной аудитории, мы создали образцы приложений в Kotlin и Java, которые можно найти на GitHub .

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

Защищенная аудитория API требует некоторого JavaScript во время выбора AD и отчетов о впечатлениях. Есть два метода предоставления этого JavaScript в среде тестирования:

  • Запустите сервер с необходимыми конечными точками HTTPS, которые возвращают JavaScript
  • Переопределить удаленное извлечение, предоставив необходимый код из локального источника

Любой подход требует настройки конечной точки HTTPS для обработки отчетов о впечатлениях.

Https endpoints

Чтобы проверить выбор рекламы и отчетов о впечатлениях, вам необходимо настроить 7 конечных точек HTTPS, к которым может получить ваше тестовое устройство или эмулятор:

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

Для удобства, GitHub Repo предоставляет базовый код JavaScript для целей тестирования. Он также включает в себя определения услуг OpenAPI, которые могут быть развернуты на поддерживаемой платформе Mock или MicroServices. Для получения более подробной информации см. Project Readme .

Переопределить удаленное извлечение JavaScript

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

Чтобы включить режим отладки для вашего приложения, добавьте следующую строку в атрибут приложения в вашем AndroidManifest.xml:

<application
  android:debuggable="true">

Для примера того, как использовать эти переопределения, см. Приложение API защищенной аудитории на GitHub.

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

Можно переопределить независимо от выбора JavaScript на стороне продажи и покупки, хотя вам нужна конечная точка HTTPS, чтобы обслуживать любые JavaScript, для которых вы не предоставляете переопределения. Пожалуйста, смотрите Readme для получения информации о том, как настроить сервер, который обрабатывает эти случаи.

Можно только переопределить извлечение JavaScript для пользовательской аудитории, которая принадлежит вашей пакете.

Переопределить JavaScript продажи

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

  1. Инициализировать объект AdSelectionManager .
  2. Получите ссылку на TestAdSelectionManager от объекта AdSelectionManager .
  3. Создайте объект AdSelectionConfig .
  4. Создайте AddAdSelectionOverrideRequest с объектом AdSelectionConfig и String представляющей JavaScript, который вы намерены использовать в качестве переопределения.
  5. Вызовите асинхронный метод overrideAdSelectionConfigRemoteInfo() с помощью объекта AddAdSelectionOverrideRequest и соответствующих объектов Executor и OutcomeReceiver .

Котлин

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

См . Раздел «Выбор объявлений» для получения дополнительной информации о том, что представляет каждый из полей в AdSelectionConfig . Ключевое отличие состоит в том, что DecisionLogicurl может быть установлена ​​на заполнительную ценность, так как это будет игнорировано.

Чтобы переопределить JavaScript, используемый во время выбора AD, decisionLogicJs должны содержать надлежащие подписи функции на стороне продавца. Для примера того, как прочитать файл JavaScript в качестве строки, см. Приложение API защищенной аудитории на GitHub.

Метод Asynchronous overrideAdSelectionConfigRemoteInfo() использует объект OutcomeReceiver , чтобы сигнализировать о результате вызова API.

Обратный вызов onResult() означает, что переопределение было успешно применено. Будущие вызовы selectAds() будут использовать любые решения и логику отчетности, в которой вы приняли в качестве переопределения.

Обратный вызов onError() означает два возможных условия:

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

Сбросить переопределение продажи

В этом разделе предполагается, что вы переопределили JavaScript на стороне продажи и что у вас есть ссылка на TestAdSelectionManager и AdSelectionConfig используемые в предыдущем разделе.

Чтобы сбросить переопределения для всех AdSelectionConfigs :

  1. Вызовите асинхронный метод resetAllAdSelectionConfigRemoteOverrides() с соответствующим объектом OutcomeReceiver .

Котлин

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

Ява

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

После того, как вы сбросите переопределения на стороне продажи, вызовы в selectAds() используют любое решение , которое хранится в AdSelectionConfig , чтобы попытаться получить необходимый JavaScript.

Если вызов resetAllAdSelectionConfigRemoteOverrides() не удастся, обратный вызов OutComeReceiver.onError() обеспечивает AdServiceException . Если удаление переопределения предпринимается с приложением, не работает в режиме отладки с включенными параметрами разработчика, AdServiceException указывает на IllegalStateException в качестве причины.

Переопределить JavaScript покупки

  1. Следуйте шагам, чтобы присоединиться к пользовательской аудитории
  2. Создайте AddCustomAudienceOverrideRequest с покупателем и названием пользовательской аудитории, которую вы хотите переопределить, в дополнение к логике торгов и данных, которые вы хотите использовать в качестве переопределения
  3. Вызовите метод асинхронного overrideCustomAudienceRemoteInfo() с помощью объекта AddCustomAudienceOverrideRequest и соответствующих объектов Executor и OutcomeReceiver

Котлин

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

Значения для покупателя и имени - те же самые, которые используются для создания пользовательской аудитории. Узнайте больше об этих областях .

Кроме того, вы можете указать два дополнительных параметра:

  • biddingLogicJs : JavaScript, который держит логику покупателя, которая используется во время выбора рекламы. См. Требуемые подписи функции в этом JavaScript.
  • trustedBiddingSignals : сигналы ставок будут использоваться во время выбора AD. Для целей тестирования это может быть пустой строкой.

Асинхронный метод overrideCustomAudienceRemoteInfo() OutcomeReceiver

Обратный вызов onResult() означает, что переопределение было успешно применено. Последующие вызовы selectAds() используют любую торгов и логику отчетности, которые вы передали в качестве переопределения.

Обратный вызов onError() означает два возможных условия.

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

Сбросить переопределение покупки

В этом разделе предполагается, что вы переопределили JavaScript на стороне покупки и что у вас есть ссылка на TestCustomAudienceManager используемый в предыдущем разделе.

Чтобы сбросить переопределения для всей пользовательской аудитории:

  1. Вызовите метод асинхронного resetAllCustomAudienceOverrides() с соответствующими объектами Executor и OutcomeReceiver .

Котлин

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

Ява

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

После того, как вы сбросите переопределение на стороне покупки, последующие вызовы selectAds() используют любые biddingLogicUrl и trustedBiddingData , хранящиеся в CustomAudience , чтобы попытаться получить необходимый JavaScript.

Если вызов resetCustomAudienceRemoteInfoOverride() не удастся, обратный вызов OutComeReceiver.onError() обеспечивает AdServiceException . Если удаление переопределения предпринимается с приложением, не работает в режиме отладки с включенными параметрами разработчика, AdServiceException указывает на IllegalStateException в качестве причины.

Настройка сервера отчетности

Когда вы используете переопределения удаленного извлечения, вам все равно необходимо настроить сервер, который ваше устройство или эмулятор может реагировать на события отчетности. Простой конечной точки, которая возвращает 200, достаточно для тестирования. Repo GitHub включает определения услуг OpenAPI, которые можно развернуть на поддерживаемой платформе Mock или MicroServices. Для получения более подробной информации см. Project Readme .

При поиске определений OpenAPI ищите отчеты-server.json. Этот файл содержит простую конечную точку, которая возвращает 200, представляющая код ответа HTTP. Эта конечная точка используется во время selectAds() и сигнализирует API защищенной аудитории, которая успешно завершена отчетность.

Функциональность для проверки

  • Использование присоединения или оставления и настройки пользовательской аудитории на основе предыдущих действий пользователя.
  • Используйте инициацию выбора AD на устройстве через Javascripts, размещенные дистанционно.
  • Обратите внимание, как ассоциация приложения с пользовательскими настройками аудитории может повлиять на результаты выбора рекламы.
  • Отчеты о впечатлениях после выбора рекламы.

Ограничения

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

Компонент Ограничение Описание Предельное значение
Пользовательская аудитория (CA) Максимальное количество рекламы на CA 100
Максимальное количество CAS на приложение 1000
Максимальное количество приложений, которые могут создать CA 1000
Максимальная задержка во время активации CA от времени создания 60 дней
Максимальное время истечения срока действия CA с времени активации 60 дней
Максимальное количество CAS на устройстве 4000
Максимальный размер названия СА 200 байтов
Максимальный размер ежедневного выброса Uri 400 байтов
Максимальный размер логики ставок URI 400 байтов
Максимальный размер доверенных данных о торгах 10 КБ
Максимальный размер сигналов пользовательских торгах 10 КБ
Максимальная скорость вызовов для leaveCustomAudience на покупателя 1 в секунду
Максимальная скорость вызовов для joinCustomAudience на покупателя 1 в секунду
CA фоновая выборка Тайм -аут подключения 5 секунд
Http читать тайм -аут 30 секунд
Максимальный общий размер загрузки 10 КБ
Максимальная продолжительность итерации выбора 5 минут
Максимальное количество CAS, обновленных на работу 1000
Выбор рекламы Максимальное количество покупателей подлежит уточнению
Максимальное количество CAS на покупателя подлежит уточнению
Максимальное количество рекламы на аукционе подлежит уточнению
Первоначальный тайм -аут подключения 5 секунд
Тайм -аут для чтения подключения 5 секунд
Максимальное время выполнения общего AdSelection 10 секунд
Максимальное время выполнения торгов за CA в AdSelection 5 секунд
Максимальное время выполнения забивания в AdSelection 5 секунд
Максимальное время выполнения для каждого покупателя в AdSelection подлежит уточнению
Максимальный размер выбора объявлений/продавец/сигналы покупателя подлежит уточнению
Максимальный размер продавца/сценариев покупателя подлежит уточнению
Максимальная скорость вызовов для selectAds 1 QPS
Отчеты о впечатлениях Минимальное время до удаления выбора AD из стойкости 24 часа
Максимальное количество выбора рекламы хранения подлежит уточнению
Максимальный размер вывода отчетности URL подлежит уточнению
Максимальное время для отчетности о впечатлениях подлежит уточнению
Максимальное количество повторных переписей для вызовов уведомлений подлежит уточнению
Тайм-аут соединения 5 секунд
Максимальное общее время исполнения для reportImpression 2 секунды
Максимальная ставка вызовов для reportImpressions 1 QPS
Сообщение о событиях Максимальное количество маяков на покупателя за аукцион 10

Максимальное количество маяков на продавца за аукцион

10

Максимальный размер ключа событий

40 байтов

Максимальный размер данных о событиях

64 КБ

Объявления Максимальный размер рекламного списка 10 КБ, разделенные All AdData в одном CA для контекстуального
URL-адреса Максимальная длина любой строки URL -адреса, взятой в качестве входа подлежит уточнению
JavaScript Максимальное время исполнения 1 секунда для ставков и результатов на отчет о впечатлениях
Максимальная память используется 10 МБ

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

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

{ % Vorbatim %} { % endverbatim %} { % Vorbatim %} { % endverbatim %},

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


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

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

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

AD Tech Platerds могут интегрировать эти API для реализации ремаркетинга, которая сохраняет конфиденциальность пользователей. Поддержка дополнительных вариантов использования, включая App Install Ads, планируется для будущих выпусков. Узнайте больше об API защищенной аудитории на Android в предложении дизайна .

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

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

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

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

  1. Установите свою среду разработки для песочницы конфиденциальности на Android.
  2. Либо установите системное изображение на поддерживаемое устройство , либо настройте эмулятор , который включает в себя поддержку песочнице конфиденциальности на Android.
  3. В терминале включите доступ к API защищенной аудитории (отключен по умолчанию) со следующей командой ADB.

      adb shell device_config put adservices ppapi_app_allow_list \"*\"
    
  4. В терминале включите отчетность Beacon со следующими командами 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. Ссылка на конфигурацию AD Services в элементе <application> вашего манифеста:

      <property android:name="android.adservices.AD_SERVICES_CONFIG"
                android:resource="@xml/ad_services_config" />
    
  7. Укажите ресурс AD Services XML, упомянутый в вашем манифесте, например, res/xml/ad_services_config.xml . Узнайте больше о разрешениях на рекламные услуги и контроль доступа SDK .

      <ad-services-config>
        <custom-audiences allowAllToAccess="true" />
      </ad-services-config>
    
  8. По умолчанию API выбора AD обеспечивает ограничения на максимальный объем памяти, который может распределять сценарий отчетности на аукционе или отчетности. Функция ограничения памяти требует версии веб -просмотра 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 : имя пакета приложения владельца. Это неявно устанавливается на имя пакета приложения Caller.
  • buyer : Идентификатор для рекламной сети покупателей, которая управляет рекламой для этой пользовательской аудитории.
  • name : произвольное имя или идентификатор для пользовательской аудитории.

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

Кроме того, CustomAudience должен быть создан с помощью этих необходимых параметров:

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

  • Время активации : пользовательская аудитория может участвовать в выборе рекламы и ежедневных обновлениях только после времени ее активации. Это может быть полезно, например, привлечь пользователей приложения.
  • Время истечения : будущее, после чего пользовательская аудитория удаляется с устройства.
  • Пользовательские тендеры : строка JSON, содержащая пользовательские сигналы, такие как предпочтительный локаль пользователя, что логика торгов покупателя использует JavaScript для создания заявок в процессе выбора AD. Этот формат помогает рекламным технологическим платформам повторно использовать код на разных платформах и облегчает потребление в функциях JavaScript.
  • Доверенные данные о торгах : URL -адрес HTTPS и список строк, используемых в процессе выбора AD, которые извлекают сигналы ставок из доверенного сервиса ключа/стоимости.
  • Объявления : список объектов AdData соответствующих рекламе, которые участвуют в выборе AD. Каждый объект AdData состоит из:
    • Рендеринг URL : HTTPS URL, который запрашивается для того, чтобы сделать окончательную рекламу.
    • Метаданные : объект JSON, сериализованный как строка, содержащая информацию, которая будет использована логикой торгов покупателя в процессе выбора AD.
    • AD -фильтры : класс, который содержит всю необходимую информацию для приложения Установка AD -фильтрации и ограничения частоты во время выбора рекламы.

Вот пример экземпляра объекта 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. Вызовите метод Asynchronous 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 -адрес логики решений : URL -адрес HTTPS, запрошенный для получения логики JavaScript Seller Ad Network.
    • Https url : запрашивается, чтобы получить логику JavaScript продавцы Ad Network. См. Требуемые подписи функции .
    • Предварительно построенный URI : это следует за форматом выбора AD Flegh. IllegalArgumentException выброшена, если пройден непреодолимый или узорный предварительно построенный URI.
  • Пользовательские покупатели аудитории : полный список идентификаторов для покупательских рекламных сетей, которые разрешены продавцом для участия в процессе выбора рекламы. Эти идентификаторы покупателей соответствуют CustomAudience.getBuyer() участвующей пользовательской аудитории.

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

  • Сигналы выбора объявлений : объект JSON, сериализованный как строка, содержащий сигналы, которые будут использоваться логикой торгов покупателя, избираемой из CustomAudience.getBiddingLogicUrl() .
  • Seller signals : A JSON object, serialized as a string, containing signals consumed by the seller's fetched JavaScript decision logic from AdSelectionConfig.getDecisionLogicUrl() .
  • Per buyer signals : A map of JSON objects, serialized as strings, containing signals to be consumed by specific buyers' bidding logic JavaScript fetched from CustomAudience.getBiddingLogicUrl() , which are identified by the buyer fields of participating custom audiences.
  • Contextual ads: A collection of ad candidates that are collected directly from buyers during an auction that happens outside of a Protected Audience auction.

Once an ad is selected, the results, bids, and signals are persisted internally for reporting. The OutcomeReceiver.onResult() callback returns an AdSelectionOutcome that contains:

  • A render URL for the winning ad, obtained from AdData.getRenderUrl() .
  • An ad selection ID unique to the device user. This ID is used for reporting the ad impression.

If the ad selection can't be completed successfully due to reasons such as invalid arguments, timeouts, or excessive resource consumption, the OutcomeReceiver.onError() callback provides an AdServicesException with the following behaviors:

  • If the ad selection is initiated with invalid arguments, the AdServicesException indicates an IllegalArgumentException as the cause.
  • All other errors receive an AdServicesException with an IllegalStateException as the cause.

Contextual ads

Protected Audience can incorporate contextual ads into a Protected Auction. Contextual ads need to be selected on the ad tech server and returned to the device outside of Protected Audience APIs. Contextual ads can then be included in the auction using the AdSelectionConfig at which point they function the same as on device ads, including eligibility for negative ad filtering. Once the Protected Audience auction has completed, you need to invoke reportImpression() . This calls reportWin() in the winning contextual ad, in the same pattern as impression reporting , to receive the winning ad on a device. Each contextual ad needs a buyer, a bid, a link to reporting logic, a render URL, and ad metadata.

To deploy contextual ads in app, the target app needs to create a ContextualAds object:

Котлин

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

Java

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

The resulting ContextualAds object can then be passed along when creating your 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)

Java

// 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);

App install ad filtering

App install ads filtering helps you to filter installation ads for apps that are already installed on a device.

The first step in this process is to define which advertisers have the ability to filter on the installed package. This needs to happen in the app you want to target with an ad.

Котлин

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

Java

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

When the preceding code executes, the advertisers passed in are then able to filter out the installed apps that you specify during their bid generation. If you need to remove an advertiser from having access to this app's install status, run this code again with the advertiser's information removed.

The next step is to set up ad filtering inside the publisher app. The party that serves the ad inside of the publisher app (most likely to be a supply-side SDK) must initialize their AdFilters object with information about which ads related to apps they'd like to filter out:

Котлин

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

Java

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

Demand-side publishers may also set an AdFilter for ads that exist inside of their custom audiences.

AdFilters can also be passed in at the point of instantiating a new AdData object:

Котлин

// 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()

Java

// 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();

Frequency cap filtering

Frequency cap filtering enables ad techs to limit the number of times an ad is shown. Frequency cap filtering reduces ad overexposure and optimizes alternate ad selection for a given ad campaign.

There are two main components of a frequency cap filter: the ad event type, and the ad counter key. The available ad event types that can be used are:

  • Win : A win event indicates that the ad has won an auction. Win events are automatically updated by the Protected Audience API and cannot be called directly by the developer. Win data is only visible to ads within a given custom audience.
  • Impression : Separate from reportImpression , an on-device caller (SSP or MMP) uses updateAdCounterHistogram() to invoke impression events at the point in code they choose. Impression events are visible to all ads belonging to a given DSP, and are not limited to ads in the same custom audience.
  • View : Event is invoked by the on-device caller (SSP or MMP) at a point in code they choose using a call to updateAdCounterHistogram() . View events are visible to all ads belonging to a given DSP and not limited to ads in the same Custom Audience.
  • Click : Event is invoked by the on-device caller (SSP or MMP) at a point in code they choose using a call to updateAdCounterHistogram() . Click events are visible to all ads belonging to a given DSP and not limited to ads in the same Custom Audience.

In the publisher app, an SSP or MMP that has a presence on the device invokes ad events. When updateAdCounterHistogram() is called, the counter of a frequency cap filter is incremented so that future auctions will have up to date information about a user's exposure to a given ad. The ad event types are not forcibly tied to the corresponding user action and are guidelines given to help callers to structure their event system. To increment ad counters at the time of an event, the on-device actor provides the winning ad auction's ad selection ID.

Ad counter keys are arbitrary 32-bit signed integers assigned by a buyer ad tech, and they correspond to a given set of ads as defined by the DSP. Since ad counter keys are limited only to ads that belong to a given DSP, these keys can be selected without overlapping with histograms from another ad tech. Ad counter keys are used to increment DSP-specific identifiers across a DSP's ads or within a given custom audience to filter out ads from future auctions.

Counter keys can be leveraged to prioritize ads that are more likely to be interesting to a given user based on their interactions with other ads from a given buyer ad tech. For example, an ad that has received a high level of engagement from winning ad auctions, views, and clicks, represents an inferred data point. To further illustrate this point: an ad for left handed golf clubs might indicate that the user wouldn't be interested in right handed ones. A frequency cap filter set for a counter key assigned to left-handed ads could filter out ads for right handed clubs.

To use frequency capping in your auction, you must first create KeyedFrequencyCap objects as shown below:

Котлин

// 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()

Java

// 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();

Once the KeyedFrequencyCap objects are created, you can pass them into an AdFilters object.

Котлин

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

Java

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

When the AdFilters object is populated with frequency cap filters, it can be passed along when the custom audience is created:

Котлин

// 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()

Java

// 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();

When frequency cap filters are implemented into a custom audience, the SSP can then invoke the necessary click, view, or impression events.

Котлин

val callerAdTech: AdTechIdentifier = mAdSelectionConfig.getSeller()

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

Java

AdTechIdentifier callerAdTech = mAdSelectionConfig.getSeller();

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

Ads that have hit their pre-set frequency cap filter limits are filtered out of the auction. Filtering happens before the bidding logic is executed for on-device auctions, and as the payload is generating for Bidding & Auction services auctions.This toolkit gives ad techs the flexibility to use the interactions between users and the ads within their custom audiences to focus ad targeting while minimizing ad overexposure.

Contextual ad filtering without network calls

If there is no remarketing demand on the device, you can run ad selection for contextual ads without network calls. With prebuilt URIs and a list of contextual ads with bids, the platform can skip retrieving bidding logic, bidding signals, and scoring signals. The platform uses a prebuilt URI to select the contextual ad with the highest bid.

To improve latency, ad techs can run an ad selection flow that includes only contextual ads with ad filtering functionality without network calls. This is achieved by using prebuilt URIs for scoring signals. Refer to the Supported prebuilt URI use cases and names section for a list of scoreAds implementations.

To run ad selection without network calls:

  1. Set up ad filtering
  2. Create your contextual ads
  3. Create a AdSelectionConfig object with the following:

    1. An empty list of buyers
    2. A prebuilt URI to select the highest bid
    3. Contextual ads
    4. An empty URI for the scoring signals. The empty URI is allowed to indicate that you don't want to use the fetching of trusted signals for scoring:
    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. Run ad selection:

    adSelectionManager.selectAds(
        adSelectionConfig,
        executor,
        outcomeReceiver);
    

Run your own reporting JavaScript while using prebuilt URIs

Today, the Privacy Sandbox platform only has a basic reporting JavaScript implementation available for prebuilt URIs. If you want to run your own reporting JavaScript while still using prebuilt URIs for a low latency ad selection, you can override the DecisionLogicUri between ad selection and reporting runs.

  1. Run steps to run ad selection for contextual ads using prebuilt URIs
  2. Create a copy of your AdSelectionConfig before running reporting

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

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

Run waterfall mediation

Waterfall mediation requires multiple third party SDKs (3P networks) to be orchestrated by a first party SDK mediation network. Waterfall mediation is done the same way regardless if the auction took place on device or ran on Bidding & Auction services (B&A).

3P networks

3P networks need to provide an adapter that allows the mediation network to invoke the necessary methods for running an auction:

  • Run ad selection
  • Report impressions

Here's an example of a mediation network adapter:

Котлин

class NetworkAdaptor {
    private val adSelectionManager : AdSelectionManager

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

    fun selectAds() {...}

    fun reportImpressions() {...}
}

Java

class NetworkAdaptor {
    AdSelectionManager adSelectionManager;

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

    public void selectAds() {...}

    public void reportImpressions() {...}
}

Each SDK has their own ad selection service managers and clients, and their own selectAds and reportImpressions implementation. SDK providers can refer to the sections on how to run ad selection for on-device auctions or the B&A explainer for B&A auctions. Follow how to report ad impressions (following the single SSP impression reporting for reporting.

Mediation network

Similar to 3P networks, mediation networks need selectAds and reportImpression implementations. Refer to the sections on how to run ad selection and how to report ad impressions for more information.

Mediation networks are responsible for running the mediation chain and placing themselves in the mediation chain. The next section covers how to set up and execute this process.

Retrieve mediation chain and bid floors

The mediation network is responsible for retrieving the first party (1P) contextual ads, mediation chain, and third party networks' bid floors (3P). This can happen in a request to retrieve contextual ads executed by the mediation network. The mediation chain determines how to iterate through the 3P Networks, and the bid floors can be passed to the auction process as adSelectionSignals .

Network placement in the mediation chain

A mediation SDK can place itself in the mediation chain based on their live eCPM of 1P ad bids. In the Protected Audience API, ad bids are opaque. A mediation SDK should use AdSelectionFromOutcomesConfig to be able to compare a given 1P ad's bid to the bid floor of the next 3P network in the chain. If the 1P bid is higher than the bid floor then that means the mediation SDK is placed in front of that 3P network.

Run ad selection

To retrieve a 1P ad candidate, the mediation network can execute an on-device auction following the steps in the run ad selection section. This generates a 1P ad candidate, a bid, and an AdSelectionId that is used in the mediation process.

Create an AdSelectionFromOutcomesConfig

An AdSelectionFromOutcomesConfig allows the mediation network to pass a list of AdSelectionIds (results from previous auctions), ad selection signals, and a URI to fetch JavaScript that selects an ad from multiple candidates. The list of AdSelectionIds along with their bids and the signals are passed to the JavaScript which can return one of the AdSelectionIds if it beats the bid floor, or none if the mediation chain should continued.

Mediation Networks create an AdSelectionFromOutcomesConfig using the 1P AdSelectionId from the previous section, and the bid floor for the 3P Network being considered. A new AdSelectionFromOutcomesConfig should be created for each step in the mediation chain.

Котлин

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

Java

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

The selectAds() method override for waterfall mediation requires an AdSelectionFromOutcomesConfig input, where you must specify the following required parameters:

  • Seller : Identifier for the seller ad network initiating the ad selection.
  • AdSelectionIds : A singleton list of a previous selectAds() run for a 1P ad.
  • Ad selection signals : A JSON object, serialized as a string, containing signals to be used by buyer bidding logic. In this case, include the bid floor retrieved for the given 3P network.
  • Selection Logic URI : An HTTPS URL queried during ad selection to fetch the mediation network's JavaScript for selecting a winning ad. See the required function signatures in this JavaScript. The JavaScript should return the 3P ad if the bid is higher than the bid floor, or otherwise return null . This allows the mediation SDK to truncate the mediation chain when a winner is found.

With the AdSelectionOutcomesConfig created, call the selectAds() method of the 3P network that is first in the chain.

Котлин

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)

Java

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

Orchestrate waterfall mediation

The following is the order of operations for running through the mediation process.

  1. Run 1P ad selection.
  2. Iterate over the mediation chain. For each 3P network, do the following:
    1. Build AdSelectionFromOutcomeConfig including the 1P outcomeId and the 3P SDK's bid floor.
    2. Call selectAds() with the config from the previous step.
    3. If the result is not empty, return the ad.
    4. Call the current SDK network adapter's selectAds() method. If the result is not empty, return the ad.
  3. If no winner is found from the chain, return the 1P ad.

Котлин

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

Java

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) { ... }
}

Report ad impressions

There are two flows for reporting an ad impression depending on how the auction is run. If you are a single SSP running an auction, follow this section. If you are going to implement waterfall mediation, follow the steps found in the waterfall mediation impression reporting section .

Single SSP impression reporting

After a winning ad has been chosen from the ad selection workflow, you can report the impression back to participating buy-side and sell-side platforms with the AdSelectionManager.reportImpression() method. To report an ad impression:

  1. Initialize an AdSelectionManager object.
  2. Build a ReportImpressionRequest object with the ad selection ID.
  3. Call the asynchronous reportImpression() method with the ReportImpressionRequest object and relevant Executor and OutcomeReceiver objects.

Java

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)

Initialize the ReportImpressionRequest with the following required parameters:

  • Ad selection ID : An ID unique only to a device user that identifies a successful ad selection.
  • Ad selection config : The same configuration used in the selectAds() call identified by the provided ad selection ID.

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

  • The onResult() callback indicates if impression reporting URLs have been created and the request has been scheduled.
  • The onError() callback indicates the following possible conditions:
    • If the call is initialized with an invalid input argument, the AdServicesException indicates an IllegalArgumentException as the cause.
    • All other errors receive an AdServicesException with an IllegalStateException as the cause.

Waterfall mediation impression reporting

A mediation SDK needs to keep track of the winning SDK to trigger their reporting flows. The SDKs participating in a mediation chain should provide a method for the mediator to invoke to trigger their own reporting flow. An SDK participating in a mediated auction can follow the steps above to implement their own reporting.

SSPs can use this 3P SDK code example as a prototype for how to join in mediation flows:

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

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

Impression reporting endpoints

The report impression API issues HTTPS GET requests to endpoints provided by the sell-side platform and the winning buy-side platform:

Buy-side platform endpoint:

  • The API uses the Bidding logic URL specified in the custom audience to fetch the buyer-provided JavaScript that includes logic to return an impression reporting URL.
  • Invoke the reportWin() JavaScript function, which is expected to return the buyer's impression reporting URL.

Sell-side platform endpoint:

  • Use the Decision logic URL specified in the AdSelectionConfig object to fetch the seller's decision logic JavaScript.
  • Invoke the reportResult() JavaScript function, which is expected to return the seller's impression reporting URL.

Bidding & Auction services reporting

An auction executed on Bidding & Auction services will have all the necessary reporting information, including generated URLs for ad interaction reporting , included in the encrypted response from the server-side auction. When the response is decrypted, the appropriate URLs are registered with the platform, so ad and impression reporting follows the same steps listed above.

Best effort Impression reporting

The reportImpression() method is designed to offer a best-effort completion of reporting.

Report Ad Interactions

Protected Audience provides support to report on more granular interactions for a rendered ad. This can include interactions such as view time, clicks, hovers, or any other useful metric that can be collected. The process to receive these reports requires two steps. First, buyers and sellers must register to receive these reports in their reporting JavaScript. Then, the client will need to report these events.

Registering to receive interaction events

Registering for interaction events happens in the buyer's reportWin() and seller's reportResult() JavaScript functions using a JavaScript function provided by the platform: registerAdBeacon . To register to receive an event report, simply call the platform JavaScript Function from your reporting JavaScript. The following snippet is using a buyer's reportWin() , but the same approach applies to reportResult() .

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

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

    return reportingUri;
}

Reporting interaction events

After reporting an impression, clients can report the interactions back to previously registered winning buy-side and sell-side platforms with the AdSelectionManager.reportInteraction() method. To report an ad event:

  1. Initialize an AdSelectionManager object.
  2. Build a ReportInteractionRequest object with the ad selection ID, interaction key, interaction data, and reporting destination.
  3. Call the asynchronous reportInteraction() method with the request object and relevant Executor and OutcomeReceiver objects.
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);

Initialize the ReportInteractionRequest with the following required parameters:

  • Ad selection ID : An ad selection ID retrieved from a previously returned AdSelectionOutcome .
  • Interaction Key : A string key defined by the client describing the action being reported. This must match the key that was registered by the seller or buyer in the reporting JavaScript functions.
  • Interaction Data : A string containing data to be included with the event report, to be POSTed back to the reporting servers.
  • Reporting Destinations : A bit mask specifying if the events should be reported to the buyer, seller, or both. These flags are provided by the platform and the final destination mask can be created using bitwise operations. To report to one destination, you can use the flag provided by the platform directly. To report to multiple destinations, you can use the bitwise OR ( | ) to combine flag values.

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

  • The onResult() callback indicates the report interaction call is valid.
  • The onError() callback indicates the following possible conditions:
    • If the call is made when the app is running in the background, an IllegalStateException with a description of the failure is returned.
    • If the client is throttled from calling reportInteraction() , a LimitExceededException is returned.
    • If the package is not enrolled to call the Privacy Preserving APIs, a SecurityException() is returned.
    • If the app reporting interactions is different from the app that called selectAds() , an IllegalStateException is returned.
  • If the user has not consented to enable the Privacy Sandbox APIs, the call will fail silently.

Interaction reporting endpoints

The report interaction API issues HTTPS POST requests to endpoints provided by the sell-side platform and the winning buy-side platform. Protected Audience will match the interaction keys with the URIs declared in reporting JavaScript and issue a POST request to each endpoint for each interaction being reported. The content type of the request is plain text with the body being the Interaction Data.

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:

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:

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 currently 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 repo 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, please 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. Please 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)

Java

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, please 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)

Java

// 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 wish to override, in addition to the bidding logic and data you wish 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)

Java

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)

Java

// 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. A simple endpoint that returns 200 is sufficient for testing. The GitHub repo 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 a simple 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 .

Компонент Limit Description Limit Value
Custom audience (CA) Maximum number of ads per CA 100
Maximum number of CAs per application 1000
Maximum number of apps that can create a CA 1000
Maximum delay in the activation time of a CA from its creation time 60 дней
Maximum expiration time of a CA from its activation time 60 дней
Maximum number of CAs on device 4000
Maximum size of CA name 200 bytes
Maximum size of daily fetch URI 400 bytes
Maximum size of bidding logic URI 400 bytes
Maximum size of trusted bidding data 10 KB
Maximum size of user bidding signals 10 KB
Maximum call rate for leaveCustomAudience per buyer 1 per second
Maximum call rate for joinCustomAudience per buyer 1 per second
CA Background Fetch Connect timeout 5 seconds
HTTP read timeout 30 секунд
Maximum total download size 10 KB
Max duration of a fetch iteration 5 минут
Maximum number of CAs updated per job 1000
Ad Selection Maximum number of buyers подлежит уточнению
Maximum number of CAs per buyer подлежит уточнению
Maximum number of ads in an auction подлежит уточнению
Initial connection timeout 5 seconds
Connection read timeout 5 seconds
Maximum execution time of overall AdSelection 10 секунд
Maximum execution time of bidding per CA in AdSelection 5 second
Maximum execution time of scoring in AdSelection 5 second
Maximum execution time for per buyer in AdSelection подлежит уточнению
Maximum size of ad selection/seller/per buyer signals подлежит уточнению
Maximum size of seller/buyer scripts подлежит уточнению
Maximum call rate for selectAds 1 QPS
Impression reporting Minimum time before removing ad selection from persistence 24 часа
Maximum number of storage ad selections подлежит уточнению
Maximum size of reporting output URL подлежит уточнению
Maximum time for impression reporting подлежит уточнению
Maximum number of retries for notification calls подлежит уточнению
Тайм-аут соединения 5 seconds
Maximum overall execution time for reportImpression 2 секунды
Maximum call rate for reportImpressions 1 QPS
Event reporting Maximum number of beacons per buyer per auction 10

Maximum number of beacons per seller per auction

10

Maximum size of event key

40 bytes

Maximum size of event data

64KB

Объявления Maximum size of ad list 10 KB shared by all AdData in a single CA for contextual
URL-адреса Maximum length of any URL string taken as input подлежит уточнению
Javascript Maximum execution time 1 second for bidding and scoring for impression reporting
Maximum memory used 10 MB

Report bugs and issues

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.

{% verbatim %} {% endverbatim %} {% verbatim %} {% endverbatim %} ,

As you read through the Privacy Sandbox on Android documentation, use the Developer Preview or Beta button to select the program version that you're working with, as instructions may vary.


The Protected Audience API on Android (formerly known as FLEDGE) includes the Custom Audience API and the Ad Selection API. Ad tech platforms and advertisers can use these APIs to serve customized ads based on previous app engagement that limits the sharing of identifiers across apps and limits sharing a user's app interaction information with third-parties.

The Custom Audience API is centered around the "custom audience" abstraction, which represents a group of users with common intentions. An advertiser can register a user with a custom audience and associate relevant ads with it. This information is stored locally and can be used to inform advertiser bids, ad filtering, and ad rendering.

The Ad Selection API provides a framework that allows multiple developers to run an auction locally for a custom audience. To achieve this, the system considers relevant ads associated with the custom audience and performs additional processing on ads that an ad tech platform returns to the device.

Ad tech platforms can integrate these APIs to implement remarketing that preserves user privacy. Support for additional use cases, including app install ads, are planned for future releases. Learn more about the Protected Audience API on Android in the design proposal .

This guide describes how to work with the Protected Audience API on Android to do the following:

  1. Manage custom audiences
  2. Set up and run ad selection on a device
  3. Report ad impressions

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

Before you get started, complete the following:

  1. Set up your development environment for the Privacy Sandbox on Android.
  2. Either install a system image onto a supported device or set up an emulator that includes support for the Privacy Sandbox on Android.
  3. In a terminal, enable access to the Protected Audience API (disabled by default) with the following adb command.

      adb shell device_config put adservices ppapi_app_allow_list \"*\"
    
  4. In a terminal, enable beacon reporting with the following adb commands.

     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. Include an ACCESS_ADSERVICES_CUSTOM_AUDIENCE permission in your app manifest:

      <uses-permission android:name="android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE" />
    
  6. Reference an ad services configuration in the <application> element of your manifest:

      <property android:name="android.adservices.AD_SERVICES_CONFIG"
                android:resource="@xml/ad_services_config" />
    
  7. Specify the ad services XML resource referenced in your manifest, such as res/xml/ad_services_config.xml . Learn more about ad services permissions and SDK access control .

      <ad-services-config>
        <custom-audiences allowAllToAccess="true" />
      </ad-services-config>
    
  8. By default, the Ad Selection API enforces limits on the maximum amount of memory that an auction or impression reporting script can allocate. The memory limitation feature requires WebView version 105.0.5195.58 or higher. The platform enforces a version check and calls to the selectAds and reportImpression APIs fail if this isn't satisfied. There are two options to set this up:

    • Option 1: Run the following adb command to deactivate this check:

      adb device_config put fledge_js_isolate_enforce_max_heap_size false
      
    • Option 2: Install WebView Beta from the Google Play store. This must be equal to or higher than the version stated earlier.

Join a custom audience

A custom audience represents a group of users with common intentions or interests as decided by an advertiser app. An app or SDK may use a custom audience to indicate a particular audience, such as someone who has left items in a shopping cart. To create or join a custom audience asynchronously, do the following:

  1. Initialize the CustomAudienceManager object.
  2. Create a CustomAudience object by specifying key parameters such as the buyer's package and a relevant name. Then, initialize the JoinCustomAudienceRequest object with the CustomAudience object.
  3. Call the asynchronous joinCustomAudience() with the JoinCustomAudienceRequest object and relevant Executor and OutcomeReceiver objects.

Котлин

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)

Java

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

The combination of the following parameters uniquely identifies each CustomAudience object on a device:

  • owner : Package name of the owner app. This is implicitly set to the package name of the caller app.
  • buyer : Identifier for the buyer ad network which manages ads for this custom audience.
  • name : An arbitrary name or identifier for the custom audience.

Calling joinCustomAudience() repeatedly with a different instance of CustomAudience updates any existing CustomAudience with matching owner, buyer , and name parameters. To help preserve privacy, the result of the API does not distinguish between "creation" and "update."

Additionally, the CustomAudience must be created with these required parameters:

Optional parameters for a CustomAudience object may include:

  • Activation time : A custom audience can only participate in ad selection and daily updates after its activation time. This can be useful to engage lapsed users of an app, for example.
  • Expiration time : A future time after which the custom audience is removed from the device.
  • User bidding signals : A JSON string containing user signals, such as the user's preferred locale, that a buyer's bidding logic JavaScript consumes to generate bids during the ad selection process. This format helps ad tech platforms reuse code across platforms and eases the consumption in JavaScript functions.
  • Trusted bidding data : An HTTPS URL and a list of strings used during the ad selection process that fetch bidding signals from a trusted Key/Value service.
  • Ads : A list of AdData objects corresponding to the ads that participate in ad selection. Each AdData object consists of:
    • Render URL : An HTTPS URL that is queried to render the final ad.
    • Metadata : A JSON object serialized as a string containing information to be consumed by buyer bidding logic during the ad selection process.
    • Ad Filters : A class that contains all necessary information for app install ad filtering and frequency capping during ad selection.

Here's an example of a CustomAudience object instantiation:

Котлин

// 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()

Java

// 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();

Handle joinCustomAudience() outcomes

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

  • The onResult() callback signifies the custom audience is successfully created or updated.
  • The onError() callback signifies two possible conditions.

Here's an example of handling the outcome of 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)
    }
};

Java

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

Leave a custom audience

If the user no longer satisfies the business criteria for a given custom audience, an app or SDK can call leaveCustomAudience() to remove the custom audience from the device. To remove a CustomAudience based on its unique parameters, do the following:

  1. Initialize the CustomAudienceManager object.
  2. Initialize the LeaveCustomAudienceRequest with the custom audience's buyer and name . To learn more about these input fields, read " Join a custom audience ."
  3. Call the asynchronous leaveCustomAudience() method with the LeaveCustomAudienceRequest object and relevant Executor and OutcomeReceiver objects.

Котлин

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)

Java

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

Similar to calling joinCustomAudience() , the OutcomeReceiver signals the end of an API call. To help protect privacy, an error outcome doesn't distinguish between internal errors and invalid arguments. The onResult() callback is called when the API call has completed, whether or not a matching custom audience is removed successfully.

Run ad selection

To use the Protected Audience API to select ads, call the selectAds() method:

  1. Initialize an AdSelectionManager object.
  2. Build an AdSelectionConfig object.
  3. Call the asynchronous selectAds() method with the AdSelectionConfig object and relevant Executor and OutcomeReceiver objects.

Котлин

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
)

Java

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

The selectAds() method requires an AdSelectionConfig input, where you must specify the following required parameters:

  • Seller : Identifier for the seller ad network initiating the ad selection.
  • Decision logic URL : An HTTPS URL queried to obtain the seller ad network's JavaScript logic.
    • HTTPS URL : queried to obtain the seller ad network's JavaScript logic. See the required function signatures .
    • Prebuilt URI : that follows FLEDGE's ad selection format. IllegalArgumentException is thrown, if an unsupported or malformed prebuilt uri is passed.
  • Custom audience buyers : A full list of identifiers for buyer ad networks that are allowed by the seller to participate in the ad selection process. These buyer identifiers correspond to CustomAudience.getBuyer() of participating custom audiences.

The following parameters can be optionally specified for more customized ad selection:

  • Ad selection signals : A JSON object, serialized as a string, containing signals to be consumed by buyer bidding logic JavaScript fetched from CustomAudience.getBiddingLogicUrl() .
  • Seller signals : A JSON object, serialized as a string, containing signals consumed by the seller's fetched JavaScript decision logic from AdSelectionConfig.getDecisionLogicUrl() .
  • Per buyer signals : A map of JSON objects, serialized as strings, containing signals to be consumed by specific buyers' bidding logic JavaScript fetched from CustomAudience.getBiddingLogicUrl() , which are identified by the buyer fields of participating custom audiences.
  • Contextual ads: A collection of ad candidates that are collected directly from buyers during an auction that happens outside of a Protected Audience auction.

Once an ad is selected, the results, bids, and signals are persisted internally for reporting. The OutcomeReceiver.onResult() callback returns an AdSelectionOutcome that contains:

  • A render URL for the winning ad, obtained from AdData.getRenderUrl() .
  • An ad selection ID unique to the device user. This ID is used for reporting the ad impression.

If the ad selection can't be completed successfully due to reasons such as invalid arguments, timeouts, or excessive resource consumption, the OutcomeReceiver.onError() callback provides an AdServicesException with the following behaviors:

  • If the ad selection is initiated with invalid arguments, the AdServicesException indicates an IllegalArgumentException as the cause.
  • All other errors receive an AdServicesException with an IllegalStateException as the cause.

Contextual ads

Protected Audience can incorporate contextual ads into a Protected Auction. Contextual ads need to be selected on the ad tech server and returned to the device outside of Protected Audience APIs. Contextual ads can then be included in the auction using the AdSelectionConfig at which point they function the same as on device ads, including eligibility for negative ad filtering. Once the Protected Audience auction has completed, you need to invoke reportImpression() . This calls reportWin() in the winning contextual ad, in the same pattern as impression reporting , to receive the winning ad on a device. Each contextual ad needs a buyer, a bid, a link to reporting logic, a render URL, and ad metadata.

To deploy contextual ads in app, the target app needs to create a ContextualAds object:

Котлин

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

Java

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

The resulting ContextualAds object can then be passed along when creating your 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)

Java

// 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);

App install ad filtering

App install ads filtering helps you to filter installation ads for apps that are already installed on a device.

The first step in this process is to define which advertisers have the ability to filter on the installed package. This needs to happen in the app you want to target with an ad.

Котлин

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

Java

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

When the preceding code executes, the advertisers passed in are then able to filter out the installed apps that you specify during their bid generation. If you need to remove an advertiser from having access to this app's install status, run this code again with the advertiser's information removed.

The next step is to set up ad filtering inside the publisher app. The party that serves the ad inside of the publisher app (most likely to be a supply-side SDK) must initialize their AdFilters object with information about which ads related to apps they'd like to filter out:

Котлин

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

Java

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

Demand-side publishers may also set an AdFilter for ads that exist inside of their custom audiences.

AdFilters can also be passed in at the point of instantiating a new AdData object:

Котлин

// 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()

Java

// 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();

Frequency cap filtering

Frequency cap filtering enables ad techs to limit the number of times an ad is shown. Frequency cap filtering reduces ad overexposure and optimizes alternate ad selection for a given ad campaign.

There are two main components of a frequency cap filter: the ad event type, and the ad counter key. The available ad event types that can be used are:

  • Win : A win event indicates that the ad has won an auction. Win events are automatically updated by the Protected Audience API and cannot be called directly by the developer. Win data is only visible to ads within a given custom audience.
  • Impression : Separate from reportImpression , an on-device caller (SSP or MMP) uses updateAdCounterHistogram() to invoke impression events at the point in code they choose. Impression events are visible to all ads belonging to a given DSP, and are not limited to ads in the same custom audience.
  • View : Event is invoked by the on-device caller (SSP or MMP) at a point in code they choose using a call to updateAdCounterHistogram() . View events are visible to all ads belonging to a given DSP and not limited to ads in the same Custom Audience.
  • Click : Event is invoked by the on-device caller (SSP or MMP) at a point in code they choose using a call to updateAdCounterHistogram() . Click events are visible to all ads belonging to a given DSP and not limited to ads in the same Custom Audience.

In the publisher app, an SSP or MMP that has a presence on the device invokes ad events. When updateAdCounterHistogram() is called, the counter of a frequency cap filter is incremented so that future auctions will have up to date information about a user's exposure to a given ad. The ad event types are not forcibly tied to the corresponding user action and are guidelines given to help callers to structure their event system. To increment ad counters at the time of an event, the on-device actor provides the winning ad auction's ad selection ID.

Ad counter keys are arbitrary 32-bit signed integers assigned by a buyer ad tech, and they correspond to a given set of ads as defined by the DSP. Since ad counter keys are limited only to ads that belong to a given DSP, these keys can be selected without overlapping with histograms from another ad tech. Ad counter keys are used to increment DSP-specific identifiers across a DSP's ads or within a given custom audience to filter out ads from future auctions.

Counter keys can be leveraged to prioritize ads that are more likely to be interesting to a given user based on their interactions with other ads from a given buyer ad tech. For example, an ad that has received a high level of engagement from winning ad auctions, views, and clicks, represents an inferred data point. To further illustrate this point: an ad for left handed golf clubs might indicate that the user wouldn't be interested in right handed ones. A frequency cap filter set for a counter key assigned to left-handed ads could filter out ads for right handed clubs.

To use frequency capping in your auction, you must first create KeyedFrequencyCap objects as shown below:

Котлин

// 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()

Java

// 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();

Once the KeyedFrequencyCap objects are created, you can pass them into an AdFilters object.

Котлин

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

Java

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

When the AdFilters object is populated with frequency cap filters, it can be passed along when the custom audience is created:

Котлин

// 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()

Java

// 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();

When frequency cap filters are implemented into a custom audience, the SSP can then invoke the necessary click, view, or impression events.

Котлин

val callerAdTech: AdTechIdentifier = mAdSelectionConfig.getSeller()

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

Java

AdTechIdentifier callerAdTech = mAdSelectionConfig.getSeller();

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

Ads that have hit their pre-set frequency cap filter limits are filtered out of the auction. Filtering happens before the bidding logic is executed for on-device auctions, and as the payload is generating for Bidding & Auction services auctions.This toolkit gives ad techs the flexibility to use the interactions between users and the ads within their custom audiences to focus ad targeting while minimizing ad overexposure.

Contextual ad filtering without network calls

If there is no remarketing demand on the device, you can run ad selection for contextual ads without network calls. With prebuilt URIs and a list of contextual ads with bids, the platform can skip retrieving bidding logic, bidding signals, and scoring signals. The platform uses a prebuilt URI to select the contextual ad with the highest bid.

To improve latency, ad techs can run an ad selection flow that includes only contextual ads with ad filtering functionality without network calls. This is achieved by using prebuilt URIs for scoring signals. Refer to the Supported prebuilt URI use cases and names section for a list of scoreAds implementations.

To run ad selection without network calls:

  1. Set up ad filtering
  2. Create your contextual ads
  3. Create a AdSelectionConfig object with the following:

    1. An empty list of buyers
    2. A prebuilt URI to select the highest bid
    3. Contextual ads
    4. An empty URI for the scoring signals. The empty URI is allowed to indicate that you don't want to use the fetching of trusted signals for scoring:
    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. Run ad selection:

    adSelectionManager.selectAds(
        adSelectionConfig,
        executor,
        outcomeReceiver);
    

Run your own reporting JavaScript while using prebuilt URIs

Today, the Privacy Sandbox platform only has a basic reporting JavaScript implementation available for prebuilt URIs. If you want to run your own reporting JavaScript while still using prebuilt URIs for a low latency ad selection, you can override the DecisionLogicUri between ad selection and reporting runs.

  1. Run steps to run ad selection for contextual ads using prebuilt URIs
  2. Create a copy of your AdSelectionConfig before running reporting

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

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

Run waterfall mediation

Waterfall mediation requires multiple third party SDKs (3P networks) to be orchestrated by a first party SDK mediation network. Waterfall mediation is done the same way regardless if the auction took place on device or ran on Bidding & Auction services (B&A).

3P networks

3P networks need to provide an adapter that allows the mediation network to invoke the necessary methods for running an auction:

  • Run ad selection
  • Report impressions

Here's an example of a mediation network adapter:

Котлин

class NetworkAdaptor {
    private val adSelectionManager : AdSelectionManager

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

    fun selectAds() {...}

    fun reportImpressions() {...}
}

Java

class NetworkAdaptor {
    AdSelectionManager adSelectionManager;

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

    public void selectAds() {...}

    public void reportImpressions() {...}
}

Each SDK has their own ad selection service managers and clients, and their own selectAds and reportImpressions implementation. SDK providers can refer to the sections on how to run ad selection for on-device auctions or the B&A explainer for B&A auctions. Follow how to report ad impressions (following the single SSP impression reporting for reporting.

Mediation network

Similar to 3P networks, mediation networks need selectAds and reportImpression implementations. Refer to the sections on how to run ad selection and how to report ad impressions for more information.

Mediation networks are responsible for running the mediation chain and placing themselves in the mediation chain. The next section covers how to set up and execute this process.

Retrieve mediation chain and bid floors

The mediation network is responsible for retrieving the first party (1P) contextual ads, mediation chain, and third party networks' bid floors (3P). This can happen in a request to retrieve contextual ads executed by the mediation network. The mediation chain determines how to iterate through the 3P Networks, and the bid floors can be passed to the auction process as adSelectionSignals .

Network placement in the mediation chain

A mediation SDK can place itself in the mediation chain based on their live eCPM of 1P ad bids. In the Protected Audience API, ad bids are opaque. A mediation SDK should use AdSelectionFromOutcomesConfig to be able to compare a given 1P ad's bid to the bid floor of the next 3P network in the chain. If the 1P bid is higher than the bid floor then that means the mediation SDK is placed in front of that 3P network.

Run ad selection

To retrieve a 1P ad candidate, the mediation network can execute an on-device auction following the steps in the run ad selection section. This generates a 1P ad candidate, a bid, and an AdSelectionId that is used in the mediation process.

Create an AdSelectionFromOutcomesConfig

An AdSelectionFromOutcomesConfig allows the mediation network to pass a list of AdSelectionIds (results from previous auctions), ad selection signals, and a URI to fetch JavaScript that selects an ad from multiple candidates. The list of AdSelectionIds along with their bids and the signals are passed to the JavaScript which can return one of the AdSelectionIds if it beats the bid floor, or none if the mediation chain should continued.

Mediation Networks create an AdSelectionFromOutcomesConfig using the 1P AdSelectionId from the previous section, and the bid floor for the 3P Network being considered. A new AdSelectionFromOutcomesConfig should be created for each step in the mediation chain.

Котлин

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

Java

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

The selectAds() method override for waterfall mediation requires an AdSelectionFromOutcomesConfig input, where you must specify the following required parameters:

  • Seller : Identifier for the seller ad network initiating the ad selection.
  • AdSelectionIds : A singleton list of a previous selectAds() run for a 1P ad.
  • Ad selection signals : A JSON object, serialized as a string, containing signals to be used by buyer bidding logic. In this case, include the bid floor retrieved for the given 3P network.
  • Selection Logic URI : An HTTPS URL queried during ad selection to fetch the mediation network's JavaScript for selecting a winning ad. See the required function signatures in this JavaScript. The JavaScript should return the 3P ad if the bid is higher than the bid floor, or otherwise return null . This allows the mediation SDK to truncate the mediation chain when a winner is found.

With the AdSelectionOutcomesConfig created, call the selectAds() method of the 3P network that is first in the chain.

Котлин

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)

Java

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

Orchestrate waterfall mediation

The following is the order of operations for running through the mediation process.

  1. Run 1P ad selection.
  2. Iterate over the mediation chain. For each 3P network, do the following:
    1. Build AdSelectionFromOutcomeConfig including the 1P outcomeId and the 3P SDK's bid floor.
    2. Call selectAds() with the config from the previous step.
    3. If the result is not empty, return the ad.
    4. Call the current SDK network adapter's selectAds() method. If the result is not empty, return the ad.
  3. If no winner is found from the chain, return the 1P ad.

Котлин

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

Java

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) { ... }
}

Report ad impressions

There are two flows for reporting an ad impression depending on how the auction is run. If you are a single SSP running an auction, follow this section. If you are going to implement waterfall mediation, follow the steps found in the waterfall mediation impression reporting section .

Single SSP impression reporting

After a winning ad has been chosen from the ad selection workflow, you can report the impression back to participating buy-side and sell-side platforms with the AdSelectionManager.reportImpression() method. To report an ad impression:

  1. Initialize an AdSelectionManager object.
  2. Build a ReportImpressionRequest object with the ad selection ID.
  3. Call the asynchronous reportImpression() method with the ReportImpressionRequest object and relevant Executor and OutcomeReceiver objects.

Java

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)

Initialize the ReportImpressionRequest with the following required parameters:

  • Ad selection ID : An ID unique only to a device user that identifies a successful ad selection.
  • Ad selection config : The same configuration used in the selectAds() call identified by the provided ad selection ID.

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

  • The onResult() callback indicates if impression reporting URLs have been created and the request has been scheduled.
  • The onError() callback indicates the following possible conditions:
    • If the call is initialized with an invalid input argument, the AdServicesException indicates an IllegalArgumentException as the cause.
    • All other errors receive an AdServicesException with an IllegalStateException as the cause.

Waterfall mediation impression reporting

A mediation SDK needs to keep track of the winning SDK to trigger their reporting flows. The SDKs participating in a mediation chain should provide a method for the mediator to invoke to trigger their own reporting flow. An SDK participating in a mediated auction can follow the steps above to implement their own reporting.

SSPs can use this 3P SDK code example as a prototype for how to join in mediation flows:

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

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

Impression reporting endpoints

The report impression API issues HTTPS GET requests to endpoints provided by the sell-side platform and the winning buy-side platform:

Buy-side platform endpoint:

  • The API uses the Bidding logic URL specified in the custom audience to fetch the buyer-provided JavaScript that includes logic to return an impression reporting URL.
  • Invoke the reportWin() JavaScript function, which is expected to return the buyer's impression reporting URL.

Sell-side platform endpoint:

  • Use the Decision logic URL specified in the AdSelectionConfig object to fetch the seller's decision logic JavaScript.
  • Invoke the reportResult() JavaScript function, which is expected to return the seller's impression reporting URL.

Bidding & Auction services reporting

An auction executed on Bidding & Auction services will have all the necessary reporting information, including generated URLs for ad interaction reporting , included in the encrypted response from the server-side auction. When the response is decrypted, the appropriate URLs are registered with the platform, so ad and impression reporting follows the same steps listed above.

Best effort Impression reporting

The reportImpression() method is designed to offer a best-effort completion of reporting.

Report Ad Interactions

Protected Audience provides support to report on more granular interactions for a rendered ad. This can include interactions such as view time, clicks, hovers, or any other useful metric that can be collected. The process to receive these reports requires two steps. First, buyers and sellers must register to receive these reports in their reporting JavaScript. Then, the client will need to report these events.

Registering to receive interaction events

Registering for interaction events happens in the buyer's reportWin() and seller's reportResult() JavaScript functions using a JavaScript function provided by the platform: registerAdBeacon . To register to receive an event report, simply call the platform JavaScript Function from your reporting JavaScript. The following snippet is using a buyer's reportWin() , but the same approach applies to reportResult() .

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

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

    return reportingUri;
}

Reporting interaction events

After reporting an impression, clients can report the interactions back to previously registered winning buy-side and sell-side platforms with the AdSelectionManager.reportInteraction() method. To report an ad event:

  1. Initialize an AdSelectionManager object.
  2. Build a ReportInteractionRequest object with the ad selection ID, interaction key, interaction data, and reporting destination.
  3. Call the asynchronous reportInteraction() method with the request object and relevant Executor and OutcomeReceiver objects.
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);

Initialize the ReportInteractionRequest with the following required parameters:

  • Ad selection ID : An ad selection ID retrieved from a previously returned AdSelectionOutcome .
  • Interaction Key : A string key defined by the client describing the action being reported. This must match the key that was registered by the seller or buyer in the reporting JavaScript functions.
  • Interaction Data : A string containing data to be included with the event report, to be POSTed back to the reporting servers.
  • Reporting Destinations : A bit mask specifying if the events should be reported to the buyer, seller, or both. These flags are provided by the platform and the final destination mask can be created using bitwise operations. To report to one destination, you can use the flag provided by the platform directly. To report to multiple destinations, you can use the bitwise OR ( | ) to combine flag values.

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

  • The onResult() callback indicates the report interaction call is valid.
  • The onError() callback indicates the following possible conditions:
    • If the call is made when the app is running in the background, an IllegalStateException with a description of the failure is returned.
    • If the client is throttled from calling reportInteraction() , a LimitExceededException is returned.
    • If the package is not enrolled to call the Privacy Preserving APIs, a SecurityException() is returned.
    • If the app reporting interactions is different from the app that called selectAds() , an IllegalStateException is returned.
  • If the user has not consented to enable the Privacy Sandbox APIs, the call will fail silently.

Interaction reporting endpoints

The report interaction API issues HTTPS POST requests to endpoints provided by the sell-side platform and the winning buy-side platform. Protected Audience will match the interaction keys with the URIs declared in reporting JavaScript and issue a POST request to each endpoint for each interaction being reported. The content type of the request is plain text with the body being the Interaction Data.

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:

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:

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 currently 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 repo 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, please 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. Please 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)

Java

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, please 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)

Java

// 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 wish to override, in addition to the bidding logic and data you wish 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)

Java

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)

Java

// 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. A simple endpoint that returns 200 is sufficient for testing. The GitHub repo 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 a simple 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 .

Компонент Limit Description Limit Value
Custom audience (CA) Maximum number of ads per CA 100
Maximum number of CAs per application 1000
Maximum number of apps that can create a CA 1000
Maximum delay in the activation time of a CA from its creation time 60 дней
Maximum expiration time of a CA from its activation time 60 дней
Maximum number of CAs on device 4000
Maximum size of CA name 200 bytes
Maximum size of daily fetch URI 400 bytes
Maximum size of bidding logic URI 400 bytes
Maximum size of trusted bidding data 10 KB
Maximum size of user bidding signals 10 KB
Maximum call rate for leaveCustomAudience per buyer 1 per second
Maximum call rate for joinCustomAudience per buyer 1 per second
CA Background Fetch Connect timeout 5 seconds
HTTP read timeout 30 секунд
Maximum total download size 10 KB
Max duration of a fetch iteration 5 минут
Maximum number of CAs updated per job 1000
Ad Selection Maximum number of buyers подлежит уточнению
Maximum number of CAs per buyer подлежит уточнению
Maximum number of ads in an auction подлежит уточнению
Initial connection timeout 5 seconds
Connection read timeout 5 seconds
Maximum execution time of overall AdSelection 10 секунд
Maximum execution time of bidding per CA in AdSelection 5 second
Maximum execution time of scoring in AdSelection 5 second
Maximum execution time for per buyer in AdSelection подлежит уточнению
Maximum size of ad selection/seller/per buyer signals подлежит уточнению
Maximum size of seller/buyer scripts подлежит уточнению
Maximum call rate for selectAds 1 QPS
Impression reporting Minimum time before removing ad selection from persistence 24 часа
Maximum number of storage ad selections подлежит уточнению
Maximum size of reporting output URL подлежит уточнению
Maximum time for impression reporting подлежит уточнению
Maximum number of retries for notification calls подлежит уточнению
Тайм-аут соединения 5 seconds
Maximum overall execution time for reportImpression 2 секунды
Maximum call rate for reportImpressions 1 QPS
Event reporting Maximum number of beacons per buyer per auction 10

Maximum number of beacons per seller per auction

10

Maximum size of event key

40 bytes

Maximum size of event data

64KB

Объявления Maximum size of ad list 10 KB shared by all AdData in a single CA for contextual
URL-адреса Maximum length of any URL string taken as input подлежит уточнению
Javascript Maximum execution time 1 second for bidding and scoring for impression reporting
Maximum memory used 10 MB

Report bugs and issues

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.

{% verbatim %} {% endverbatim %} {% verbatim %} {% endverbatim %} ,

As you read through the Privacy Sandbox on Android documentation, use the Developer Preview or Beta button to select the program version that you're working with, as instructions may vary.