Biblioteca auxiliar de verificação de terceiros

Os anunciantes podem usar provedores de verificação de terceiros, como o IAS, 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:

A tag do provedor deve viajar com o criativo, da configuração da campanha até a resposta do leilão.
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 versão inicial 0.1.0 oferece suporte a renderizadores personalizados de banners web com tags de monitoramento do IAS. Ela ainda não inclui integração automática com o Banners.js, outros provedores de verificação, medição em aplicativos móveis nativos nem instalação direta via <script>.

Antes de começar

Seus banners devem usar modelos JSON, 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.

Instale o pacote em um aplicativo baseado em npm:

npm install @topsort/verification

O pacote é um módulo ES para aplicativos e bundlers. Ele não fornece um build IIFE para instalação direta via <script> do navegador. 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:

<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. A biblioteca insere o script validado no contêiner do banner depois que o consentimento é concedido. Seu renderizador deve registrar cada banner depois que o elemento estiver conectado e encerrar o registro quando o banner for removido. Uma chave de renderização diferente no mesmo elemento substitui automaticamente o registro anterior. 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 e então registre cada banner depois que o elemento contêiner estiver disponível:

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. Uma tag vazia não carrega nada e encerra com segurança qualquer registro anterior do mesmo elemento. Elementos inválidos, chaves de renderização vazias e tags não vazias malformadas não carregam nada e produzem diagnósticos limitados. Essas condições não lançam erros 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.

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

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

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

O consentimento negado é definitivo para esse registro. Se for concedido mais tarde, registre o banner novamente ou recarregue a página. A retirada do consentimento e a falha do provedor também são definitivas; crie um novo registro depois de corrigir a causa. 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
consent_withdrawn
consent_source_failed
element_not_ready
runtime_disposed

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.

Banners.js

A integração automática com o Banners.js não faz parte de 0.1.0. Uma integração personalizada só pode usar o runtime se fornecer o elemento renderizado exato, verificationTag e resolvedBidId, e encerrar o registro conforme o ciclo de vida do banner. O suporte de primeira classe ao Banners.js será documentado separadamente quando estiver disponível.

Visão Geral

Plataforma de Anúncios

Servidor de Anúncios

Toppie

Integrações Avançadas

API

Biblioteca auxiliar de verificação de terceiros

Antes de começar

Passo 1: Configure o modelo de banner

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

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

Passo 4: Registre o banner renderizado

Uso do React

Conecte seu CMP

Verifique a integração

Content Security Policy

Banners.js

​Antes de começar

​Passo 1: Configure o modelo de banner

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

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

​Passo 4: Registre o banner renderizado

​Uso do React

​Conecte seu CMP

​Verifique a integração

​Content Security Policy

​Banners.js

Antes de começar

Passo 1: Configure o modelo de banner

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

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

Passo 4: Registre o banner renderizado

Uso do React

Conecte seu CMP

Verifique a integração

Content Security Policy

Banners.js