Se agregó en el nivel de API 34.
También se agregó en Extensiones de servicios de anuncios 4.

AdSelectionManager

public class AdSelectionManager
extends Object

java.lang.Object.
   ↳ android.adservices.adselection.AdSelectionManager,


AdSelection Manager proporciona APIs para SDK de anuncios y de apps para ejecutar procesos de selección de anuncios y también informar impresiones.

Resumen

Métodos públicos

static AdSelectionManager get(Context context)

Método de fábrica para crear una instancia de AdSelectionManager.

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

Recopila datos del público personalizado del dispositivo.

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

Conserva los resultados de la selección de anuncios del servidor.

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

Le notifica al servicio que hay un nuevo evento de anuncio que informar para el anuncio seleccionado en la ejecución de selección de anuncios que identifica adSelectionId.

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

Le notifica al servicio que hay una impresión nueva que informar para el anuncio seleccionado en la ejecución de selección de anuncios que identifica adSelectionId.

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

Selecciona un anuncio de los resultados de selecciones de anuncios ejecutadas anteriormente.

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

Ejecuta el proceso de selección de anuncios en el dispositivo a fin de seleccionar un anuncio de remarketing para la aplicación que realiza la llamada.

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

Actualiza los histogramas de contador de un anuncio que se seleccionaba anteriormente mediante una llamada a selectAds(android.adservices.adselection.AdSelectionConfig, java.util.concurrent.Executor, android.os.OutcomeReceiver).

Métodos heredados

Métodos públicos

get

public static AdSelectionManager get (Context context)

Método de fábrica para crear una instancia de AdSelectionManager.

Parámetros
context Context: El Context que se usará. Este valor no puede ser null.

Devuelve
AdSelectionManager Una instancia de AdSelectionManager. Este valor no puede ser null.

getAdSelectionData.

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

Recopila datos del público personalizado del dispositivo. Muestra un BLOB comprimido y encriptado que se enviará a los servidores de subastas para la selección de anuncios. Para obtener más detalles, visita la Explicación de los servicios de ofertas y subastas.

Los anuncios de público personalizado deben tener un ad_render_id para que se puedan recopilar.

Consulta AdSelectionManager#persistAdSelectionResult para obtener información sobre cómo procesar los resultados de la selección de anuncios ejecutada en el servidor con el BLOB que genera esta API.

El receptor pasa el resultado, que muestra un GetAdSelectionDataOutcome para una ejecución correcta, o un Exception incluye el tipo de excepción que se arrojó y el mensaje de error correspondiente.

Si se arroja la IllegalArgumentException, se debe a un argumento de entrada no válido que la API recibió para ejecutar la selección de anuncios.

Si se muestra IllegalStateException con el mensaje de error "Falla de los servicios de AdSelection", se debe a una falla interna del servicio de selección de anuncios.

Si se arroja TimeoutException, se produce cuando se encuentra un tiempo de espera durante la oferta, la puntuación o el proceso de selección general para encontrar el anuncio ganador.

Si se arroja la LimitExceededException, se produce cuando el paquete de llamada supera los límites de frecuencia permitidos y se limita.

Si se arroja la SecurityException, se produce cuando el emisor no está autorizado o no se solicita el permiso.
Requiere AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

Parámetros
request GetAdSelectionDataRequest: Este valor no puede ser null.

executor Executor: Este valor no puede ser null. Los eventos de devolución de llamada y de objetos de escucha se envían a través de este Executor, lo que proporciona una manera fácil de controlar qué subproceso se usa. Para enviar eventos a través del subproceso principal de tu aplicación, puedes usar Context.getMainExecutor(). De lo contrario, proporciona un Executor que se envíe al subproceso correspondiente.

receiver OutcomeReceiver: Este valor no puede ser null.

getTestAdSelectionManager.

Se agregó en el nivel de API 34.
También se agregó en Extensiones de servicios de anuncios 4.
public TestAdSelectionManager getTestAdSelectionManager ()

