> ## 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 verificação de terceiros

> Use @topsort/verification para inserir tags de verificação do IAS em anúncios de banner após o consentimento do comprador.

Os anunciantes podem usar provedores de verificação de terceiros, como IAS e DoubleVerify, para medir de forma independente se seus anúncios foram renderizados e estavam visíveis. Esses provedores executam um script pequeno na página junto com o anúncio.

Isso exige duas coisas:

1. A tag do provedor deve viajar com o criativo, da configuração da campanha até a resposta do leilão.
2. O storefront deve inserir o script no banner renderizado depois que o comprador tiver concedido o consentimento.

O Topsort já oferece suporte a transportar tags de verificação por meio de modelos JSON de banner. Os marketplaces podem implementar o tratamento de consentimento e a inserção do script por conta própria, ou usar a biblioteca `@topsort/verification` para gerenciar esses passos.

A biblioteca auxiliar atualmente oferece suporte **apenas ao IAS**. Ela reduz o código personalizado necessário para gerenciar a inserção de tags, re-renders de banners, rotação de anúncios e alterações de consentimento.

A biblioteca está disponível para todos os clientes Topsort e funciona com ou sem Banners.js. Siga os passos abaixo para um renderizador de banners personalizado. Se você usa Banners.js, veja também [Uso do Banners.js](#uso-do-bannersjs).

## Antes de começar

* Seus banners devem usar [modelos JSON](/pt/knowledge-base/ad-platform/banners/native-ads-banners-templating), que definem campos criativos nomeados.
* Você precisa de uma **Consent Management Platform (CMP)** para coletar e registrar o consentimento do comprador. O Topsort e esta biblioteca não fornecem uma CMP. Você conecta a biblioteca à sua CMP existente por meio de um adaptador de consentimento.

## Passo 1: Configure o modelo de banner

Ao criar o modelo de banner, inclua um campo de texto chamado `verificationTag`. Este campo contém a tag de verificação do anunciante.

Você pode usar outro nome de campo, desde que o storefront leia o mesmo nome da resposta do leilão. Este guia usa `verificationTag`.

## Passo 2: Forneça a tag de verificação

Durante a criação da campanha, o anunciante cola no campo do modelo a tag fornecida pelo provedor de verificação.

Para o suporte atual a IAS da biblioteca, o valor aceito é exatamente uma tag de script externa:

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

A biblioteca valida a tag de acordo com os seguintes requisitos:

* A URL deve usar HTTPS.
* O hostname deve ser `staticjs.adsafeprotected.com`.
* O path deve ser `/fw.js`.
* A URL deve conter exatamente um `advEntityId` numérico e um `pubEntityId` numérico.
* JavaScript inline, atributos extras, elementos extras, outros hosts, portas explícitas e fragmentos de URL são rejeitados.

Se a tag for rejeitada, a biblioteca não insere um script. O banner continua sendo renderizado normalmente.

## Passo 3: Leia a tag da resposta do leilão

Os campos do modelo são retornados no objeto `content` do asset vencedor. Leia `verificationTag` junto com a URL da imagem, o headline e outros campos criativos.

Na resposta bruta do leilão, isso é `winner.asset[index].content.verificationTag`, em que `index` identifica o asset que você está renderizando.

Os exemplos abaixo assumem que sua aplicação mapeia o objeto `content` desse asset para `banner.content` e o `resolvedBidId` do vencedor para `banner.resolvedBidId`. Esses são mapeamentos no nível da aplicação, não um formato diferente de resposta de leilão.

## Passo 4: Registre o banner renderizado

A biblioteca insere o script validado no contêiner do banner depois que o consentimento é concedido. Ela também gerencia alterações de registro quando banners são re-renderizados, rotacionados ou removidos.

Três termos aparecem nos exemplos:

* **Runtime:** O objeto retornado por `createVerificationRuntime(...)`. Ele se conecta ao seu adaptador de consentimento e rastreia os elementos de banner registrados. Crie um runtime para a página e reutilize-o entre banners.
* **Register:** Chamar `register(...)` fornece o elemento do banner, a tag de verificação e a chave de render. A biblioteca verifica o consentimento antes de inserir o script.
* **Handle:** O objeto retornado por `register(...)`. O método `dispose()` encerra o registro e remove o nó de script que a biblioteca inseriu.

Crie o adaptador `consentSource` descrito em [Conecte seu CMP](#conecte-seu-cmp) e então registre cada banner depois que o elemento contêiner estiver disponível:

```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 um re-render do mesmo anúncio de um anúncio novo renderizado no mesmo elemento. Registrar um `renderKey` novo no mesmo elemento desmonta e substitui automaticamente o registro anterior.

Mantenha a chave estável para re-renders do mesmo anúncio e altere-a para o render de um anúncio novo.

Se `element` não for um elemento válido, a tag estiver vazia ou `renderKey` estiver vazio, `register` não faz nada e não carrega nada. Ele não lança um erro no código de renderização de banners.

### Uso do React

Para React, crie o runtime uma vez em um módulo compartilhado e importe-o onde você renderizar banners. Não o crie dentro de um componente, onde montagens repetidas criariam runtimes e assinaturas de consentimento separados.

```typescript theme={null}
// verification.ts
import { createVerificationRuntime } from "@topsort/verification";
import { consentSource } from "./consent";

export const verification = createVerificationRuntime({ consentSource });
```

Use o helper do React para conectar o runtime ao elemento do 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` retorna um callback ref. O React o chama com o nó DOM quando o banner monta e com `null` quando desmonta. O helper registra o banner e trata a limpeza, então você não chama `dispose()` você mesmo.

## Conecte seu CMP

A biblioteca não mostra UI de consentimento e não se comunica diretamente com sua CMP. Você fornece um adaptador com duas funções:

* `current()` retorna o estado atual de consentimento.
* `subscribe(listener)` informa alterações de consentimento e retorna uma função que interrompe a escuta.

Escolha a finalidade da CMP aplicável à medição do fornecedor e então mapeie o estado para `"unknown"`, `"granted"` ou `"denied"`.

O exemplo a seguir ilustra a estrutura do adaptador. Substitua `readMyCmp()` e `myCmp.on/off` pelas APIs reais da sua 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);
  },
};
```

A biblioteca responde a cada estado da seguinte forma:

* **`unknown`:** Aguarda sem parsear a tag, buscar o script do provedor ou modificar o DOM.
* **`granted`:** Valida a tag, cria um elemento `<script>` novo a partir do `src` validado e o anexa dentro do elemento do banner. Não insere markup armazenado via `innerHTML`.
* **`denied`:** Encerra o registro sem carregar o script.

Retorne o estado de consentimento real da sua CMP. Hardcodar `"granted"` ignora o controle de consentimento e permite que o IAS carregue assim que o banner for registrado.

Se o consentimento for retirado depois, a biblioteca encerra o registro e remove o próprio nó de script. Ela não pode desfazer código do fornecedor que já executou, requests já enviados, globals já definidos ou storage já gravado. A limpeza é de melhor esforço e cobre apenas o nó de script criado pela biblioteca.

## Verifique a integração

Passe um callback `onDiagnostic` ao criar o runtime para receber códigos de status como:

* `registered`
* `active`
* `consent_denied`
* `invalid_tag`
* `provider_load_failed`
* `provider_load_timeout`

Os diagnósticos incluem o nome do provedor e os milissegundos decorridos. Eles não incluem a tag bruta, a query da URL nem o conteúdo da página.

**`active` significa apenas que o script do provedor terminou de carregar.** Não confirma que o IAS registrou uma impressão, considerou o anúncio visível ou aceitou os dados. Confirme a medição nos relatórios do IAS.

## Content Security Policy

Se o seu storefront usa uma Content Security Policy (CSP), permita `staticjs.adsafeprotected.com` em `script-src` para que o navegador possa carregar o script do IAS.

Isso não é uma allowlist de produção completa. O conjunto completo de origens do IAS exigidas para `script-src`, `connect-src`, `img-src` e `frame-src` permanece sujeito à validação do IAS.

## Uso do Banners.js

A mesma configuração de modelo e o mesmo adaptador de consentimento se aplicam ao usar [Banners.js](/pt/ad-platform/banners/bannersjs).

Depois que o Banners.js renderiza um banner e dispara o evento `ready`:

1. Identifique o elemento contêiner do banner renderizado.
2. Leia `verificationTag` do content de modelo do criativo vencedor.
3. Registre o elemento, a tag e a chave de render com o runtime de verificação, como mostrado no Passo 4.

Encerre o registro quando o banner for removido ou rotacionado. Ao registrar uma chave de render nova no mesmo elemento, a biblioteca substitui automaticamente o registro anterior.