FLEDGE en la guía para desarrolladores de Android

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.

Enviar comentarios

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:

1. Administrar públicos personalizados
2. Configurar y ejecutar la selección de anuncios en un dispositivo
3. Denunciar impresiones de anuncios

Antes de comenzar

Antes de comenzar, completa lo siguiente:

1. Configura tu entorno de desarrollo para Privacy Sandbox en Android.
2. Instala una imagen del sistema en un dispositivo compatible o configura un emulador que incluya compatibilidad con Privacy Sandbox en Android.

3. 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 \"*\"
   

4. Incluye un permiso ACCESS_ADSERVICES_CUSTOM_AUDIENCE en el manifiesto de tu app:

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

5. 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" />
   

6. 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>
   

7. 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 y reportImpression 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:

1. Inicializa el objeto CustomAudienceManager.
2. Especifica parámetros clave, como el paquete del comprador y un nombre relevante, para crear un objeto CustomAudience. Luego, inicializa el objeto JoinCustomAudienceRequest con el objeto CustomAudience.
3. Llama a joinCustomAudience() asíncrono con el objeto JoinCustomAudienceRequest y los objetos Executor y OutcomeReceiver relevantes.

val customAudienceManager: CustomAudienceManager =
    context.getSystemService(CustomAudienceManager::class.java)

// Initialize a custom audience.
val audience = CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    ...
    .build()

// Initialize a custom audience request.
val joinCustomAudienceRequest: JoinCustomAudienceRequest =
    JoinCustomAudienceRequest.Builder().setCustomAudience(audience).build()

// Request to join a custom audience.
customAudienceManager.joinCustomAudience(joinCustomAudienceRequest,
    executor,
    outcomeReceiver)

CustomAudienceManager customAudienceManager =
    context.getSystemService(CustomAudienceManager.class);

// Initialize a custom audience.
CustomAudience audience = new CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    ...
    .build();

// Initialize a custom audience request.
JoinCustomAudienceRequest joinCustomAudienceRequest =
    new JoinCustomAudienceRequest.Builder().setCustomAudience(audience).build();

// Request to join a custom audience.
customAudienceManager.joinCustomAudience(joinCustomAudienceRequest,
    executor,
    outcomeReceiver);

La combinación de los siguientes parámetros identifica de manera única cada objeto CustomAudience en un dispositivo:

• 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 objeto AdData 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:

// Minimal initialization of a CustomAudience object
val customAudience: CustomAudience = CustomAudience.Builder()
    .setBuyer(AdTechIdentifier.fromString("my.buyer.domain.name"))
    .setName("example-custom-audience-name")
    .setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
    .setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
    .build()

// Minimal initialization of a CustomAudience object
CustomAudience customAudience = CustomAudience.Builder()
    .setBuyer(AdTechIdentifier.fromString("my.buyer.domain.name"))
    .setName("example-custom-audience-name")
    .setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
    .setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
    .build();

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 con IllegalStateException como la causa.

Este es un ejemplo de control del resultado de joinCustomAudience():

var callback: OutcomeReceiver<Void, AdServicesException> =
    object : OutcomeReceiver<Void, AdServicesException> {
    override fun onResult(result: Void) {
        Log.i("CustomAudience", "Completed joinCustomAudience")
    }

    override fun onError(error: AdServicesException) {
        // Handle error
        Log.e("CustomAudience", "Error executing joinCustomAudience", error)
    }
};

OutcomeReceiver callback = new OutcomeReceiver<Void, AdServicesException>() {
    @Override
    public void onResult(@NonNull Void result) {
        Log.i("CustomAudience", "Completed joinCustomAudience");
    }

    @Override
    public void onError(@NonNull AdServicesException error) {
        // Handle error
        Log.e("CustomAudience", "Error executing joinCustomAudience", error);
    }
};

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:

1. Inicializa el objeto CustomAudienceManager.
2. Inicializa el elemento LeaveCustomAudienceRequest con buyer y name del público personalizado. Para obtener más información sobre estos campos de entrada, consulta "Únete a un público personalizado".
3. Llama al método asíncrono leaveCustomAudience() con el objeto LeaveCustomAudienceRequest y los objetos Executor y OutcomeReceiver relevantes.

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)

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

1. Inicializa un objeto AdSelectionManager.
2. Compila un objeto AdSelectionConfig.
3. Llama al método asíncrono selectAds() con el objeto AdSelectionConfig y los objetos Executor y OutcomeReceiver relevantes.

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)

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 con IllegalStateException 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:

1. Inicializa un objeto AdSelectionManager.
2. Compila un objeto ReportImpressionRequest con el ID de selección de anuncios.
3. Llama al método asíncrono reportImpression() con el objeto AdSelectionConfig y los objetos Executor y OutcomeReceiver relevantes.

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

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 indica IllegalArgumentException como la causa.
  • Todos los demás errores recibirán AdServicesException con IllegalStateException como la causa.

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
        },
        ...
    ]
}

Por lo general, esta recuperación en segundo plano se realiza una vez cada 24 horas. Mientras realizas pruebas, puedes activar este trabajo de forma manual si ejecutas el siguiente comando:

adb shell cmd jobscheduler run -f com.google.android.adservices.api 9

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:

• generateBid()
• reportResult()

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:

