Compartir a través de

Registrarse en la API de selección de anuncios

  • Artículo

La API de selección de anuncios proporciona anuncios relevantes para el usuario en su sitio web sin usar cookies de terceros. Consulta Introducción a la selección de anuncios en el privacy-preserving-ads repositorio.

La API de selección de anuncios puede usarse mediante:

  • Vendedores que ejecutan una plataforma de suministro (SSP), que pueden usar la API para proporcionar anuncios de mayor calidad para sus publicadores.
  • Compradores que ejecutan una plataforma de demanda (DSP), que pueden usar la API para mejorar la eficacia de las campañas publicitarias.

Para empezar a usar la API de selección de anuncios y probar el flujo de un extremo a otro, regístrese para obtener la versión preliminar limitada de la API de selección de anuncios.

Como vendedor que opera una plataforma del lado de la oferta o un comprador que opera una plataforma del lado de la demanda, use esta guía para:

  • Regístrese en la versión preliminar limitada de Ad Selection API registrándose para obtener la versión de prueba de origen.
  • Complete la atestación de API publicando el archivo JSON de atestaciones.
  • Configure un entorno de evaluación con un proveedor de nube compatible.
  • Consulte la documentación de Ad Selection API.
  • Prepare las funciones de User-Defined (UDF).
  • Implemente los servicios en Azure.
  • Prueba la API de selección de anuncios en tu sitio.

Inscripción de atestación y registro alfa

¿Cuándo y dónde está disponible la versión preliminar?

Las versiones de Microsoft Edge a partir de la versión 130.0.2808.0 admiten ad selection API en una versión preliminar limitada para desarrolladores fuera del Espacio Económico Europeo (EEE) y el Reino Unido (Reino Unido).

Marcas para pruebas

Para cambiar las características de la plataforma de API de selección de anuncios en el equipo para desarrolladores, use las marcas de prueba de API de selección de anuncios en edge://flags#edge-ad-selection-api:

Marcas de

La marca api de selección de anuncios habilita la API de selección de anuncios y características asociadas, como:

  • Informes de atribución.
  • Marcos delimitados.
  • Almacenamiento compartido.
  • Agregación privada.

Requisitos y procesos de registro y atestación

Los desarrolladores interesados en las pruebas alfa pueden unirse a la prueba de origen de Ad Selection API. Esta versión de prueba de origen permite realizar pruebas de un extremo a otro de las características de Ad Selection API, que abarcan tanto el uso de la API como la implementación de imágenes de contenedor seguras.

Para cada dominio de nivel superior que quiera usar con la API de selección de anuncios, rellene el formulario Registro de prueba de origen para ese dominio y, a continuación, envíe el formulario.

