Biblioteca auxiliar de verificación de terceros

Los anunciantes pueden usar proveedores de verificación de terceros, como IAS, para medir de forma independiente si sus anuncios se renderizaron y fueron visibles. Estos proveedores ejecutan un script pequeño en la página junto al anuncio. Esto requiere dos cosas:

La etiqueta del proveedor debe viajar con el creativo, desde la configuración de la campaña hasta la respuesta de la subasta.
El storefront debe insertar el script en el banner renderizado después de que el comprador haya otorgado el consentimiento.

Topsort ya admite transportar etiquetas de verificación a través de plantillas JSON de banner. Los marketplaces pueden implementar por sí mismos el manejo del consentimiento y la inserción del script, o usar la biblioteca @topsort/verification para gestionar estos pasos. La biblioteca auxiliar actualmente admite solo IAS. Reduce el código personalizado necesario para gestionar la inserción de etiquetas, los re-renders de banners, la rotación de anuncios y los cambios de consentimiento. La versión inicial 0.1.0 admite renderizadores personalizados de banners web con etiquetas de monitorización de IAS. Todavía no incluye una integración automática con Banners.js, otros proveedores de verificación, medición en aplicaciones móviles nativas ni instalación directa mediante <script>.

Antes de empezar

Sus banners deben usar plantillas JSON, que definen campos creativos con nombre.
Necesita una Consent Management Platform (CMP) para recopilar y registrar el consentimiento del comprador. Topsort y esta biblioteca no proporcionan una CMP. Conecta la biblioteca a su CMP existente mediante un adaptador de consentimiento.

Instale el paquete en una aplicación basada en npm:

npm install @topsort/verification

El paquete es un módulo ES para aplicaciones y bundlers. No proporciona una compilación IIFE para instalación directa mediante un <script> del navegador. Al crear la plantilla de banner, incluya un campo de texto llamado verificationTag. Este campo contiene la etiqueta de verificación del anunciante. Puede usar otro nombre de campo, siempre que su storefront lea el mismo nombre de la respuesta de la subasta. Esta guía usa verificationTag.

Paso 2: Proporcionar la etiqueta de verificación

Durante la creación de la campaña, el anunciante pega en el campo de la plantilla la etiqueta que le suministra su proveedor de verificación. Para el soporte actual de IAS de la biblioteca, el valor aceptado es exactamente una etiqueta de script externa:

<script
  type="application/javascript"
  src="https://staticjs.adsafeprotected.com/fw.js?advEntityId=3072912&pubEntityId=96261444"
></script>

La biblioteca valida la etiqueta según los siguientes requisitos:

La URL debe usar HTTPS.
El hostname debe ser staticjs.adsafeprotected.com.
La ruta debe ser /fw.js.
La URL debe contener exactamente un advEntityId numérico y un pubEntityId numérico.
Se rechazan JavaScript en línea, atributos extra, elementos extra, otros hosts, puertos explícitos y fragmentos de URL.

Si se rechaza la etiqueta, la biblioteca no inserta un script. El banner sigue renderizándose con normalidad.

Paso 3: Leer la etiqueta de la respuesta de la subasta

Los campos de la plantilla se devuelven en el objeto content del asset ganador. Lea verificationTag junto con la URL de la imagen, el titular y otros campos creativos. En la respuesta cruda de la subasta, esto es winner.asset[index].content.verificationTag, donde index identifica el asset que está renderizando. Los ejemplos siguientes asumen que su aplicación mapea el objeto content de ese asset a banner.content y el resolvedBidId del ganador a banner.resolvedBidId. Estos son mapeos a nivel de aplicación, no un formato distinto de respuesta de subasta. La biblioteca inserta el script validado en el contenedor del banner después de que se otorgue el consentimiento. Su renderizador debe registrar cada banner cuando su elemento esté conectado y eliminar el registro cuando retire el banner. Registrar una clave de render distinta en el mismo elemento reemplaza automáticamente el registro anterior. En los ejemplos aparecen tres términos:

Runtime: El objeto que devuelve createVerificationRuntime(...). Se conecta a su adaptador de consentimiento y rastrea los elementos de banner registrados. Cree un runtime para la página y reutilícelo entre banners.
Register: Llamar a register(...) proporciona el elemento del banner, la etiqueta de verificación y la clave de render. La biblioteca comprueba el consentimiento antes de insertar el script.
Handle: El objeto que devuelve register(...). Su método dispose() termina el registro y elimina el nodo de script que insertó la biblioteca.

Cree el adaptador consentSource descrito en Conecta tu CMP y luego registre cada banner después de que su elemento contenedor esté disponible:

import { createVerificationRuntime } from "@topsort/verification";
import { consentSource } from "./consent";

const verification = createVerificationRuntime({ consentSource });

const handle = verification.register({
  element: bannerRoot, // The DOM element containing the rendered banner.
  verificationTag: banner.content.verificationTag,
  renderKey: banner.resolvedBidId,
});

// When the banner is removed or rotated out:
handle.dispose();

renderKey distingue un re-render del mismo anuncio de un anuncio nuevo renderizado en el mismo elemento. Registrar un renderKey nuevo en el mismo elemento desmonta y reemplaza automáticamente el registro anterior. Mantenga la clave estable para re-renders del mismo anuncio y cámbiela para el render de un anuncio nuevo. Una etiqueta vacía no carga nada y elimina de forma segura cualquier registro anterior del mismo elemento. Los elementos no válidos, las claves de render vacías y las etiquetas no vacías mal formadas no cargan nada y generan diagnósticos limitados. Estas condiciones no lanzan errores en el código de renderizado de banners.

Uso de React

Para React, cree el runtime una vez en un módulo compartido e impórtelo donde renderice banners. No lo cree dentro de un componente, donde montajes repetidos crearían runtimes y suscripciones de consentimiento separados.

// verification.ts
import { createVerificationRuntime } from "@topsort/verification";
import { consentSource } from "./consent";

export const verification = createVerificationRuntime({ consentSource });

Use el helper de React para conectar el runtime al elemento del banner:

// Banner.tsx
import { useVerificationRef } from "@topsort/verification/react";
import { verification } from "./verification";

function Banner({ banner }) {
  const ref = useVerificationRef(verification, {
    verificationTag: banner.content.verificationTag,
    renderKey: banner.resolvedBidId,
  });

  return <div ref={ref}>{/* Your existing banner markup. */}</div>;
}

useVerificationRef devuelve un callback ref. React lo llama con el nodo DOM cuando el banner se monta y con null cuando se desmonta. El helper registra el banner y gestiona la limpieza, así que usted no llama a dispose().

Conecta tu CMP

La biblioteca no muestra UI de consentimiento y no se comunica directamente con su CMP. Usted proporciona un adaptador con dos funciones:

current() devuelve el estado actual de consentimiento.
subscribe(listener) informa los cambios de consentimiento y devuelve una función que deja de escuchar.

Elija el propósito de CMP que aplica a la medición del proveedor y luego mapee su estado a "unknown", "granted" o "denied". El siguiente ejemplo ilustra la estructura del adaptador. Reemplace readMyCmp() y myCmp.on/off con las APIs reales de su CMP:

// consent.js
export const consentSource = {
  current() {
    return readMyCmp(); // "unknown" | "granted" | "denied"
  },

  subscribe(listener) {
    const onChange = () => listener(readMyCmp());
    myCmp.on("change", onChange);

    return () => myCmp.off("change", onChange);
  },
};

La biblioteca responde a cada estado de la siguiente forma:

unknown: Espera sin parsear la etiqueta, obtener el script del proveedor ni modificar el DOM.
granted: Valida la etiqueta, crea un elemento <script> nuevo a partir del src validado y lo añade dentro del elemento del banner. No inserta markup almacenado mediante innerHTML.
denied: Termina el registro sin cargar el script.

El consentimiento denegado es definitivo para ese registro. Si se concede más tarde, registre de nuevo el banner o recargue la página. La retirada del consentimiento y los fallos del proveedor también son definitivos; cree un registro nuevo después de corregir la causa. Devuelva el estado de consentimiento real de su CMP. Hardcodear "granted" omite el control de consentimiento y permite que IAS se cargue en cuanto se registra el banner. Si el consentimiento se retira más tarde, la biblioteca termina el registro y elimina su propio nodo de script. No puede deshacer código del proveedor que ya se ejecutó, solicitudes ya enviadas, globals ya definidos ni almacenamiento ya escrito. La limpieza es de mejor esfuerzo y cubre solo el nodo de script creado por la biblioteca.

Comprueba la integración

Pase un callback onDiagnostic al crear el runtime para recibir códigos de estado como:

registered
active
consent_denied
invalid_tag
provider_load_failed
consent_withdrawn
consent_source_failed
element_not_ready
runtime_disposed

Los diagnósticos incluyen el nombre del proveedor y los milisegundos transcurridos. No incluyen la etiqueta cruda, la query de la URL ni el contenido de la página. active significa solo que el script del proveedor terminó de cargar. No confirma que IAS registró una impresión, consideró el anuncio visible o aceptó los datos. Confirme la medición en los reportes de IAS.

Content Security Policy

Si su storefront usa una Content Security Policy (CSP), permita staticjs.adsafeprotected.com en script-src para que el navegador pueda cargar el script de IAS. Esto no es una allowlist de producción completa. El conjunto completo de orígenes de IAS requeridos para script-src, connect-src, img-src y frame-src sigue sujeto a validación de IAS.

Banners.js

La integración automática con Banners.js no forma parte de 0.1.0. Una integración personalizada solo puede usar el runtime si proporciona el elemento renderizado exacto, verificationTag y resolvedBidId, y elimina el registro según el ciclo de vida del banner. La compatibilidad de primera clase con Banners.js se documentará por separado cuando esté disponible.

Resumen

Plataforma de Anuncios

Servidor de Anuncios

Toppie

Integraciones Avanzadas

API

Biblioteca auxiliar de verificación de terceros

Antes de empezar

Paso 1: Configurar la plantilla de banner

Paso 2: Proporcionar la etiqueta de verificación

Paso 3: Leer la etiqueta de la respuesta de la subasta

Paso 4: Registrar el banner renderizado

Uso de React

Conecta tu CMP

Comprueba la integración

Content Security Policy

Banners.js

​Antes de empezar

​Paso 1: Configurar la plantilla de banner

​Paso 2: Proporcionar la etiqueta de verificación

​Paso 3: Leer la etiqueta de la respuesta de la subasta

​Paso 4: Registrar el banner renderizado

​Uso de React

​Conecta tu CMP

​Comprueba la integración

​Content Security Policy

​Banners.js

Antes de empezar

Paso 1: Configurar la plantilla de banner

Paso 2: Proporcionar la etiqueta de verificación

Paso 3: Leer la etiqueta de la respuesta de la subasta

Paso 4: Registrar el banner renderizado

Uso de React

Conecta tu CMP

Comprueba la integración

Content Security Policy

Banners.js