• scoreAd()
• reportWin()

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 var ad = { '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 y name 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 y expiration_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 campo userBiddingSignals de CustomAudience cuando se crea.
  • trusted_bidding_signals, contextual_signals y user_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 propiedad render_url del anuncio
• bid: un valor flotante que representa el valor de la oferta para este anuncio
• status: 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 de generateBid.
• bid: el valor de la oferta para el anuncio.

• ad_selection_config: un objeto JSON que representa el parámetro AdSelectionConfig de la API de selectAds. 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 de sellerSignals AdSelectionConfig.

• trusted_scoring_signal: Lee del campo adSelectionSignals en el parámetro de la API de AdSelectionConfig.

• 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 mapa perBuyerSignal en el parámetro de la API de AdSelectionConfig 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 anuncio
• status: 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 de scoreAds
• render_url: la URL de renderización del anuncio ganador
• bid: la oferta que se ofrece para el anuncio ganador
• contextual_signals: consulta la documentación de generateBid

Salida:

• status: 0 para la ejecución correcta y un valor distinto de cero para las fallas
• results: Un objeto JSON que contiene lo siguiente:
  • signals_for_buyer: Un objeto JSON que se pasa a la función reportWin
  • 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 sobre scoreAd
• signals_for_buyer: Un objeto JSON que muestra reportResult
• contextual_signals, custom_audience_signals: consulta la documentación de generateBid

Salida:

• status: 0 para la ejecución correcta y un valor distinto de cero para las fallas
• results: 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:

1. Extremo del comprador que publica la lógica de ofertas de JavaScript
2. Un extremo que publica los indicadores de ofertas
3. Extremo del vendedor que publica la lógica de decisión de JavaScript
4. Un extremo que muestra indicadores de puntuación
5. Extremo de los informes de impresiones del comprador que ganó
6. Extremo de los informes de impresiones del vendedor
7. 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:

1. Inicializa un objeto AdSelectionManager.
2. Obtén una referencia a TestAdSelectionManager desde el objeto AdSelectionManager.
3. Compila un objeto AdSelectionConfig.
4. Compila una AddAdSelectionOverrideRequest con el objeto AdSelectionConfig y una String que represente el JavaScript que quieres usar como anulación.
5. Llama al método asíncrono overrideAdSelectionConfigRemoteInfo() con el objeto AddAdSelectionOverrideRequest y los objetos Executor y OutcomeReceiver relevantes.

val testAdSelectionManager: TestAdSelectionManager =
  context.getSystemService(AdSelectionManager::class.java).getTestAdSelectionManager()

// Initialize AdSelectionConfig =
val adSelectionConfig = new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .build()

// Initialize AddAddSelectionOverrideRequest
val request = AddAdSelectionOverrideRequest.Builder()
    .setAdSelectionConfig(adSelectionConfig)
    .setDecisionLogicJs(decisionLogicJS)
    .build()

// Run the call to override the JavaScript for the given AdSelectionConfig
// Note that this only takes effect in apps marked as debuggable
testAdSelectionManager.overrideAdSelectionConfigRemoteInfo(
    request,
    executor,
    outComeReceiver)

TestAdSelectionManager testAdSelectionManager =
  context.getSystemService(AdSelectionManager.class).getTestAdSelectionManager();

// Initialize AdSelectionConfig =
AdSelectionConfig adSelectionConfig = new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .build();

// Initialize AddAddSelectionOverrideRequest
AddAdSelectionOverrideRequest request = AddAdSelectionOverrideRequest.Builder()
    .setAdSelectionConfig(adSelectionConfig)
    .setDecisionLogicJs(decisionLogicJS)
    .build();

// Run the call to override the JavaScript for the given AdSelectionConfig
// Note that this only takes effect in apps marked as debuggable
testAdSelectionManager.overrideAdSelectionConfigRemoteInfo(
    request,
    executor,
    outComeReceiver);

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:

1. Llama al método resetAllAdSelectionConfigRemoteOverrides() asíncrono con el objeto OutcomeReceiver relevante.

// Resets overrides for all AdSelectionConfigs
testAadSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
  outComeReceiver)

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

1. Sigue los pasos para unirte a un público personalizado.
2. 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.
3. Llama al método asíncrono overrideCustomAudienceRemoteInfo() con el objeto AddCustomAudienceOverrideRequest y los objetos Executor y OutcomeReceiver relevantes.

val testCustomAudienceManager: TestCustomAudienceManager =
  context.getSystemService(CustomAudienceManager::class.java).getTestCustomAudienceManager()

// Join custom audience

// Build the AddCustomAudienceOverrideRequest
val request = AddCustomAudienceOverrideRequest.Builder()
    .setBuyer(buyer)
    .setName(name)
    .setBiddingLogicJs(biddingLogicJS)
    .setTrustedBiddingSignals(trustedBiddingSignals)
    .build()

// Run the call to override JavaScript for the given custom audience
testCustomAudienceManager.overrideCustomAudienceRemoteInfo(
    request,
    executor,
    outComeReceiver)

TestCustomAudienceManager testCustomAudienceManager =
  context.getSystemService(CustomAudienceManager.class).getTestCustomAudienceManager();

// Join custom audience

// Build the AddCustomAudienceOverrideRequest
AddCustomAudienceOverrideRequest request =
    AddCustomAudienceOverrideRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .setBiddingLogicJs(biddingLogicJS)
        .setTrustedBiddingSignals(trustedBiddingSignals)
        .build();

// Run the call to override JavaScript for the given custom audience
testCustomAudienceManager.overrideCustomAudienceRemoteInfo(
    request,
    executor,
    outComeReceiver);

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:

1. Llama al método resetAllCustomAudienceOverrides() asíncrono con objetos Executor y OutcomeReceiver relevantes.

// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
    executor,
    outComeReceiver)

// 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.

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.