Devuelve
TestAdSelectionManager Este valor no puede ser null.

persistenteAdSelectionResult

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

Conserva los resultados de la selección de anuncios del servidor. Para obtener más detalles, visita la Explicación de los servicios de ofertas y subastas

Consulta AdSelectionManager#getAdSelectionData para obtener información sobre cómo generar un BLOB encriptado a fin de ejecutar una selección de anuncios en el servidor.

El receptor pasa el resultado, que muestra un AdSelectionOutcome para una ejecución correcta, o un Exception incluye el tipo de excepción que se arrojó y el mensaje de error correspondiente.

Si se arroja la IllegalArgumentException, se debe a un argumento de entrada no válido que la API recibió para ejecutar la selección de anuncios.

Si se muestra IllegalStateException con el mensaje de error "Falla de los servicios de AdSelection", se debe a una falla interna del servicio de selección de anuncios.

Si se arroja TimeoutException, se produce cuando se encuentra un tiempo de espera durante la oferta, la puntuación o el proceso de selección general para encontrar el anuncio ganador.

Si se arroja la LimitExceededException, se produce cuando el paquete de llamada supera los límites de frecuencia permitidos y se limita.

Si se arroja la SecurityException, se produce cuando el emisor no está autorizado o no se solicita el permiso.
Requiere AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

Parámetros
request PersistAdSelectionResultRequest: Este valor no puede ser null.

executor Executor: Este valor no puede ser null. Los eventos de devolución de llamada y de objetos de escucha se envían a través de este Executor, lo que proporciona una manera fácil de controlar qué subproceso se usa. Para enviar eventos a través del subproceso principal de tu aplicación, puedes usar Context.getMainExecutor(). De lo contrario, proporciona un Executor que se envíe al subproceso correspondiente.

receiver OutcomeReceiver: Este valor no puede ser null.

Evento de informe

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

Le notifica al servicio que hay un nuevo evento de anuncio que informar para el anuncio seleccionado en la ejecución de selección de anuncios que identifica adSelectionId. Un evento de anuncio es cualquier caso que ocurre con un anuncio asociado con un adSelectionId determinado. No hay garantía de cuándo se informará el evento de anuncio. Los informes de eventos podrían retrasarse y los informes se podrían agrupar en lotes.

Con ReportEventRequest#getKey(), el servicio recuperará el reportingUri que se registró en registerAdBeacon. Consulta la documentación de reportImpression(ReportImpressionRequest, Executor, OutcomeReceiver) para obtener más detalles sobre registerAdBeacon. Luego, el servicio adjuntará ReportEventRequest#getData() al cuerpo de una solicitud POST y la enviará. El cuerpo de la solicitud POST tendrá el content-type de text/plain, y los datos se transmitirán en charset=UTF-8.

El receptor pasa el resultado, que muestra un Object vacío para una ejecución correcta, o un Exception incluye el tipo de excepción que se arrojó y el mensaje de error correspondiente.

Si se arroja la IllegalArgumentException, se debe a un argumento de entrada no válido que la API recibió para informar el evento del anuncio.

Si se muestra IllegalStateException con el mensaje de error "Falla de los servicios de AdSelection", se debe a una falla interna del servicio de selección de anuncios.

Si se arroja la LimitExceededException, se produce cuando el paquete de llamada supera los límites de frecuencia permitidos y se limita.

Si se arroja la SecurityException, se produce cuando el emisor no está autorizado o no se solicita el permiso.

Los eventos se informarán, como máximo, una vez como el mejor esfuerzo posible.
Requiere AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

Parámetros
request ReportEventRequest: Este valor no puede ser null.

executor Executor: Este valor no puede ser null.

receiver OutcomeReceiver: Este valor no puede ser null.

ReportImpression

Se agregó en el nivel de API 34.
También se agregó en Extensiones de servicios de anuncios 4.
public void reportImpression (ReportImpressionRequest request, 
                Executor executor, 
                OutcomeReceiver<ObjectException> receiver)

