Руководство для разработчиков 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. Включите разрешение ACCESS_ADSERVICES_CUSTOM_AUDIENCE в манифест вашего приложения:

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

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

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

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

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

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

Примечание. Общий размер значений атрибутов «Пользовательские сигналы назначения ставок», «Доверенные данные назначения ставок» и «Объявления» не должен превышать 10 КБ. Эти три поля должны быть заполнены, чтобы пользовательская аудитория могла участвовать в выборе рекламы.

Вот пример создания экземпляра объекта 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() предназначен для максимально эффективного завершения создания отчетов.

Примечание:

• Если API не может определить URL-адреса отчетов о показах с помощью функций JavaScript, он вернет ошибку.
• Если вызов URL-адресов завершается неудачно, текущая версия Developer Preview не выдает никаких ошибок. Логика повторных попыток для временных сбоев запланирована в будущих выпусках.
• Многократные вызовы 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 должен включать следующие функции:

• 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 sellerSignals AdSelectionConfig

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

Примечание. Эта функция предоставлена ​​платформой Android и не должна реализована AD Tech.

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 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">

Примечание. Обязательно удалите 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 %}