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

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

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

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

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

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

В этом руководстве описывается, как работать с 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 Beta из магазина 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 логики ставок : HTTPS URL, запрашиваемый во время выбора рекламы для извлечения логики ставок JavaScript покупателя. См. требуемые сигнатуры функций в этом JavaScript.
• Ad Render IDs : произвольный ID, установленный покупателем ad tech. Это оптимизация для генерации полезной нагрузки для B&A .

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

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

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

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

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

Обработка результатов joinCustomAudience()

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Выполнить выбор объявления

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

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

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

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

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

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

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

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

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

• Продавец : идентификатор рекламной сети продавца, инициировавшей выбор рекламы.
• URL логики принятия решения : HTTPS-URL, запрашиваемый для получения логики JavaScript рекламной сети продавца.
  • HTTPS URL : запрашивается для получения логики JavaScript рекламной сети продавца. См. требуемые сигнатуры функций .
  • Предварительно созданный URI : соответствует формату выбора рекламы FLEDGE. Исключение IllegalArgumentException выдается, если передается неподдерживаемый или неправильно сформированный предварительный URI.
• Custom auditor buyers : Полный список идентификаторов для рекламных сетей покупателей, которым продавец разрешает участвовать в процессе выбора рекламы. Эти идентификаторы покупателей соответствуют 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 .

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

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

В приложении издателя 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();

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

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

Запустите каскадную медиацию

Для посредничества Waterfall требуется несколько сторонних SDK (3P-сетей), которые должны быть организованы сетью посредничества SDK первой стороны. Посредничество Waterfall выполняется одинаково, независимо от того, проводился ли аукцион на устройстве или на сервисах торгов и аукционов (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. Следуйте инструкциям по составлению отчетов о показах рекламы (следуя единому отчету о показах SSP для отчетности).

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

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

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

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

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

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

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

Выполнить выбор объявления

Чтобы получить кандидата на рекламу 1P, сеть посредничества может провести аукцион на устройстве, следуя шагам в разделе «Выбор рекламы» . Это генерирует кандидата на рекламу 1P, ставку и AdSelectionId , который используется в процессе посредничества.

Создайте AdSelectionFromOutcomesConfig

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

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

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

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

class MediationNetwork {
    AdSelectionManager adSelectionManager;

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

    public void runAdSelection() {...}

    public void reportImpressions() {...}

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

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

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

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

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

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

Отчет о показах отдельных SSP

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

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

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

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

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

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

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

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

Инициализируйте ReportImpressionRequest со следующими обязательными параметрами:

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

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

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

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

Посреднический 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-адрес отчета о показах продавца.

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

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

Отчет о максимальном впечатлении

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

Отчет о взаимодействии с рекламой

Protected Audience обеспечивает поддержку для создания отчетов о более детальных взаимодействиях для отображаемой рекламы. Это может включать такие взаимодействия, как время просмотра, клики, наведения или любые другие полезные показатели, которые можно собрать. Процесс получения этих отчетов состоит из двух этапов. Во-первых, покупатели и продавцы должны зарегистрироваться для получения этих отчетов в своем отчетном 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 .
• Interaction Key : строковый ключ, определенный клиентом, описывающий сообщаемое действие. Он должен соответствовать ключу, зарегистрированному продавцом или покупателем в функциях JavaScript для отчетности.
• Данные взаимодействия : строка, содержащая данные, которые необходимо включить в отчет о событии и отправить обратно на серверы отчетов.
• Reporting Destinations : Битовая маска, указывающая, следует ли сообщать о событиях покупателю, продавцу или обоим. Эти флаги предоставляются платформой, а конечную маску назначения можно создать с помощью побитовых операций. Чтобы отправить отчет в один пункт назначения, вы можете напрямую использовать флаг, предоставленный платформой. Чтобы отправить отчет в несколько пунктов назначения, вы можете использовать побитовое ИЛИ ( | ) для объединения значений флагов.

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

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

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

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

Лучший отчет о взаимодействии

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 должен включать следующие функции:

• generateBid()
• reportWin()

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

• scoreAd()
• reportResult()

GenerateBid ()

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

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

• 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 selectAds(AdSelectionFromOutcomesConfig) ad-selection-from-outcomes .

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

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

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

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

Ограничения

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

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

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