Le notifica al servicio que hay una impresión nueva que informar para el anuncio seleccionado en la ejecución de selección de anuncios que identifica adSelectionId. No hay garantía de cuándo se informará la impresión. Los informes de impresiones podrían retrasarse, y los informes se podrían agrupar en lotes.

Para calcular la URL de informes del vendedor ganadora, el servicio recupera la lógica de JavaScript del vendedor a partir del elemento AdSelectionConfig#getDecisionLogicUri() que se encuentra en ReportImpressionRequest.getAdSelectionConfig(). Luego, el servicio ejecuta una de las funciones que se encuentran en el JS del vendedor, llamada reportResult, y proporciona indicadores en el dispositivo, así como ReportImpressionRequest#getAdSelectionConfig() como parámetros de entrada.

La definición de la función de reportResult es la siguiente:

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

Para calcular la URL de los informes del comprador ganador, el servicio recupera la lógica de JavaScript del comprador ganador, que se obtiene a través del objeto CustomAudience.getBiddingLogicUri() del comprador. Luego, el servicio ejecuta una de las funciones que se encuentran en el JS del comprador, llamada reportWin, y proporciona indicadores en el dispositivo, signals_for_buyer calculado por reportResult y campos específicos de ReportImpressionRequest#getAdSelectionConfig() como parámetros de entrada.

La definición de la función de reportWin es la siguiente:

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

Además, los compradores y vendedores tienen la opción de registrarse para recibir informes sobre eventos de anuncios específicos. Para ello, pueden invocar la función registerAdBeacon proporcionada por la plataforma dentro de reportWin y reportResult para compradores y vendedores, respectivamente.

La definición de la función de registerBeacon es la siguiente:

function registerAdBeacon(beacons), en el que beacons es un diccionario de string para pares de strings

Para cada evento de anuncio para el que un comprador o vendedor esté interesado en los informes, debería agregar un par event_key: event_reporting_uri al dict beacons, en el que event_key es un identificador para ese evento específico. Este event_key debe coincidir con ReportEventRequest#getKey() cuando el SDK invoca a reportEvent(ReportEventRequest, Executor, OutcomeReceiver). Además, cada event_reporting_uri debe analizarse correctamente en una Uri. Este será el Uri que se informa cuando el SDK invoca a reportEvent(ReportEventRequest, Executor, OutcomeReceiver).

Cuando el comprador o vendedor haya agregado todos los pares para los que quiera recibir eventos, puede invocar a registerAdBeacon(beacons), en el que beacons es el nombre del diccionario al que agregó los pares.

registerAdBeacon arrojará una TypeError en estas situaciones:

  1. Se llama a registerAdBeacon más de una vez. Si este error se detecta en reportWin/reportResult, se registrará el conjunto original de vinculaciones.
  2. registerAdBeacon no tiene exactamente 1 argumento de dict.
  3. El contenido del argumento 1 dict no corresponde a todas las vinculaciones String: String.

receiver pasa el resultado, que muestra un Object vacío para una ejecución correcta, o un Exception incluye el tipo de excepción que se arrojó y el mensaje de error correspondiente.

Si se arroja la IllegalArgumentException, se debe a un argumento de entrada no válido que la API recibió para informar la impresión.

Si se muestra IllegalStateException con el mensaje de error "Falla de los servicios de AdSelection", se debe a una falla interna del servicio de selección de anuncios.

Si se arroja la LimitExceededException, se produce cuando el paquete de llamada supera los límites de frecuencia permitidos y se limita.

Si se arroja la SecurityException, se produce cuando el emisor no está autorizado o no se solicita el permiso.

Las impresiones se informarán, como máximo, una vez como mejor esfuerzo.
Requiere AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

Parámetros
request ReportImpressionRequest: Este valor no puede ser null.

executor Executor: Este valor no puede ser null.

receiver OutcomeReceiver: Este valor no puede ser null.

selectAds

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

Selecciona un anuncio de los resultados de selecciones de anuncios ejecutadas anteriormente.

El SDK de Ads proporciona la entrada adSelectionFromOutcomesConfig, y el objeto AdSelectionFromOutcomesConfig se transfiere a través de una llamada de Binder. Por este motivo, el tamaño total de estos objetos está sujeto a las limitaciones de IPC de Android. Si no se transfiere el AdSelectionFromOutcomesConfig, se arrojará una TransactionTooLargeException.

El receptor pasa el resultado, que muestra un AdSelectionOutcome para una ejecución correcta, o un Exception incluye el tipo de excepción que se arrojó y el mensaje de error correspondiente.

El adSelectionFromOutcomesConfig de entrada contiene lo siguiente:

  • Seller debe ser un AdTechIdentifier registrado. De lo contrario, se arrojará IllegalStateException.
  • Debe existir List of ad selection ids y provenir de llamadas de selectAds(AdSelectionConfig, Executor, OutcomeReceiver) que se originan en la misma aplicación. De lo contrario, IllegalArgumentException para la validación de entradas generará listas que infrinjan los IDs de selección de anuncios.
  • Selection logic URI que podría seguir los esquemas precompilados de HTTPS o de selección de anuncios.

    Si el URI sigue el esquema HTTPS, el host debería coincidir con el seller. De lo contrario, se arrojará IllegalArgumentException.

    Los URIs precompilados son una forma de sustituir una lógica genérica compilada previamente por los JavaScript requeridos para selectOutcome. El URI precompilado para este extremo debería ser similar al siguiente:

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

    Si se pasa un URI precompilado no compatible o el servicio inhabilita la función del URI precompilado, se arrojará IllegalArgumentException.

    Consulta AdSelectionFromOutcomesConfig.Builder#setSelectionLogicUri para ver los <name> compatibles y los <script-generation-parameters> obligatorios.

Si se arroja la IllegalArgumentException, se debe a un argumento de entrada no válido que la API recibió para ejecutar la selección de anuncios.

Si se muestra IllegalStateException con el mensaje de error "Falla de los servicios de AdSelection", se debe a una falla interna del servicio de selección de anuncios.

Si se arroja TimeoutException, se produce cuando se encuentra un tiempo de espera durante la oferta, la puntuación o el proceso de selección general para encontrar el anuncio ganador.

Si se arroja la LimitExceededException, se produce cuando el paquete de llamada supera los límites de frecuencia permitidos y se limita.

Si se arroja la SecurityException, se produce cuando el emisor no está autorizado o no se solicita el permiso.
Requiere AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

Parámetros
adSelectionFromOutcomesConfig AdSelectionFromOutcomesConfig: Este valor no puede ser null.

executor Executor: Este valor no puede ser null. Los eventos de devolución de llamada y de objetos de escucha se envían a través de este Executor, lo que proporciona una manera fácil de controlar qué subproceso se usa. Para enviar eventos a través del subproceso principal de tu aplicación, puedes usar Context.getMainExecutor(). De lo contrario, proporciona un Executor que se envíe al subproceso correspondiente.

receiver OutcomeReceiver: Este valor no puede ser null.

selectAds

Se agregó en el nivel de API 34.
public void selectAds (AdSelectionConfig adSelectionConfig, 
                Executor executor, 
                OutcomeReceiver<AdSelectionOutcomeException> receiver)

Ejecuta el proceso de selección de anuncios en el dispositivo a fin de seleccionar un anuncio de remarketing para la aplicación que realiza la llamada.

El SDK de Ads proporciona la entrada adSelectionConfig, y el objeto AdSelectionConfig se transfiere a través de una llamada de Binder. Por este motivo, el tamaño total de estos objetos está sujeto a las limitaciones de IPC de Android. Si no se transfiere el AdSelectionConfig, se arrojará una TransactionTooLargeException.

La entrada adSelectionConfig contiene Decision Logic Uri que podría seguir los esquemas precompilados de HTTPS o de selección de anuncios.

Si el URI sigue el esquema HTTPS, el host debería coincidir con el seller. De lo contrario, se arrojará IllegalArgumentException.

