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<GetAdSelectionDataOutcome, Exception> receiver)
Recopila datos del público personalizado del dispositivo. |
TestAdSelectionManager
|
getTestAdSelectionManager()
|
void
|
persistAdSelectionResult(PersistAdSelectionResultRequest request, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> receiver)
Conserva los resultados de la selección de anuncios del servidor. |
void
|
reportEvent(ReportEventRequest request, Executor executor, OutcomeReceiver<Object, Exception> 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 |
void
|
reportImpression(ReportImpressionRequest request, Executor executor, OutcomeReceiver<Object, Exception> 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 |
void
|
selectAds(AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> receiver)
Selecciona un anuncio de los resultados de selecciones de anuncios ejecutadas anteriormente. |
void
|
selectAds(AdSelectionConfig adSelectionConfig, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> 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<Object, Exception> outcomeReceiver)
Actualiza los histogramas de contador de un anuncio que se seleccionaba anteriormente mediante una llamada a |
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<GetAdSelectionDataOutcome, Exception> 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.
public TestAdSelectionManager getTestAdSelectionManager ()
Devuelve | |
---|---|
TestAdSelectionManager |
Este valor no puede ser null . |
persistenteAdSelectionResult
public void persistAdSelectionResult (PersistAdSelectionResultRequest request, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> 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<Object, Exception> 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
public void reportImpression (ReportImpressionRequest request, Executor executor, OutcomeReceiver<Object, Exception> 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:
- Se llama a
registerAdBeacon
más de una vez. Si este error se detecta en reportWin/reportResult, se registrará el conjunto original de vinculaciones. registerAdBeacon
no tiene exactamente 1 argumento de dict.- 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<AdSelectionOutcome, Exception> 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 unAdTechIdentifier
registrado. De lo contrario, se arrojaráIllegalStateException
.- Debe existir
List of ad selection ids
y provenir de llamadas deselectAds(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
public void selectAds (AdSelectionConfig adSelectionConfig, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> 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<Object, Exception> 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:
- La app no declaró los permisos correctos en su manifiesto.
- la app o entidad identificada por
callerAdTechIdentifier
no tiene autorización para usar la API.
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 . |