Менеджер выбора объявлений

public class AdSelectionManager
extends Object

java.lang.Объект
↳ android.adservices.adselection.AdSelectionManager

AdSelection Manager предоставляет API для приложений и рекламных SDK для запуска процессов выбора объявлений, а также для составления отчетов о показах.

Краткое содержание

Публичные методы

static AdSelectionManager get ( Context context)

Фабричный метод для создания экземпляра AdSelectionManager.

void getAdSelectionData ( GetAdSelectionDataRequest request, Executor executor, OutcomeReceiver < GetAdSelectionDataOutcome , Exception > receiver)

Собирает данные об индивидуальной аудитории с устройства.

TestAdSelectionManager getTestAdSelectionManager ()
void persistAdSelectionResult ( PersistAdSelectionResultRequest request, Executor executor, OutcomeReceiver < AdSelectionOutcome , Exception > receiver)

Сохраняет результаты выбора объявлений со стороны сервера.

void reportEvent ( ReportEventRequest request, Executor executor, OutcomeReceiver < Object , Exception > receiver)

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

void reportImpression ( ReportImpressionRequest request, Executor executor, OutcomeReceiver < Object , Exception > receiver)

Уведомляет службу о новом показе объявления, выбранного в ходе отбора объявлений, определенного adSelectionId .

void selectAds ( AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig, Executor executor, OutcomeReceiver < AdSelectionOutcome , Exception > receiver)

Выбирает объявление из результатов ранее выбранных объявлений.

void selectAds ( AdSelectionConfig adSelectionConfig, Executor executor, OutcomeReceiver < AdSelectionOutcome , Exception > receiver)

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

void updateAdCounterHistogram ( UpdateAdCounterHistogramRequest updateAdCounterHistogramRequest, Executor executor, OutcomeReceiver < Object , Exception > outcomeReceiver)

Обновляет гистограммы счетчиков для объявления, которое ранее было выбрано с помощью вызова selectAds(android.adservices.adselection.AdSelectionConfig, java.util.concurrent.Executor, android.os.OutcomeReceiver) .

Унаследованные методы

Публичные методы

получать

public static AdSelectionManager get (Context context)

Фабричный метод для создания экземпляра AdSelectionManager.

Параметры
context Context : используемый Context . Это значение не может быть null .

Возврат
AdSelectionManager Экземпляр AdSelectionManager . Это значение не может быть null .

getAdSelectionData

public void getAdSelectionData (GetAdSelectionDataRequest request, 
                Executor executor, 
                OutcomeReceiver<GetAdSelectionDataOutcome, Exception> receiver)

Собирает данные об индивидуальной аудитории с устройства. Возвращает сжатый и зашифрованный большой двоичный объект для отправки на серверы аукционов для выбора объявления. Для получения более подробной информации посетите раздел «Объяснение услуг по проведению торгов и аукционов» .

Чтобы объявления с индивидуальной аудиторией могли быть собраны, они должны иметь ad_render_id .

См. AdSelectionManager#persistAdSelectionResult чтобы узнать, как обрабатывать результаты выбора объявлений, выполняемого на стороне сервера, с помощью большого двоичного объекта, созданного этим API.

Выходные данные передаются получателем, который либо возвращает GetAdSelectionDataOutcome для успешного выполнения, либо Exception включает тип выданного исключения и соответствующее сообщение об ошибке.

Если выдается IllegalArgumentException , это вызвано недопустимым входным аргументом, полученным API для запуска выбора объявления.

Если IllegalStateException выдается с сообщением об ошибке «Сбой служб AdSelection.», это вызвано внутренним сбоем службы выбора объявлений.

Если выдается TimeoutException , оно возникает, когда во время торгов, оценки или общего процесса выбора для поиска выигрышного объявления возникает тайм-аут.

Если выдается LimitExceededException , оно возникает, когда вызывающий пакет превышает допустимые пределы скорости и регулируется.

Если выдается SecurityException , это вызвано тем, что вызывающий объект не авторизован или разрешение не запрошено.
Требуется AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE .

Параметры
request GetAdSelectionDataRequest : это значение не может быть null .

executor Executor : Это значение не может быть null . События обратного вызова и прослушивателя отправляются через этот Executor , предоставляя простой способ контролировать, какой поток используется. Чтобы отправлять события через основной поток вашего приложения, вы можете использовать Context.getMainExecutor() . В противном случае предоставьте Executor , который отправляет данные в соответствующий поток.

receiver OutcomeReceiver : это значение не может быть null .

getTestAdSelectionManager

public TestAdSelectionManager getTestAdSelectionManager ()

Возврат
TestAdSelectionManager Это значение не может быть null .

persistAdSelectionResult