Los URIs precompilados son una forma de sustituir una lógica genérica compilada previamente por los JavaScript requeridos para scoreAds. El URI precompilado para este extremo debería ser similar al siguiente:

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

Si se pasa un URI precompilado no compatible o el servicio inhabilita la función del URI precompilado, se arrojará IllegalArgumentException.

Consulta AdSelectionConfig.Builder#setDecisionLogicUri para conocer los <name> compatibles y los <script-generation-parameters> obligatorios.

El receptor pasa el resultado, que muestra un AdSelectionOutcome para una ejecución correcta, o un Exception incluye el tipo de excepción que se arrojó y el mensaje de error correspondiente.

Si se arroja la IllegalArgumentException, se debe a un argumento de entrada no válido que la API recibió para ejecutar la selección de anuncios.

Si se muestra IllegalStateException con el mensaje de error "Falla de los servicios de AdSelection", se debe a una falla interna del servicio de selección de anuncios.

Si se arroja TimeoutException, se produce cuando se encuentra un tiempo de espera durante la oferta, la puntuación o el proceso de selección general para encontrar el anuncio ganador.

Si se arroja la LimitExceededException, se produce cuando el paquete de llamada supera los límites de frecuencia permitidos y se limita.

Si se arroja la SecurityException, se produce cuando el emisor no está autorizado o no se solicita el permiso.
Requiere AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

Parámetros
adSelectionConfig AdSelectionConfig: Este valor no puede ser null.

executor Executor: Este valor no puede ser null. Los eventos de devolución de llamada y de objetos de escucha se envían a través de este Executor, lo que proporciona una manera fácil de controlar qué subproceso se usa. Para enviar eventos a través del subproceso principal de tu aplicación, puedes usar Context.getMainExecutor(). De lo contrario, proporciona un Executor que se envíe al subproceso correspondiente.

receiver OutcomeReceiver: Este valor no puede ser null.

updateAdCounterHistograma

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

Actualiza los histogramas de contador de un anuncio que se seleccionaba anteriormente mediante una llamada a selectAds(android.adservices.adselection.AdSelectionConfig, java.util.concurrent.Executor, android.os.OutcomeReceiver).

Los histogramas de contador se usan en la selección de anuncios para informar el filtrado de limitación de frecuencia en anuncios candidatos, en los que los anuncios cuyas limitaciones de frecuencia se alcanzan o superan, se quitan del proceso de oferta durante la selección de anuncios.

Los histogramas de contador solo se pueden actualizar para los anuncios especificados por el adSelectionId determinado que muestra una llamada reciente a la selección de anuncios de FLEDGE desde la misma app que realiza la llamada.

Se muestra una SecurityException a través de outcomeReceiver en los siguientes casos:

  1. La app no declaró los permisos correctos en su manifiesto.
  2. la app o entidad identificada por callerAdTechIdentifier no tiene autorización para usar la API.
Se muestra una IllegalStateException a través de outcomeReceiver si la llamada no proviene de una app con una actividad en primer plano.

Se muestra una LimitExceededException a través de outcomeReceiver si la llamada supera el límite de la API de la app que realiza la llamada.

En todos los demás casos de falla, outcomeReceiver mostrará un Object vacío. Ten en cuenta que, para proteger la privacidad del usuario, los errores internos no se devolverán a través de una excepción.
Requiere AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

Parámetros
updateAdCounterHistogramRequest UpdateAdCounterHistogramRequest: Este valor no puede ser null.

executor Executor: Este valor no puede ser null. Los eventos de devolución de llamada y de objetos de escucha se envían a través de este Executor, lo que proporciona una manera fácil de controlar qué subproceso se usa. Para enviar eventos a través del subproceso principal de tu aplicación, puedes usar Context.getMainExecutor(). De lo contrario, proporciona un Executor que se envíe al subproceso correspondiente.

outcomeReceiver OutcomeReceiver: Este valor no puede ser null.