A medida que leas la documentación de Privacy Sandbox en Android, usa el botón Versión preliminar para desarrolladores o Beta para seleccionar la versión del programa con la que estás trabajando, ya que las instrucciones pueden variar.
FLEDGE en Android incluye la API de Custom Audience y la API de Ad Selection. Las plataformas de tecnología publicitaria y los anunciantes pueden usar estas APIs para publicar anuncios personalizados según la participación anterior en la app, lo que limita el uso compartido de identificadores en todas las apps y el uso compartido de la información sobre la interacción en la app del usuario con terceros.
La API de Custom Audience se centra en la abstracción de "público personalizado", que representa a un grupo de usuarios con intenciones comunes. Un anunciante puede registrar un usuario con un público personalizado y asociar anuncios relevantes con este. Esta información se almacena de forma local y se puede usar para informar las ofertas de los anunciantes, el filtrado y la renderización de anuncios.
La API de Ad Selection proporciona un framework que permite que varios desarrolladores ejecuten una subasta a nivel local para un público personalizado. Para lograrlo, el sistema tienen en cuenta los anuncios relevantes asociados con el público personalizado y realiza un procesamiento adicional en anuncios que una plataforma de tecnología publicitaria muestra en el dispositivo.
Las plataformas de tecnología publicitaria pueden integrar estas APIs para implementar el remarketing que preserva la privacidad del usuario. En versiones futuras, se planea admitir casos de uso adicionales, como anuncios de instalación de app. Más información sobre FLEDGE en Android en la propuesta de diseño.
En esta guía para desarrolladores, se describe cómo trabajar con FLEDGE en Android a fin de hacer lo siguiente:
- Administrar públicos personalizados
- Configurar y ejecutar la selección de anuncios en un dispositivo
- Denunciar impresiones de anuncios
Antes de comenzar
Antes de comenzar, completa lo siguiente:
- Configura tu entorno de desarrollo para Privacy Sandbox en Android.
- Instala una imagen del sistema en un dispositivo compatible o configura un emulador que incluya compatibilidad con Privacy Sandbox en Android.
En una terminal, habilita el acceso a la API de FLEDGE (inhabilitada de forma predeterminada) con el siguiente comando adb.
adb shell device_config put adservices ppapi_app_allow_list \"*\"
Incluye un permiso
ACCESS_ADSERVICES_CUSTOM_AUDIENCE
en el manifiesto de tu app:<uses-permission android:name="android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE" />
Haz referencia a una configuración de servicios de anuncios en el elemento
<application>
de tu manifiesto:<property android:name="android.adservices.AD_SERVICES_CONFIG" android:resource="@xml/ad_services_config" />
Especifica el recurso XML de servicios de anuncios al que se hace referencia en el manifiesto, como
res/xml/ad_services_config.xml
. Obtén más información sobre los permisos de los servicios de anuncios y el control de acceso al SDK.<ad-services-config> <custom-audiences allowAllToAccess="true" /> </ad-services-config>
De forma predeterminada, la API de Ad Selection aplica límites a la cantidad máxima de memoria que una secuencia de comandos de informes de impresiones o subastas puede asignar. La función de limitación de memoria requiere la versión 105.0.5195.58 de WebView o una posterior. La plataforma aplica una verificación de versión y las llamadas a las APIs de
selectAds
yreportImpression
fallarán si esto no se satisface. Existen dos alternativas para configurar esta opción:La primera es ejecutar el siguiente comando adb para inhabilitar esta verificación:
adb device_config put fledge_js_isolate_enforce_max_heap_size false
La segunda es instalar WebView Beta desde Google Play Store. Debe ser igual a la versión que se mencionó más arriba o posterior.
Únete a un público personalizado
Un público personalizado representa a un grupo de usuarios con intenciones o intereses comunes, según lo decide la app de un anunciante. Una app o un SDK pueden usar un público personalizado para indicar un público en particular, por ejemplo, una persona que dejó artículos en un carrito de compras. Para crear un público personalizado o unirte a uno, haz lo siguiente:
- Inicializa el objeto
CustomAudienceManager
. - Especifica parámetros clave, como el paquete del comprador y un nombre relevante, para crear un objeto
CustomAudience
. Luego, inicializa el objetoJoinCustomAudienceRequest
con el objetoCustomAudience
. - Llama a
joinCustomAudience()
asíncrono con el objetoJoinCustomAudienceRequest
y los objetosExecutor
yOutcomeReceiver
relevantes.
Kotlin
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)
Java
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);
La combinación de los siguientes parámetros identifica de manera única cada objeto CustomAudience
owner
: Nombre del paquete de la app del propietario. Esto se establece de forma implícita en el nombre del paquete de la app que realiza la llamada.buyer
: Identificador de la red de publicidad del comprador que administra los anuncios para este público personalizado.name
: Un identificador o nombre arbitrario para el público personalizado.
Llamar a joinCustomAudience()
de forma continua con una instancia diferente de CustomAudience
actualizará cualquier CustomAudience
existente con owner, buyer
que coincida y los parámetros name
. Para ayudar a preservar la privacidad, el resultado de la API no distingue entre "creación" y "actualización".
Además, se debe crear CustomAudience
con estos parámetros obligatorios:
- URL de actualización diaria: Es una URL HTTPS que se consulta a diario en segundo plano para actualizar los indicadores de ofertas del usuario, los datos de ofertas de confianza de un público personalizado, y las URLs de renderización y los metadatos para anuncios.
- URL de lógica de ofertas: Es una URL HTTPS que se consulta durante la selección de anuncios para recuperar la lógica de ofertas de JavaScript de un comprador. Consulta las firmas de las funciones necesarias en JavaScript.
Entre los parámetros opcionales para un objeto CustomAudience
, se pueden incluir los siguientes:
- Tiempo de activación: Un público personalizado solo puede participar en la selección de anuncios y en las actualizaciones diarias después de su tiempo de activación. Por ejemplo, esto puede ser útil para atraer a los usuarios inactivos de una app.
- Tiempo de vencimiento: El momento en el futuro en el que se quitará el público personalizado del dispositivo.
- Indicadores de ofertas del usuario: Es una string JSON que contiene indicadores del usuario, como la configuración regional preferida del usuario, que consumirá la lógica de ofertas de JavaScript de un comprador para generar ofertas durante el proceso de selección de anuncios. Este formato permite que las plataformas de tecnología publicitaria vuelvan a usar el código en distintas plataformas y facilita el consumo de funciones de JavaScript.
- Datos de ofertas de confianza: Es una URL HTTPS y una lista de strings que se usan durante el proceso de selección de anuncios que recuperan los indicadores de ofertas de un servidor clave-valor de confianza.
- Anuncios: Es una lista de objetos
AdData
correspondientes a los anuncios que participarán en la selección de anuncios. Cada objetoAdData
consta de lo siguiente:- URL de renderización: Es una URL HTTPS que se consulta para renderizar el anuncio final.
- Metadatos: Es un objeto JSON serializado como una string que contiene información que consumirá la lógica de ofertas del comprador durante el proceso de selección de anuncios.
Este es un ejemplo de una instancia del objeto CustomAudience
:
Kotlin
// 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()
Java
// 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();
Controla los resultados de joinCustomAudience()
El método joinCustomAudience()
asíncrono usa el objeto OutcomeReceiver
para indicar el resultado de la llamada a la API.
- La devolución de llamada
onResult()
indica que el público personalizado se creó o se actualizó de forma correcta. - La devolución de llamada
onError()
indica dos condiciones posibles.- Si se inicializa
JoinCustomAudienceRequest
con argumentos no válidos,AdServicesException
indicaráIllegalArgumentException
como la causa. - Todos los demás errores recibirán
AdServicesException
conIllegalStateException
como la causa.
- Si se inicializa
Este es un ejemplo de control del resultado de joinCustomAudience()
:
Kotlin
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)
}
};
Java
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);
}
};
Abandona un público personalizado
Si el usuario ya no satisface los criterios comerciales para un público personalizado determinado, una app o un SDK puede llamar a leaveCustomAudience()
a fin de quitar el público personalizado del dispositivo. Para quitar CustomAudience
según sus parámetros únicos, haz lo siguiente:
- Inicializa el objeto
CustomAudienceManager
. - Inicializa el elemento
LeaveCustomAudienceRequest
conbuyer
yname
del público personalizado. Para obtener más información sobre estos campos de entrada, consulta "Únete a un público personalizado". - Llama al método asíncrono
leaveCustomAudience()
con el objetoLeaveCustomAudienceRequest
y los objetosExecutor
yOutcomeReceiver
relevantes.
Kotlin
val customAudienceManager: CustomAudienceManager =
context.getSystemService(CustomAudienceManager::class.java)
// Initialize a LeaveCustomAudienceRequest
val leaveCustomAudienceRequest: LeaveCustomAudienceRequest =
JoinCustomAudienceRequest.Builder()
.setBuyer(buyer)
.setName(name)
.build()
// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
leaveCustomAudienceRequest,
executor,
outcomeReceiver)
Java
CustomAudienceManager customAudienceManager =
context.getSystemService(CustomAudienceManager.class);
// Initialize a LeaveCustomAudienceRequest
LeaveCustomAudienceRequest leaveCustomAudienceRequest =
new JoinCustomAudienceRequest.Builder()
.setBuyer(buyer)
.setName(name)
.build();
// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
leaveCustomAudienceRequest,
executor,
outcomeReceiver);
De manera similar a cuando se llama a joinCustomAudience()
, el objeto OutcomeReceiver
indicará el final de una llamada a la API. Para ayudar a proteger la privacidad, un resultado de error no diferenciará entre errores internos y argumentos no válidos. Se llama a la devolución de llamada onResult()
cuando se completa la llamada a la API, independientemente de si un público personalizado se quita de forma correcta o no.
Ejecuta la selección de anuncios
Si deseas usar FLEDGE para seleccionar anuncios, llama al método selectAds()
:
- Inicializa un objeto
AdSelectionManager
. - Compila un objeto
AdSelectionConfig
. - Llama al método asíncrono
selectAds()
con el objetoAdSelectionConfig
y los objetosExecutor
yOutcomeReceiver
relevantes.
Kotlin
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)
.build()
// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
adSelectionConfig,
executor,
outcomeReceiver)
Java
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)
.build();
// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
adSelectionConfig,
executor,
outcomeReceiver);
El método selectAds()
requiere una entrada AdSelectionConfig
, en la que debes especificar los siguientes parámetros obligatorios:
- Vendedor: Es el identificador de la red de publicidad del vendedor que inicia la selección de anuncios.
- URL de lógica de decisión: Es una URL HTTPS que se consulta para obtener la lógica de JavaScript de la red de publicidad del vendedor. Consulta las firmas de las funciones necesarias en JavaScript.
- Compradores de públicos personalizados: Es una lista completa de identificadores de redes de publicidad de compradores que el vendedor permite para participar en el proceso de selección de anuncios. Estos identificadores de compradores corresponden a CustomAudience.getBuyer() de los públicos personalizados que participan.
De manera opcional, los siguientes parámetros se pueden especificar para una selección de anuncios más personalizada:
- Indicadores de la selección de anuncios: Es un objeto JSON, serializado como una cadena, que contiene indicadores que consumirá la lógica de ofertas de JavaScript del comprador que se recupera de
CustomAudience.getBiddingLogicUrl()
. - Indicadores del vendedor: Es un objeto JSON, serializado como una string, que contiene indicadores que consumen la lógica de decisión recuperada de JavaScript del vendedor desde
AdSelectionConfig.getDecisionLogicUrl()
. - Indicadores por comprador: Es un mapa de objetos JSON, serializado como cadenas, que contiene los indicadores que consumirá la lógica de ofertas de JavaScript de compradores específicos que se recupera de
CustomAudience.getBiddingLogicUrl()
. Estos indicadores son identificados por los campos del comprador de los públicos personalizados que participan.
Una vez que se selecciona un anuncio, los resultados, las ofertas y los indicadores se conservan de forma interna para informes posteriores. Desde la devolución de llamada OutcomeReceiver.onResult()
, obtendrás un AdSelectionOutcome
que contiene lo siguiente:
- Una URL de renderización para el anuncio ganador, que se obtiene de
AdData.getRenderUrl()
- Un ID de selección de anuncios único para el usuario del dispositivo, que se utiliza para informar la impresión de anuncios
Si la selección de anuncios no se puede completar correctamente debido a argumentos no válidos, tiempos de espera o un consumo excesivo de recursos, la devolución de llamada OutcomeReceiver.onError()
proporcionará AdServicesException
con los siguientes comportamientos:
- Si la selección de anuncios se inicia con argumentos no válidos,
AdServicesException
indicaráIllegalArgumentException
como la causa. - Todos los demás errores recibirán
AdServicesException
conIllegalStateException
como la causa.
Cómo informar impresiones de anuncios
Después de elegir un anuncio ganador del flujo de trabajo de selección de anuncios, puedes informar la impresión a las plataformas participantes orientadas a la compra y a la venta con el método AdSelectionManager.reportImpression()
. Para informar una impresión de anuncios, haz lo siguiente:
- Inicializa un objeto
AdSelectionManager
. - Compila un objeto
ReportImpressionRequest
con el ID de selección de anuncios. - Llama al método asíncrono
reportImpression()
con el objetoAdSelectionConfig
y los objetosExecutor
yOutcomeReceiver
relevantes.
Java
AdSelectionManager adSelectionManager =
context.getSystemService(AdSelectionManager.class);
// Initialize a ReportImpressionRequest
ReportImpressionRequest adSelectionConfig =
new ReportImpressionRequest.Builder()
.setAdSelectionId(adSelectionId)
.setAdSelectionConfig(adSelectionConfig);
.build();
// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportImpression(
reportImpressionRequest,
executor,
outcomeReceiver);
Kotlin
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)
Inicializa ReportImpressionRequest
con los siguientes parámetros obligatorios:
- ID de selección de anuncios: Es un ID único solo para el usuario de un dispositivo que identifica a una selección de anuncios correcta.
- Configuración de selección de anuncios: Es la misma configuración que se usa en la llamada
selectAds()
identificada con el ID de selección de anuncios proporcionado.
El método reportImpression()
asíncrono usa el objeto OutcomeReceiver
para indicar el resultado de la llamada a la API.
- La devolución de llamada
onResult()
indica si se completó la selección de anuncios. - La devolución de llamada
onError()
indica las siguientes condiciones posibles:- Si se inicializa la llamada con un argumento de entrada no válido,
AdServicesException
indicaIllegalArgumentException
como la causa. - Todos los demás errores recibirán
AdServicesException
conIllegalStateException
como la causa.
- Si se inicializa la llamada con un argumento de entrada no válido,
Extremos de informes de impresiones
La API de Report Impression emitirá solicitudes GET HTTPS a los extremos que proporciona la plataforma orientada a la venta y la plataforma ganadora orientada a la compra:
Extremo de la plataforma orientada a la compra:
- La API utilizará la URL de lógica de ofertas que se especifica en el público personalizado para recuperar el código lógico de ofertas de JavaScript del comprador.
- Invoca la función de JavaScript
reportResult()
, que se espera que muestre la URL del informe de impresiones del comprador.
Extremo de la plataforma orientada a la venta:
- Usa la URL de lógica de decisión que se especifica en el objeto
AdSelectionConfig
para recuperar la lógica de decisión de JavaScript del vendedor. - Invoca la función de JavaScript
reportWin()
, que se espera que muestre la URL del informe de impresiones del comprador.
La mejor manera de completar informes de impresiones
El objetivo de reportImpression()
es ofrecer la mejor manera de completar los informes.
Actualización diaria en segundo plano
Cuando creas un público personalizado, tu app o SDK pueden inicializar metadatos personalizados. Además, la plataforma puede actualizar los siguientes metadatos personalizados del público con un proceso diario de actualización en segundo plano.
- Indicadores de ofertas del usuario
- Datos de ofertas de confianza
- Lista
AdData
Este proceso consulta la URL de actualización diaria definida en el público personalizado y es posible que la URL muestre una respuesta JSON.
- La respuesta JSON puede contener cualquiera de los campos de metadatos admitidos que deben actualizarse.
- Cada campo JSON se valida de forma independiente. El cliente ignorará los campos con formato incorrecto, por lo que la respuesta no se actualizará en ese campo en particular.
- Una respuesta HTTP vacía o un objeto JSON vacío "
{}
" no generarán actualizaciones de metadatos. - El tamaño del mensaje de respuesta debe limitarse a 10 KB.
- Todos los URIs son obligatorios para usar HTTPS.
trusted_bidding_uri
debe compartir el mismo ETLD+1 que el comprador.
Ejemplo: Respuesta JSON para una actualización diaria en segundo plano
{
"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 para la selección de anuncios
El flujo de trabajo de la selección de anuncios organiza la ejecución de JavaScript que brinda el comprador y el vendedor.
El JavaScript que brinda el comprador se recupera de la URL de lógica de ofertas que se especifica en el público personalizado. El JavaScript que se muestra debe incluir las siguientes funciones:
El JavaScript que brinda el vendedor se recupera de la URL de lógica de decisión que se especifica en el parámetro AdSelectionConfig
para la API de Ad Selection. El JavaScript que se muestra debe incluir las siguientes funciones:
generateBid()
function generateBid(
ad,
auction_signals,
per_buyer_signals,
trusted_bidding_signals,
contextual_signals,
user_signals,
custom_audience_signals) {
return {'status': 0, 'ad': ad, 'bid': ad.metadata.result };
}
Parámetros de entrada:
ad
: Es un objeto JSON con el siguiente formato varad = { 'render_url': url, 'metadata': json_metadata }
;auction_signals, per_buyer_signals
: Son los objetos JSON que se especifican en el objeto de configuración de la subasta.custom_audience_signals
: Es un objeto JSON que genera la plataforma. El formato para este objeto JSON es el siguiente: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" }
donde:
owner, buyer
yname
son strings que se toman de las propiedades con el mismo nombre del público personalizado que participa en la selección de anuncios.activation_time
yexpiration_time
son el tiempo de activación y vencimiento del público personalizado, que se expresa como segundos desde la época Unix.ca_user_bidding_signals
es una cadena JSON que se especifica en el campouserBiddingSignals
deCustomAudience
cuando se crea.trusted_bidding_signals, contextual_signals
yuser_signals
son objetos JSON. En la actualidad, se pasan como objetos vacíos y se completarán en versiones futuras. Su formato no se aplica de manera forzosa por la plataforma y es administrado por la tecnología publicitaria.
Resultado:
ad
: el anuncio al que hace referencia la oferta. La secuencia de comandos puede mostrar una copia del anuncio que recibió con diferentes metadatos. Se espera que no cambie la propiedadrender_url
del anunciobid
: un valor flotante que representa el valor de la oferta para este anunciostatus
: un valor entero que puede ser uno de los siguientes:- 0: para una ejecución correcta
- 1: (o cualquier valor distinto de cero) en caso de que alguno de los indicadores de entrada no sea válido. Si se muestra un valor distinto de cero mediante generate-bid, el proceso de oferta se invalida para todos los anuncios de PP
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 };
}
Parámetros de entrada:
ad
: consulta la documentación degenerateBid
.bid
: el valor de la oferta para el anuncio.ad_selection_config
: un objeto JSON que representa el parámetroAdSelectionConfig
de la API deselectAds
. El formato es el siguiente: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
: Son objetos JSON que se leen del parámetro de la API desellerSignals
AdSelectionConfig
.trusted_scoring_signal
: Lee del campoadSelectionSignals
en el parámetro de la API deAdSelectionConfig
.contextual_signals, user_signals
: objetos JSON. En la actualidad, se pasan como objetos vacíos y se completarán en versiones futuras. Su formato no se aplica de manera forzosa por la plataforma y es administrado por la tecnología publicitaria.per_buyer_signals
: Es un objeto JSON que se lee del mapaperBuyerSignal
en el parámetro de la API deAdSelectionConfig
usando como clave el comprador actual del público personalizado. Estará vacío si el mapa no contiene ninguna entrada para el comprador determinado.
Salida:
score
: un valor flotante que representa el valor de puntuación para este anunciostatus
: un valor entero que puede ser uno de los siguientes:- 0: para una ejecución correcta
- 1: en caso de que
customAudienceSignals
no sea válido - 2: en caso de que
AdSelectionConfig
no sea válido - 3: en caso de que alguno de los otros indicadores no sea válido
- Cualquier valor distinto de cero causa la falla del proceso; el valor determina el tipo de excepción que se arroja
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 }
};
}
Parámetros de entrada:
ad_selection_config
: consulta la documentación descoreAds
render_url
: la URL de renderización del anuncio ganadorbid
: la oferta que se ofrece para el anuncio ganadorcontextual_signals
: consulta la documentación degenerateBid
Salida:
status: 0
para la ejecución correcta y un valor distinto de cero para las fallasresults
: Un objeto JSON que contiene lo siguiente:signals_for_buyer
: Un objeto JSON que se pasa a la funciónreportWin
reporting_url
: Una URL que usa la plataforma para notificar la impresión al comprador
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 } };
}
Parámetros de entrada:
ad_selection_signals, per_buyer_signals
: Consulta la documentación sobrescoreAd
signals_for_buyer
: Un objeto JSON que muestrareportResult
contextual_signals, custom_audience_signals
: consulta la documentación degenerateBid
Salida:
status: 0
para la ejecución correcta y un valor distinto de cero para las fallasresults
: Un objeto JSON que contiene lo siguiente:reporting_url
: Una URL que usa la plataforma para notificar la impresión al vendedor
Pruebas
Para ayudarte a comenzar con FLEDGE, creamos apps de ejemplo en Kotlin y Java, que se encuentran en GitHub.
Requisitos previos
FLEDGE requiere JavaScript durante la selección de anuncios y los informes de impresiones. Hay dos métodos para proporcionar este JavaScript en un entorno de pruebas:
- Ejecuta un servidor con los extremos HTTPS requeridos que muestra el código JavaScript.
- Para anular la recuperación remota, proporciona el código necesario de una fuente local.
Cualquiera de los dos métodos requiere la configuración de un extremo HTTPS para administrar los informes de impresiones.
Extremos HTTPS
Para probar la selección de anuncios y los informes de impresiones, deberás configurar 7 extremos HTTPS a los que puede acceder tu dispositivo de prueba o emulador:
- Extremo del comprador que publica la lógica de ofertas de JavaScript
- Un extremo que publica los indicadores de ofertas
- Extremo del vendedor que publica la lógica de decisión de JavaScript
- Un extremo que muestra indicadores de puntuación
- Extremo de los informes de impresiones del comprador que ganó
- Extremo de los informes de impresiones del vendedor
- Un extremo que publica las actualizaciones diarias de un público personalizado
Para mayor comodidad, el repositorio de GitHub brinda código básico de JavaScript con fines de prueba. También incluye definiciones del servicio de OpenAPI, que se pueden implementar en una plataforma simulada o de microservicios compatible. Para obtener más detalles, consulta el archivo readme del proyecto.
Cómo anular la recuperación remota de JavaScript
Esta función está diseñada para usarse en pruebas de extremo a extremo. Para anular la recuperación remota, tu app debe ejecutarse en modo de depuración con las opciones para desarrolladores habilitadas.
Para habilitar el modo de depuración en tu aplicación, agrega la siguiente línea al atributo de la aplicación en tu AndroidManifest.xml:
<application
android:debuggable="true">
Para ver un ejemplo de cómo usar estas anulaciones, consulta la app de ejemplo de FLEDGE en GitHub.
Debes agregar tu propio JavaScript personalizado para controlar las rutinas de selección de anuncios, como las ofertas, las decisiones de puntuación y los informes. Puedes encontrar ejemplos básicos de código JavaScript que manejan todas las solicitudes necesarias en el repositorio de GitHub. La aplicación de ejemplo de FLEDGE demuestra cómo leer el código de ese archivo y prepararlo para usarlo como anulación.
Es posible anular de forma independiente la recuperación de JavaScript orientada a la compra y la venta, aunque necesitarás un extremo HTTPS para publicar cualquier JavaScript para el que no brindes anulaciones. Consulta el archivo readme para obtener información sobre cómo configurar un servidor que controle estos casos.
Solo tu paquete puede anular la recuperación de JavaScript para públicos personalizados de tu propiedad.
Cómo anular JavaScript orientado a la venta
Para configurar una anulación de JavaScript orientado a la venta, haz lo siguiente como se muestra en el siguiente ejemplo de código:
- Inicializa un objeto
AdSelectionManager
. - Obtén una referencia a
TestAdSelectionManager
desde el objetoAdSelectionManager
. - Compila un objeto
AdSelectionConfig
. - Compila una
AddAdSelectionOverrideRequest
con el objetoAdSelectionConfig
y unaString
que represente el JavaScript que quieres usar como anulación. - Llama al método asíncrono
overrideAdSelectionConfigRemoteInfo()
con el objetoAddAdSelectionOverrideRequest
y los objetosExecutor
yOutcomeReceiver
relevantes.
Kotlin
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)
Java
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);
Consulta la sección Ejecuta la selección de anuncios para obtener más información sobre lo que representa cada uno de los campos en AdSelectionConfig
. La diferencia clave es que decisionLogicUrl se puede establecer como un valor de marcador de posición, ya que se ignorará.
Para anular el código JavaScript que se usa durante la selección de anuncios, decisionLogicJs
debe contener las firmas de funciones adecuadas del lado del vendedor.
Para ver un ejemplo de cómo leer un archivo JavaScript como una string, consulta la app de ejemplo de FLEDGE en GitHub.
El método overrideAdSelectionConfigRemoteInfo()
asíncrono usa el objeto OutcomeReceiver
para indicar el resultado de la llamada a la API.
La devolución de llamada onResult()
significa que la anulación se aplicó correctamente.
Las llamadas futuras a selectAds()
usarán la lógica de decisión y de informe que hayas pasado como anulación.
La devolución de llamada onError()
indica dos condiciones posibles:
- Si se intenta realizar la anulación con argumentos no válidos,
AdServiceException
indicaráIllegalArgumentException
como la causa. - Si la anulación se intenta con una app que no se ejecuta en el modo de depuración con las opciones para desarrolladores habilitadas,
AdServiceException
indicaráIllegalStateException
como la causa.
Cómo restablecer anulaciones orientadas a la venta
En esta sección, se da por sentado que anulaste el código JavaScript orientado a la venta y que tienes una referencia a los elementos TestAdSelectionManager
y AdSelectionConfig
que se usaron en la sección anterior.
A fin de restablecer las anulaciones para todos los elementos AdSelectionConfigs
, sigue estos pasos:
- Llama al método
resetAllAdSelectionConfigRemoteOverrides()
asíncrono con el objetoOutcomeReceiver
relevante.
Kotlin
// Resets overrides for all AdSelectionConfigs
testAadSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
outComeReceiver)
Java
// Resets overrides for all AdSelectionConfigs
testAdSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
outComeReceiver);
Después de restablecer las anulaciones orientadas a la venta, las llamadas a selectAds()
usan cualquier decisionLogicUrl almacenada en AdSelectionConfig
para intentar recuperar el JavaScript necesario.
Si la llamada a resetAllAdSelectionConfigRemoteOverrides()
falla, la devolución de llamada OutComeReceiver.onError()
proporciona una AdServiceException
.
Si se intentan quitar las anulaciones con una app que no se ejecuta en el modo de depuración con las opciones para desarrolladores habilitadas, AdServiceException
indicará IllegalStateException
como la causa.
Cómo anular JavaScript orientado a la compra
- Sigue los pasos para unirte a un público personalizado.
- Compila una
AddCustomAudienceOverrideRequest
con el comprador y nombre del público personalizado que deseas anular, además de la lógica de ofertas y los datos que deseas usar como anulación. - Llama al método asíncrono
overrideCustomAudienceRemoteInfo()
con el objetoAddCustomAudienceOverrideRequest
y los objetosExecutor
yOutcomeReceiver
relevantes.
Kotlin
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)
Java
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);
Los valores para comprador y nombre son los mismos que se usan a fin de crear el público personalizado. Más información sobre estos campos.
También puedes especificar dos parámetros adicionales:
biddingLogicJs
: JavaScript que contiene la lógica del comprador que se usa durante la selección de anuncios. Consulta las firmas de las funciones necesarias en JavaScript.trustedBiddingSignals
: Indicadores de ofertas que se usarán durante la selección de anuncios. Para fines de prueba, puede ser una string vacía.
El método overrideCustomAudienceRemoteInfo()
asíncrono usa el objeto OutcomeReceiver
para indicar el resultado de la llamada a la API.
La devolución de llamada onResult()
significa que la anulación se aplicó correctamente.
Las llamadas posteriores a selectAds()
usan la lógica de informes y ofertas que hayas pasado como anulación.
La devolución de llamada onError()
indica dos condiciones posibles.
- Si se intenta realizar la anulación con argumentos no válidos,
AdServiceException
indicaráIllegalArgumentException
como la causa. - Si la anulación se intenta con una app que no se ejecuta en el modo de depuración con las opciones para desarrolladores habilitadas,
AdServiceException
indicaráIllegalStateException
como la causa.
Cómo restablecer anulaciones orientadas a la compra
En esta sección, se da por sentado que anulaste el código JavaScript orientado a la compra y que tienes una referencia a TestCustomAudienceManager
que se usó en la sección anterior.
A fin de restablecer las anulaciones para todos los públicos personalizados, sigue estos pasos:
- Llama al método
resetAllCustomAudienceOverrides()
asíncrono con objetosExecutor
yOutcomeReceiver
relevantes.
Kotlin
// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
executor,
outComeReceiver)
Java
// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
executor,
outComeReceiver)
Después de restablecer las anulaciones orientadas a la compra, las llamadas posteriores a selectAds()
usarán la biddingLogicUrl
y los trustedBiddingData
que estén almacenados en CustomAudience
para intentar recuperar el código JavaScript necesario.
Si la llamada a resetCustomAudienceRemoteInfoOverride()
falla, la devolución de llamada OutComeReceiver.onError()
proporciona una AdServiceException
.
Si se intentan quitar las anulaciones con una app que no se ejecuta en el modo de depuración con las opciones para desarrolladores habilitadas, AdServiceException
indicará IllegalStateException
como la causa.
Cómo configurar un servidor de informes
Cuando uses anulaciones de recuperación remota, deberás configurar un servidor al que pueda acceder tu dispositivo o emulador para responder a los eventos de informes. Un extremo simple que muestra 200 es suficiente para realizar pruebas. El repositorio de GitHub incluye definiciones del servicio de OpenAPI, que se pueden implementar en una plataforma simulada o de microservicios compatible. Para obtener más detalles, consulta el archivo readme del proyecto.
Cuando busques las definiciones de OpenAPI, busca el reporting-server.json.
Este archivo contiene un extremo simple que muestra 200, que representa un código de respuesta HTTP. Este extremo se usa durante selectAds()
y le indica a FLEDGE que los informes de impresiones se completaron correctamente.
Funcionalidad para realizar pruebas
- Prueba unirte a un público personalizado, abandonarlo y configurarlo, según las acciones del usuario anterior.
- Prueba iniciar la selección de anuncios en el dispositivo a través de JavaScript alojados de manera remota.
- Observa cómo la asociación de una app con la configuración de un público personalizado puede afectar los resultados de la selección de anuncios.
- Prueba los informes de impresiones después de la selección de anuncios.
Limitaciones
En la siguiente tabla, se enumeran las limitaciones para el procesamiento de FLEDGE. Los límites que se detallan pueden estar sujetos a cambios en función de los comentarios. Para conocer las funciones en progreso, lee las notas de la versión.
Componente | Descripción del límite | Valor del límite |
---|---|---|
Público personalizado (PP) | Cantidad máxima de anuncios por PP | 100 |
Cantidad máxima de PP por aplicación | 1000 | |
Cantidad máxima de apps que pueden crear un PP | 1000 | |
Retraso máximo en el tiempo de activación de un PP desde el momento de su creación | 60 días | |
Tiempo de caducidad máximo de un PP a partir de su hora de activación | 60 días | |
Cantidad máxima de PP en el dispositivo | 4,000 | |
Tamaño máximo del nombre de PP | 200 bytes | |
Tamaño máximo del URI de recuperación diario | 400 bytes | |
Tamaño máximo del URI de lógica de ofertas | 400 bytes | |
Tamaño máximo de los datos de ofertas confiables | 10 KB | |
Tamaño máximo de los indicadores de ofertas del usuario | 10 KB | |
Tasa máxima de llamadas para leaveCustomAudience por comprador |
1 por segundo | |
Tasa máxima de llamadas para joinCustomAudience por comprador |
1 por segundo | |
Recuperación en segundo plano de PP | Tiempo de espera de la conexión | 5 segundos |
Tiempo de espera de lectura de HTTP | 30 segundos | |
Tamaño máximo total de descarga | 10 KB | |
Duración máxima de una iteración de recuperación | 5 minutos | |
Cantidad máxima de PP actualizados por trabajo | 1000 | |
Selección de anuncios | Cantidad máxima de compradores | Por definir |
Cantidad máxima de PP por comprador | Por definir | |
Cantidad máxima de anuncios en una subasta | Por definir | |
Tiempo de espera de conexión inicial | 5 segundos | |
Tiempo de espera de lectura de la conexión | 5 segundos | |
Tiempo máximo de ejecución de AdSelection |
10 segundos | |
Tiempo máximo de ejecución de ofertas por PP en AdSelection |
5 segundos | |
Tiempo máximo de ejecución para la puntuación en AdSelection |
5 segundos | |
Tiempo máximo de ejecución por comprador en AdSelection |
Por definir | |
Tamaño máximo de la selección de anuncios/vendedor/indicadores por comprador | Por definir | |
Tamaño máximo de las secuencias de comandos del vendedor o comprador | Por definir | |
Tarifa de llamada máxima para selectAds |
1 QPS | |
Informes de impresiones | Tiempo mínimo antes de quitar la selección de anuncios de la persistencia | 24 h |
Cantidad máxima de selecciones de anuncios de almacenamiento | Por definir | |
Tamaño máximo de la URL de salida de los informes | Por definir | |
Tiempo máximo para los informes de impresiones | Por definir | |
Cantidad máxima de reintentos para llamadas de notificación | Por definir | |
Tiempo de espera de la conexión | 5 segundos | |
Tiempo máximo de ejecución general de reportImpression |
2 segundos | |
Tarifa de llamada máxima para reportImpressions |
1 QPS | |
Anuncios | Tamaño máximo de la lista de anuncios | 10 KB compartidos por todos los AdData en un solo PP para los anuncios contextuales |
URLs | Longitud máxima de cualquier string de URL tomada como entrada | Por definir |
JavaScript | Tiempo máximo de ejecución | 1 segundo para las ofertas y la puntuación para los informes de impresiones |
Cantidad máxima de memoria usada | 10 MB |
Informa errores y problemas
Tus comentarios son una parte fundamental de Privacy Sandbox en Android. Avísanos si tienes problemas o ideas para mejorar Privacy Sandbox en Android.