public void persistAdSelectionResult (PersistAdSelectionResultRequest request, 
                Executor executor, 
                OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

Сохраняет результаты выбора объявлений со стороны сервера. Для получения более подробной информации посетите раздел «Объяснение услуг по торгам и аукционам».

См. AdSelectionManager#getAdSelectionData чтобы узнать, как создать зашифрованный большой двоичный объект для запуска выбора объявлений на стороне сервера.

Выходные данные передаются получателем, который либо возвращает AdSelectionOutcome для успешного запуска, либо Exception включает тип выброшенного исключения и соответствующее сообщение об ошибке.

Если выдается IllegalArgumentException , это вызвано недопустимым входным аргументом, полученным API для запуска выбора объявления.

Если IllegalStateException выдается с сообщением об ошибке «Сбой служб AdSelection.», это вызвано внутренним сбоем службы выбора объявлений.

Если выдается TimeoutException , оно возникает, когда во время торгов, оценки или общего процесса выбора для поиска выигрышного объявления возникает тайм-аут.

Если выдается LimitExceededException , оно возникает, когда вызывающий пакет превышает допустимые пределы скорости и регулируется.

Если выдается SecurityException , это вызвано тем, что вызывающий объект не авторизован или разрешение не запрошено.
Требуется AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE .

Параметры
request PersistAdSelectionResultRequest : это значение не может быть null .

executor Executor : Это значение не может быть null . События обратного вызова и прослушивателя отправляются через этот Executor , предоставляя простой способ контролировать, какой поток используется. Чтобы отправлять события через основной поток вашего приложения, вы можете использовать Context.getMainExecutor() . В противном случае предоставьте Executor , который отправляет данные в соответствующий поток.

receiver OutcomeReceiver : это значение не может быть null .

отчетСобытие

public void reportEvent (ReportEventRequest request, 
                Executor executor, 
                OutcomeReceiver<Object, Exception> receiver)

Уведомляет службу о новом рекламном событии, о котором необходимо сообщить для объявления, выбранного в ходе выполнения выбора объявлений, определенного adSelectionId . Рекламное событие — это любое событие, которое происходит с объявлением, связанным с данным adSelectionId . Нет никакой гарантии относительно того, когда будет сообщено о рекламном событии. Отчеты о событиях могут быть отложены, а отчеты могут быть пакетными.

Используя ReportEventRequest#getKey() , служба получит reportingUri , который был зарегистрирован в registerAdBeacon . Дополнительную информацию о registerAdBeacon см. в документации reportImpression(ReportImpressionRequest, Executor, OutcomeReceiver) . Затем служба прикрепит ReportEventRequest#getData() к телу запроса POST и отправит запрос. Тело запроса POST будет иметь content-type text/plain , а данные будут передаваться в charset=UTF-8 .

Выходные данные передаются получателем, который либо возвращает пустой Object для успешного выполнения, либо Exception включает тип выброшенного исключения и соответствующее сообщение об ошибке.

Если выдается IllegalArgumentException , это вызвано недопустимым входным аргументом, полученным API для сообщения о рекламном событии.

Если IllegalStateException выдается с сообщением об ошибке «Сбой служб AdSelection.», это вызвано внутренним сбоем службы выбора объявлений.

Если выдается LimitExceededException , оно возникает, когда вызывающий пакет превышает допустимые пределы скорости и регулируется.

Если выдается SecurityException , это вызвано тем, что вызывающий объект не авторизован или разрешение не запрошено.

О событиях будет сообщено не более одного раза, при этом мы приложим все усилия.
Требуется AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE .

Параметры
request ReportEventRequest : это значение не может быть null .

executor Executor : Это значение не может быть null .

receiver OutcomeReceiver : это значение не может быть null .

отчет о показе

public void reportImpression (ReportImpressionRequest request, 
                Executor executor, 
                OutcomeReceiver<Object, Exception> receiver)

Уведомляет службу о новом показе объявления, выбранного в ходе отбора объявлений, определенного adSelectionId . Нет никаких гарантий относительно того, когда будет сообщено о показе. Отчеты о впечатлениях могут быть отложены, а отчеты могут быть пакетными.

Чтобы вычислить URL-адрес отчета о выигравшем продавце, служба извлекает логику JavaScript продавца из AdSelectionConfig#getDecisionLogicUri() найденного в ReportImpressionRequest.getAdSelectionConfig() . Затем служба выполняет одну из функций, найденных в JS продавца, под названием reportResult , предоставляя сигналы на устройстве, а также ReportImpressionRequest#getAdSelectionConfig() в качестве входных параметров.

Определение функции 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 } }; }