Para registrarse en la prueba de origen de AD Selection API para un dominio:

  1. Abra El registro de prueba de origen de la API de selección de anuncios en Microsoft Edge en una nueva ventana o pestaña.

  2. Haga clic en el botón Iniciar ahora .

  3. Lea y acepte los términos de uso y, a continuación, haga clic en el botón Siguiente . Se abre el formulario Registro de prueba de origen de LA API de selección de anuncios :

    Formulario de registro

  4. En el cuadro de texto Dominio , escriba un único dominio de nivel superior:

    Puede configurar la versión de prueba de origen para admitir cualquiera de las siguientes opciones:

    • Un dominio único, como https://example.com, sin admitir sus subdominios.
    • Un único subdominio, como https://beta.example.com.
    • Un dominio, como https://example.com, y sus subdominios, como https://beta.example.com.

    No se admiten las rutas de acceso finales ni los parámetros de consulta. Si se escribe un URI que tiene una ruta de acceso final o un parámetro de consulta, como https://example.com/path/new-feature, se registrará el dominio raíz (como https://example.com) o el subdominio, omitiendo cualquier ruta de acceso final o parámetros de consulta.

  5. En la sección Compatibilidad con subdominios , seleccione el botón de opción Sí o No :

    • Para usar la prueba de origen en un dominio (como https://example.com) sin admitir sus subdominios (por https://beta.example.comejemplo, ), seleccione No.
    • Para usar la prueba de origen solo en un subdominio específico (como https://beta.example.com), seleccione No.
    • Para usar la prueba de origen en un dominio (como https://example.com) y sus subdominios (por https://beta.example.comejemplo, ), seleccione Sí.

  6. En el cuadro de texto Dirección de Email, proporcione un contacto de desarrollador válido para el dominio.

  7. Haga clic en el botón Enviar .

    Se genera un token de prueba de origen para el dominio de nivel superior y se le envía.

  8. Cree un archivo denominado ad-selection-attestations.jsony hospede el archivo en el dominio de nivel superior, en el /.well-known/ directorio . Por ejemplo:

    https://contoso.example/.well-known/ad-selection-attestations.json

    El ad-selection-attestations.json archivo debe publicarse dentro de los 30 días posteriores a la recepción del token de OT. Para completar la atestación y permitir que el código acceda a la API de selección de anuncios, es necesario hospedar este archivo JSON para probar la API de selección de anuncios con clientes de Microsoft Edge compatibles.

Archivo JSON de ejemplo

El archivo JSON de atestaciones debe denominarse ad-selection-attestations.jsony debe cumplir los siguientes estándares. A continuación se muestra un ejemplo de un ad-selection-attestations.json archivo:

{
    "ad_selection_api_attestations": [
        {
            "attestation_parser_version": "2",
            "attestation_version": "2",
            "privacy_policy": [
                "https://contoso.example/privacy/"
            ],
            "ownership_token": "<Your Unique Token Here>",
            "enrollment_site": "https://contoso.example/",
            "platform_attestations": [
                {
                    "platform": "edge",
                    "attestations": {
                        "ad_selection_api": {
                            "ServiceNotUsedForIdentifyingUserAcrossSites": true/false
                        },
                        "attribution_reporting_api": {
                            "ServiceNotUsedForIdentifyingUserAcrossSites": true/false
                        },
                        "shared_storage_api": {
                            "ServiceNotUsedForIdentifyingUserAcrossSites": true/false
                        },
                        "private_aggregation_api": {
                            "ServiceNotUsedForIdentifyingUserAcrossSites": true/false
                        }
                    }
                },
                {
                    "platform": "android",
                    "attestations": {}
                }
            ]
        }
    ]
}
Campos y valores importantes

  • El ad-selection-attestations.json archivo debe incluir el token de prueba de origen que se generó y le envió para este dominio de nivel superior. "ownership_token": es el token de prueba de origen que se generó al registrar este dominio para la prueba de origen de la API de selección de anuncios .

  • En la "platform_attestations": sección , "platform": debe ser "edge" o "android".

  • El archivo debe incluir una lista de API (características asociadas a la API de Ad Services). En la "platform_attestations": sección , los miembros válidos de "attestations": son los siguientes:

    • "ad_selection_api": - La API principal, para la lógica de subasta privada.
    • "attribution_reporting_api": - Informes de atribución.
    • "shared_storage_api": - Almacenamiento compartido.
    • "private_aggregation_api": - Agregación privada.
    • Requisitos:
      • Cada "..._api": entrada debe tener un único campo, "ServiceNotUsedForIdentifyingUserAcrossSites":, con un true valor o false . true significa que este servicio no se usa para identificar al usuario entre sitios. false significa que este servicio se usa para identificar al usuario entre sitios.

Implementación de los servicios de API de selección de anuncios

La API de selección de anuncios usa un entorno de ejecución de confianza (TEE) para proporcionar un nivel de garantía para la integridad de los datos, la confidencialidad de los datos y la integridad del código; consulte Computación confidencial: Hardware-Based ejecución de confianza para aplicaciones y datos. Los servicios proporcionados por ad selection API deben ejecutarse en un TEE para proteger los datos utilizados por estos servicios.

Los servicios de selección de anuncios que se ejecutan en un TEE deben implementarse en una plataforma en la nube que admita las características de seguridad necesarias. Inicialmente, los servicios se pueden implementar en Azure mediante contenedores de ACI confidenciales; consulte Contenedores confidenciales en Azure Container Instances.

La API de selección de anuncios proporciona diferentes servicios que deben implementar los vendedores o compradores.

Imágenes para implementar servicios

Agregue las funciones de User-Defined (UDF) dentro de las imágenes proporcionadas de los servicios. Las funciones User-Defined pueden ejecutar lógica de negocios personalizada. Las funciones User-Defined se ejecutan en contenedores privados dentro de los servicios implementados.

Cada imagen define un servicio. Algunas imágenes no contienen UDF y constan completamente de código predefinido. Algunas imágenes contienen UDF, como funciones con un cuerpo vacío o código de inicio, que son las funciones de User-Defined pertinentes para ese servicio. Rellene los cuerpos de User-Defined Functions en estas imágenes con su propio código personalizado.

Microsoft proporciona una imagen para cada servicio, que se puede implementar en un proveedor de nube. Estas son las imágenes públicas que se deben usar para la implementación. Solo las imágenes oficiales de Microsoft pueden ejecutar subastas privadas.

Imágenes para la implementación:

Servicios para vendedores

Servicio Descripción
SellerFrontEnd Proporciona un /SelectAd punto de conexión HTTPS, que recibe solicitudes del servicio de anuncios que no es de confianza del vendedor para iniciar el flujo de subastas de audiencia protegida.
Subasta Proporciona un /ScoreAds punto de conexión, que recibe solicitudes del servicio SellerFrontEnd , que contiene ofertas que participan en la subasta. Responde con un valor de puntuación que el servicio SellerFrontEnd usa para elegir al ganador.
Clave/valor Recibe solicitudes del servicio SellerFrontEnd , que contienen claves de búsqueda de las pujas de los compradores (como ad_render_urls). Devuelve señales de puntuación en tiempo real necesarias para la subasta. Se ejecuta en modo Bring Your Own Service (BYOS), por lo que el vendedor no necesita implementar este servicio en un entorno de ejecución de confianza (TEE) y, en su lugar, puede usar la imagen proporcionada por Microsoft.

Servicios para compradores

Servicio Descripción
BuyerFrontEnd Proporciona un punto de /GetBids conexión, que recibe solicitudes del servicio SellerFrontEnd para iniciar el flujo de pujas.
Licitación Proporciona un /GenerateBids punto de conexión, que recibe solicitudes del servicio BuyerFrontEnd para controlar la puja y generar una oferta. Genera una puja, elige al ganador y selecciona el banner que se va a representar.
Clave/valor Recibe solicitudes del servicio BuyerFrontEnd y devuelve los datos de comprador en tiempo real necesarios para la puja, correspondientes a las claves de búsqueda de Interest Grupos. Esta solicitud se produce una vez por flujo de trabajo. Se ejecuta en modo Bring Your Own Service (BYOS).
Selección de pujas & clave/valor Recibe solicitudes del servicio de pujas para seleccionar y devolver banners de anuncios (candidatos) adicionales que pueden participar en la puja. La selección de pujas & servicio clave-valor también puede devolver señales adicionales necesarias para la puja. El servicio de pujas puede enviar varias solicitudes al servicio de selección de pujas & clave/valor , o puede optar por no enviar ninguna solicitud, ya que el servicio De selección de puja & clave/valor es opcional. La selección de pujas & servicio clave-valor debe implementarse en un entorno de ejecución de confianza (TEE).
K-Anonimidad Recopila contadores de k-anonimidad y comprueba que el creativo de anuncios ganador supera la comprobación de k-anonimidad.

Funciones definidas por el usuario

Los vendedores y compradores deben proporcionar su propio código personalizado como User-Defined Funciones (UDF) que se ejecutan en contenedores privados dentro de los servicios implementados. Estas funciones User-Defined pueden ejecutar lógica de negocios personalizada.

Cada comprador o vendedor puede implementar varias instancias de un servicio determinado, como:

  • SellerFrontEnd y Auction.
  • BuyerFrontend, Bidding y K-Anonymity.

Algunos de estos servicios toman una entrada que es un worklet de JavaScript que define User-Defined Functions.

funciones de User-Defined para vendedores
UDF Servicio en el que se ejecuta la UDF Descripción
scoreAd() Subasta Genera una puntuación para la oferta de cada comprador o rechaza la oferta. A continuación, el servicio SellerFrontEnd usa esta puntuación para elegir un ganador entre todos los compradores.
reportResult() SellerFrontEnd Para informes de nivel de evento. Se ejecuta en el servicio SellerFrontEnd una vez elegido el ganador final. Notifica al vendedor sobre el pujador ganador y proporciona el valor de la oferta.
funciones de User-Defined para compradores
UDF Servicio en el que se ejecuta la UDF Descripción
generateBids() Licitación Genera una puja y elige el banner que se mostrará.
reportWin() SellerFrontEnd Para informes de nivel de evento. Se ejecuta en el servicio SellerFrontEnd , si la puja del comprador gana la subasta. Notifica al comprador que ha ganado la subasta y genera direcciones URL de notificación que se desencadenarán más adelante, como durante la representación del banner u otros eventos de cliente.
getValues() Selección de pujas & clave/valor Se ejecuta en la selección de pujas & servicio clave-valor , si el comprador usa ese servicio. Permite la ejecución de código personalizado para la búsqueda y selección de datos.

Guía de implementación

Para implementar el servicio AD Selection API en Azure:

  1. Cree una cuenta de Azure y cree una suscripción en Microsoft Azure.

  2. Elija la opción Contenedores confidenciales de ACO .

  3. Vaya a Scripts de implementación de Terraform en una nueva ventana o pestaña y, a continuación, descargue los scripts de implementación de Terraform y vea la documentación de implementación. Nota: Asegúrese de que el hash de la imagen que descargó coincide con el hash del script que descargó.

  4. Los scripts de Terraform ya incluyen vínculos a imágenes públicas proporcionadas por Microsoft. Elija los servicios necesarios e impleméntelos siguiendo los pasos descritos en el elemento incluido readme.md.

    1. Establezca marcas específicas para su entorno, incluidas las ubicaciones del worklet de subasta.

    2. Configure todos los requisitos previos y prepare todas las herramientas para la implementación.

    3. Cree recursos de Azure y ejecute el script de Terraform que finaliza la implementación.

  5. Desarrolle worklets incluidos user-defined-function (UDF) e inicie servicios de API de selección de anuncios.

Uso de la API de selección de anuncios en su sitio web

Para empezar a usar la API de selección de anuncios, los vendedores y compradores deben modificar el código JavaScript de sus sitios web que se ejecuta cuando el explorador es Microsoft Edge.

  • Vendedores: para ejecutar subastas privadas, capturar grupos de interés y realizar informes, actualice el código en los sitios web de los editores.

  • Compradores: para crear grupos de interés y almacenarlos en el explorador, actualice el código en los sitios web de sus socios publicitarios. Puede usar el mecanismo de delegación para restringir y permitir la creación de grupos de interés en dominios de terceros.

Para obtener más información sobre qué métodos de API están disponibles y ver código de ejemplo, consulte Detalles de la API de selección de anuncios.

Proporcionar comentarios sobre la prueba de origen

Para proporcionar comentarios sobre la prueba de origen de Ad Selection API, cree un nuevo problema en el repositorio de GitHub WICG/privacy-preserveing-ads:

Vea también

Pruebas de origen:

Documentos técnicos y de diseño:

Imágenes para la implementación:

Scripts de implementación:

Entorno de ejecución de confianza (TEE):

Celeste: