> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topsort.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Biblioteca auxiliar de verificación de terceros

> Use @topsort/verification para insertar etiquetas de verificación de IAS en anuncios de banner después del consentimiento del comprador.

Los anunciantes pueden usar proveedores de verificación de terceros, como IAS y DoubleVerify, 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:

1. La etiqueta del proveedor debe viajar con el creativo, desde la configuración de la campaña hasta la respuesta de la subasta.
2. 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 biblioteca está disponible para todos los clientes de Topsort y funciona con o sin Banners.js. Siga los pasos siguientes para un renderizador de banners personalizado. Si usa Banners.js, consulte también [Uso de Banners.js](#uso-de-bannersjs).

## Antes de empezar

* Sus banners deben usar [plantillas JSON](/es/knowledge-base/ad-platform/banners/native-ads-banners-templating), 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.

## Paso 1: Configurar la plantilla de banner

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:

```html theme={null}
<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.

## Paso 4: Registrar el banner renderizado

La biblioteca inserta el script validado en el contenedor del banner después de que se otorgue el consentimiento. También gestiona los cambios de registro cuando los banners se vuelven a renderizar, se rotan o se eliminan.

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](#conecta-tu-cmp) y luego registre cada banner después de que su elemento contenedor esté disponible:

```javascript theme={null}
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.

Si `element` no es un elemento válido, la etiqueta está vacía o `renderKey` está vacío, `register` no hace nada y no carga nada. No lanza un error 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.

```typescript theme={null}
// 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:

```jsx theme={null}
// 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:

```javascript theme={null}
// 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.

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`
* `provider_load_timeout`

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.

## Uso de Banners.js

La misma configuración de plantilla y el mismo adaptador de consentimiento aplican al usar [Banners.js](/es/ad-platform/banners/bannersjs).

Después de que Banners.js renderice un banner y dispare su evento `ready`:

1. Identifique el elemento contenedor del banner renderizado.
2. Lea `verificationTag` del content de plantilla del creativo ganador.
3. Registre el elemento, la etiqueta y la clave de render con el runtime de verificación, como se muestra en el Paso 4.

Elimine el registro cuando el banner se quite o se rote. Al registrar una clave de render nueva en el mismo elemento, la biblioteca reemplaza automáticamente el registro anterior.