Чтобы вычислить URL-адрес отчета о выигравшем покупателе, служба извлекает логику JavaScript выигравшего покупателя, которая извлекается через CustomAudience.getBiddingLogicUri() покупателя. Затем служба выполняет одну из функций, найденных в JS покупателя, называемую reportWin , предоставляя сигналы на устройстве, signals_for_buyer , рассчитанные с помощью reportResult , и определенные поля из ReportImpressionRequest#getAdSelectionConfig() в качестве входных параметров.

Определение функции reportWin :

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

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

Определение функции registerBeacon :

function registerAdBeacon(beacons) , где beacons — это набор пар строк и строк.

Для каждого рекламного события, о котором покупатель/продавец заинтересованы в отчетах, они добавляют пару event_key : event_reporting_uri в словарь beacons , где event_key — это идентификатор этого конкретного события. Этот event_key должен соответствовать ReportEventRequest#getKey() когда SDK вызывает reportEvent(ReportEventRequest, Executor, OutcomeReceiver) . Кроме того, каждый event_reporting_uri должен правильно анализироваться в Uri . Это будет Uri , о котором будет сообщаться, когда SDK вызывает reportEvent(ReportEventRequest, Executor, OutcomeReceiver) .

Когда покупатель/продавец добавил все пары, для которых они хотят получать события, они могут вызвать registerAdBeacon(beacons) , где beacons — это имя словаря, в который они добавили пары.

registerAdBeacon выдаст TypeError в следующих ситуациях:

  1. registerAdBeacon вызывается более одного раза. Если эта ошибка обнаружена в reportWin/reportResult, будет зарегистрирован исходный набор пар.
  2. registerAdBeacon не имеет ровно 1 аргумента dict.
  3. Содержимое аргумента 1 dict не является всеми парами String: String .

Выходные данные передаются receiver , который либо возвращает пустой Object для успешного выполнения, либо Exception включает тип выброшенного исключения и соответствующее сообщение об ошибке.

Если выдается IllegalArgumentException , это вызвано недопустимым входным аргументом, полученным API для отчета о показе.

Если IllegalStateException выдается с сообщением об ошибке «Сбой служб AdSelection.», это вызвано внутренним сбоем службы выбора объявлений.

Если выдается LimitExceededException , оно возникает, когда вызывающий пакет превышает допустимые пределы скорости и регулируется.

Если выдается SecurityException , это вызвано тем, что вызывающий объект не авторизован или разрешение не запрошено.

О показах будет сообщено не более одного раза, как попытка сделать все возможное.
Требуется AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE .

Параметры
request ReportImpressionRequest : это значение не может быть null .

executor Executor : Это значение не может быть null .

receiver OutcomeReceiver : это значение не может быть null .

выберитеОбъявления

public void selectAds (AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig, 
                Executor executor, 
                OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

Выбирает объявление из результатов ранее выбранных объявлений.

Входные данные adSelectionFromOutcomesConfig предоставляются Ads SDK, а объект AdSelectionFromOutcomesConfig передается через вызов Binder. По этой причине общий размер этих объектов ограничен ограничениями Android IPC. Если не удалось передать AdSelectionFromOutcomesConfig будет выдано исключение TransactionTooLargeException .

Выходные данные передаются получателем, который либо возвращает AdSelectionOutcome для успешного запуска, либо Exception включает тип выброшенного исключения и соответствующее сообщение об ошибке.

Входные данные adSelectionFromOutcomesConfig содержат:

  • Seller должен иметь зарегистрированный AdTechIdentifier . В противном случае будет выброшено IllegalStateException .
  • List of ad selection ids должен существовать и поступать из вызовов selectAds(AdSelectionConfig, Executor, OutcomeReceiver) исходящих из того же приложения. В противном случае IllegalArgumentException для проверки ввода приведет к появлению идентификаторов выбора объявлений, нарушающих список.
  • Selection logic URI , который может следовать либо HTTPS, либо предварительно созданным схемам выбора объявлений.

    Если URI соответствует схеме HTTPS, хост должен соответствовать seller . В противном случае будет выброшено IllegalArgumentException .

    Предварительно созданные URI — это способ замены общей предварительно созданной логики для необходимых JavaScript-кодов для selectOutcome . Далее должен следовать предварительно созданный Uri для этой конечной точки;

    • ad-selection-prebuilt://ad-selection-from-outcomes/<name>?<script-generation-parameters>

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

    См. AdSelectionFromOutcomesConfig.Builder#setSelectionLogicUri для поддерживаемых <name> и обязательных <script-generation-parameters> .

Если выдается IllegalArgumentException , это вызвано недопустимым входным аргументом, полученным API для запуска выбора объявления.

Если IllegalStateException выдается с сообщением об ошибке «Сбой служб AdSelection.», это вызвано внутренним сбоем службы выбора объявлений.

Если выдается TimeoutException , оно возникает, когда во время торгов, оценки или общего процесса выбора для поиска выигрышного объявления возникает тайм-аут.

Если выдается LimitExceededException , оно возникает, когда вызывающий пакет превышает допустимые пределы скорости и регулируется.

Если выдается SecurityException , это вызвано тем, что вызывающий объект не авторизован или разрешение не запрошено.
Требуется AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE .

Параметры
adSelectionFromOutcomesConfig AdSelectionFromOutcomesConfig : это значение не может быть null .

executor Executor : Это значение не может быть null . События обратного вызова и прослушивателя отправляются через этот Executor , предоставляя простой способ контролировать, какой поток используется. Чтобы отправлять события через основной поток вашего приложения, вы можете использовать Context.getMainExecutor() . В противном случае предоставьте Executor , который отправляет данные в соответствующий поток.

receiver OutcomeReceiver : это значение не может быть null .

выберитеОбъявления

Добавлено на уровне API 34.
public void selectAds (AdSelectionConfig adSelectionConfig, 
                Executor executor, 
                OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

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

Входные данные adSelectionConfig предоставляются Ads SDK, а объект AdSelectionConfig передается через вызов Binder. По этой причине общий размер этих объектов ограничен ограничениями Android IPC. Если не передать AdSelectionConfig будет выдано исключение TransactionTooLargeException .

Входной файл adSelectionConfig содержит Decision Logic Uri , который может следовать либо HTTPS, либо предварительно созданным схемам выбора объявлений.

Если URI соответствует схеме HTTPS, хост должен соответствовать seller . В противном случае будет выброшено IllegalArgumentException .

Предварительно созданные URI — это способ замены требуемых сценариев JavaScript для scoreAds на общую предварительно созданную логику. Далее должен следовать предварительно созданный Uri для этой конечной точки;

  • ad-selection-prebuilt://ad-selection/<name>?<script-generation-parameters>

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

См. AdSelectionConfig.Builder#setDecisionLogicUri для получения информации о поддерживаемых <name> и обязательных <script-generation-parameters> .

Выходные данные передаются получателем, который либо возвращает AdSelectionOutcome для успешного запуска, либо Exception включает тип выброшенного исключения и соответствующее сообщение об ошибке.

Если выдается IllegalArgumentException , это вызвано недопустимым входным аргументом, полученным API для запуска выбора объявления.

Если IllegalStateException выдается с сообщением об ошибке «Сбой служб AdSelection», это вызвано внутренним сбоем службы выбора объявлений.

Если выдается TimeoutException , оно возникает, когда во время торгов, оценки или общего процесса выбора для поиска выигрышного объявления возникает тайм-аут.

Если выдается LimitExceededException , оно возникает, когда вызывающий пакет превышает допустимые пределы скорости и регулируется.

Если выдается SecurityException , это вызвано тем, что вызывающий объект не авторизован или разрешение не запрошено.
Требуется AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE .

Параметры
adSelectionConfig AdSelectionConfig : это значение не может быть null .

executor Executor : Это значение не может быть null . События обратного вызова и прослушивателя отправляются через этот Executor , предоставляя простой способ контролировать, какой поток используется. Чтобы отправлять события через основной поток вашего приложения, вы можете использовать Context.getMainExecutor() . В противном случае предоставьте Executor , который отправляет данные в соответствующий поток.

receiver OutcomeReceiver : это значение не может быть null .

обновить гистограмму AdCounter

public void updateAdCounterHistogram (UpdateAdCounterHistogramRequest updateAdCounterHistogramRequest, 
                Executor executor, 
                OutcomeReceiver<Object, Exception> outcomeReceiver)

Обновляет гистограммы счетчиков для объявления, которое ранее было выбрано вызовом selectAds(android.adservices.adselection.AdSelectionConfig, java.util.concurrent.Executor, android.os.OutcomeReceiver) .

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

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

SecurityException возвращается через outcomeReceiver , если:

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

LimitExceededException возвращается через outcomeReceiver , если вызов превышает ограничение API вызывающего приложения.

Во всех остальных случаях сбоя outcomeReceiver вернет пустой Object . Обратите внимание, что для защиты конфиденциальности пользователей внутренние ошибки не будут отправляться обратно через исключение.
Требуется AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE .

Параметры
updateAdCounterHistogramRequest UpdateAdCounterHistogramRequest : это значение не может быть null .

executor Executor : Это значение не может быть null . События обратного вызова и прослушивателя отправляются через этот Executor , предоставляя простой способ контролировать, какой поток используется. Чтобы отправлять события через основной поток вашего приложения, вы можете использовать Context.getMainExecutor() . В противном случае предоставьте Executor , который отправляет данные в соответствующий поток.

outcomeReceiver OutcomeReceiver : это значение не может быть null .