AD, tecnicamente: como funciona e como integrar

O que é

O que é o AD e para quem é

O AD é um servidor de anúncios direto: sem leilão e sem caixa-preta. Um publisher vende o espaço publicitário de um site que já opera; um anunciante escolhe as zonas exatas, define a segmentação e lança. Uma mesma conta pode ter qualquer um dos dois papéis — ou os dois.

Acesso

Como entrar

Entre em forhosting.com e escolha “Gerenciar meu AD” no menu da sua conta. O painel abre com uma sessão curta — uma credencial que expira em minutos (nunca mais de 60) e não deixa nenhuma chave permanente no navegador. Quando expirar, abra de novo pelo mesmo menu.

Para integrações, crie uma chave de API no painel (Perfil) ou com POST /tenants/:id/keys. Dois escopos: tenant (acesso completo à sua própria conta) e read (somente leitura, para painéis e bots). A chave é mostrada uma única vez; se for perdida, crie outra e revogue a antiga.

Nossa equipe pode abrir seu painel “como cliente” para ajudá-lo: essa sessão dura no máximo 15 minutos e leva o nome de quem a abriu. A casa nunca opera a sua conta com uma chave permanente.

Anunciantes

Campanhas e segmentação

A campanha é o contêiner: nome, datas, orçamentos opcionais e a segmentação compartilhada pelos seus criativos. Nasce como draft; você a coloca active, paused ou ended quando terminar. Só são veiculados os criativos ativos de uma campanha ativa — pausar a campanha interrompe a entrega na hora.

Entre as campanhas elegíveis o motor não sorteia ao acaso: ele alterna. Veicula uma, depois a outra, e só quando estão empatadas o peso que você deu a cada criativo desempata — mostrar dez vezes seguidas a mesma campanha ao mesmo visitante não vende nada. Os turnos são contados por visitante e por zona, no próprio navegador do visitante; com os cookies bloqueados, o motor volta ao sorteio ponderado. Um criativo com limite de entrega também tem pacing: a cada 5 minutos seu peso é reajustado para que o orçamento se distribua pelos dias da campanha em vez de queimar de manhã. O pacing só freia — nunca inventa tráfego.

Um criativo só é veiculado em uma zona onde tenha um pedido pago (veja “Comprar espaço”). Campanha, criativo, zona e pedido aparecem no painel (Campanhas, Criativos, Comprar espaço).

Anunciantes

Criativos: seis tipos, uma etiqueta

Todo criativo tem uma URL de clique, um tamanho fixo opcional e um peso. Os limites desta tabela são os que a API aplica no upload — são lidos do código, não escritos aqui.

O contrato HTML5

Seu index.html é carregado em um iframe com o destino do clique na query como clickTag. Leia-o e use-o como href da sua área clicável — essa URL é assinada e conta o clique; um link escrito à mão não conta.

// index.html — the click goes where the engine says
var clickTag = new URLSearchParams(location.search).get("clickTag");
document.getElementById("ad").href = clickTag;

Se o criativo precisar crescer, informe à página sua altura real com postMessage. A etiqueta também informa ao criativo a largura do espaço ao carregar e a cada redimensionamento, e envia visible na primeira vez que o espaço entra na tela — o momento de iniciar uma animação. Alturas de até 10000 px são aplicadas.

// creative → page: ask for the real height (applied up to 10000 px)
parent.postMessage({ fh: "resize", nh: document.documentElement.scrollHeight }, "*");

// page → creative: { fh: "size" | "visible" }
window.addEventListener("message", function (ev) {
  if (ev.data && ev.data.fh === "visible") { /* start your animation */ }
});

Um criativo mínimo que faz as duas coisas, pronto para enviar como está: baixe o ZIP de exemplo

Macros dos criativos script

Em um criativo script o motor substitui estes marcadores ao publicar a zona. Um template do painel é a mesma coisa com marcadores extras que você preenche em um formulário.

Vários destinos em um mesmo criativo

Um criativo pode levar até 8 destinos nomeados além da sua URL de clique principal — um botão da App Store e um do Google Play na mesma peça, por exemplo. Cada um tem um id de até 20 caracteres minúsculos; main é reservado para a URL principal.

Em um criativo HTML5 eles chegam na query como clickTag_<id>, ao lado do clickTag de sempre; em um criativo script você escreve [CLICKTAG:<id>]. Todos passam pelo rastreador de cliques, então somam no total e se detalham por botão nos relatórios.

Tracking de terceiros e consentimento

Qualquer criativo pode levar um código de tracking (um pixel ou script de um fornecedor de medição). Ele é emitido depois do anúncio com cada src convertido em data-src, de modo que nada carrega até a etiqueta permitir.

Se você informar o id IAB TCF v2 do fornecedor, o código só carrega após o consentimento do visitante para esse fornecedor, com ${GDPR} e ${GDPR_CONSENT_n} preenchidos. A etiqueta espera até 10 segundos pelo gestor de consentimento do site; sem id de fornecedor o código carrega como um elemento comum.

Revisão manual

Todo criativo nasce en_revision e é revisado por uma pessoa antes de poder ser veiculado. Aprovado, você o coloca active ou paused; rejeitado, você vê o motivo e pode corrigir e reenviar. Nada de um criativo sem revisão — nem o markup, nem o script, nem o código de tracking — chega a um visitante.

Alterar a URL de clique, o conteúdo ou o arquivo de um criativo aprovado o devolve à revisão: o que foi aprovado é o que é veiculado, nunca outra coisa.

Anunciantes

Comprar espaço

A vitrine lista todas as zonas à venda: site, tamanho, formatos aceitos, modelo de venda e o preço definido pelo publisher. Você escolhe uma zona, um criativo de um formato que a zona aceite, um valor e uma data de início. A cotação e a cobrança usam a mesma fórmula:

O pedido mínimo é $5; a cotação recusa qualquer valor abaixo. Um pedido é uma compra pré-paga de volume — o dinheiro se move uma vez, na compra. Envie uma idempotencyKey e uma requisição repetida devolve o mesmo pedido em vez de criar outro.

Como se paga

Quando um pedido é marcado como pago, 80% do seu preço final é creditado ao publisher da zona — sobre o pedido inteiro, não rateado pela entrega. A zona é republicada imediatamente e seu criativo começa a veicular no minuto seguinte.

Publishers

Sites, zonas, etiqueta e pagamentos

Sites

Cadastre um site pelo domínio (Seja um publisher). Ele nasce pendente e se verifica sozinho: publique o token que damos em /.well-known/fh-ad-site-verification.txt ou na home, peça a verificação e o site se ativa por conta própria — sem fila e sem que ninguém daqui precise olhar antes. Um domínio sem verificação não pode receber repasse. Retirar um site inicia uma quarentena de 90 dias sobre o domínio: ninguém mais pode cadastrá-lo enquanto isso e herdar seu histórico.

Zonas

A zona é o espaço vendável: um nome, um tamanho em pixels (ou -1 para largura adaptável), os formatos que aceita, um modelo de venda com seu preço e se está à venda na vitrine. Você pode definir um criativo de reserva próprio que veicula quando nenhum outro é elegível — ele ignora segmentação e limites.

Dois comportamentos opcionais rodam no navegador do visitante: a atualização automática (uma nova requisição a cada N segundos, mínimo 5; uma aba oculta nunca atualiza, e um espaço que volta vazio mantém o anúncio anterior) e o repasse de parâmetros (a query da página viaja com o clique até o destino do anunciante).

Como o intersticial é disparado

O overlay é uma propriedade da zona, não do site: não é preciso colar nada para ele — a tag constrói o que precisa — e você muda o ritmo no painel onde compra. Quatro modos:

Um ritmo fixo cansa o visitante no dia 30 tanto quanto no dia 1 — é para isso que serve o calendário escalonado: cobra a primeira impressão cedo e depois sai de cena. A contagem fica no próprio navegador do visitante; se o armazenamento estiver bloqueado, ela passa a contar na memória em vez de quebrar.

Quando os anúncios são pedidos — o seu site vem primeiro

Os anúncios não podem deixar o seu site lento, e o ajuste fica aqui, não no seu HTML. Cada site escolhe quando a etiqueta pede o primeiro anúncio:

E enquanto o anúncio está a caminho o espaço não fica em branco: a etiqueta pinta um marcador de lugar e aprende a altura — a primeira visita reserva um tamanho prudente e, a partir da segunda, o espaço reservado é o exato, então a página não pula quando o anúncio chega. Esse pulo é o que o Google mede como layout shift, e é o motivo habitual de uma rede de anúncios custar a nota de um site.

A etiqueta

Cole onde o anúncio deve aparecer — ou deixe a zona dizer onde fica e pule esta etapa inteira (veja «Onde sai o anúncio», mais abaixo). O id da zona vem do painel (Sites e zonas). A mesma tag serve todos os formatos que a zona aceita; uma zona intersticial usa a tag padrão também.

Padrão (um div e um script, assíncrona):

<div data-fh-ad="zon_XXXXXXXXXXXXXXXXXXXXXXXX"></div>
<script src="https://api.ad.forhosting.com/ad-tag.js" async></script>

Legada, para CMS que não executam scripts assíncronos:

<script src="https://api.ad.forhosting.com/ad-serve?zone=zon_XXXXXXXXXXXXXXXXXXXXXXXX&mode=js"></script>

Link de texto: uma URL que conta a impressão e redireciona ao anunciante:

https://api.ad.forhosting.com/ad-serve?zone=zon_XXXXXXXXXXXXXXXXXXXXXXXX&mode=link

A etiqueta se atualiza sozinha: sua URL não leva versão e nunca muda, então uma melhoria nossa chega a todos os sites em cerca de 60 minutos e ninguém edita nenhum template (hoje serve v11, no cabeçalho x-tag-version). Espera sua página terminar de carregar antes de pedir qualquer coisa, então os anúncios nunca competem com o seu conteúdo. Suas únicas marcas na sua página são o atributo data-fh-ad e o id do overlay — verificados contra as listas comuns de bloqueio, com zero coincidências. Os limites de frequência usam um cookie próprio.

Se a mesma posição se repete ao longo de uma página — “a cada N mensagens” em um fórum, por exemplo —, a etiqueta pede todas as suas cópias em uma única requisição (até 10), e o limite de frequência avança dentro desse lote, então um mesmo criativo não pode preencher todos os espaços da página. Se o nosso lado não entender o lote, a etiqueta volta a pedir um espaço de cada vez em vez de deixar a página vazia. Repetir uma zona é declarado conosco: como regra, uma zona por posição, porque a zona é o que um relatório agrupa.

Onde sai o anúncio — sem mexer no seu tema

Uma zona pode declarar onde fica: um seletor CSS (até 300 caracteres) e uma posição em relação ao que esse seletor encontrar. O espaço é criado pela tag, então mover um anúncio custa uma mudança no painel e não uma edição do seu tema.

Dois números opcionais governam a repetição: um coloca o espaço a cada N ocorrências (até 50) e um teto limita quantos espaços são criados — 4 por omissão quando há repetição, 20 no máximo. Sempre há teto: um seletor solto como p casa centenas de vezes num artigo longo, e esse limite não pode depender de quem configura lembrar de colocá-lo.

Duas coisas que vale saber. Um div data-fh-ad que você mesmo coloque no tema manda: a tag não vai criar um segundo espaço para essa zona, então dá para migrar de um método ao outro sem pagar duas impressões por uma. E um seletor que não casa não dá erro — a página fica perfeita sem o anúncio e o painel continua verde. Confira a colocação num navegador, no desktop e no celular: um seletor pode existir no artigo e não na home, ou medir 1360 px no desktop e 0 no telefone.

WordPress: nada para colar

Se o seu site é WordPress há um plugin, forhosting-ad. Instale e ele se apresenta sozinho: publica um desafio no seu próprio domínio, nós lemos, e a credencial é entregue uma única vez. Você não digita nenhuma chave, nenhum id nem nenhum token — e provar que controla o domínio não é o mesmo que ter sido convidado: nada é emitido até que o site seja aprovado.

A partir daí as zonas são geridas pelo painel, colocação incluída. O plugin ainda pede ao cache de páginas que o seu site usar que limpe as páginas cujo HTML mudou — reconhece os habituais e pede a cada um do seu jeito. Uma página em cache é o motivo mais comum de a tag estar no seu HTML e o anúncio continuar não aparecendo, e isso não se vê pela linha de comando: a cópia velha só é servida a um navegador de verdade.

Há um segundo plugin, forhosting-ad-updater, que recebe um pacote e o instala. Isso é, por desenho, um canal de execução remota, então só o instalamos em sites nossos; no seu, as atualizações chegam pelo canal próprio do WordPress e você decide quando aplicá-las.

Pagamentos

Seus 80% de cada pedido pago se acumulam no painel (Pagamentos). Quando o acumulado chega a $10, solicite o pagamento com o método do seu perfil (paypal, bank, other); nossa equipe paga fora do painel e registra a referência.

Estados: accrued → requested → processing → paid; um desembolso que falha volta para você com o motivo, para que solicite de novo com os dados corrigidos.

Para todos

Relatórios

Impressões, cliques e início/fim de vídeo são contados na borda, a cada requisição. Antes de contar, o tráfego é filtrado: rastreadores conhecidos pelo user agent, redes de data center, requisições com pontuação de bot muito baixa e qualquer IP que repita a mesma requisição em menos de 2 segundos. Uma requisição filtrada recebe o anúncio ou o redirecionamento do mesmo jeito — o que se protege é o contador.

A cada 5 minutos as contagens são consolidadas em linhas diárias por criativo, zona e host do referenciador. O dia em curso pode atrasar até esse tempo; os dias fechados nunca mudam.

O painel (Relatórios) mostra totais e uma série diária, o CTR (cliques ÷ impressões × 100) e o eCPM (valor entregue × 1000 ÷ impressões), para o lado anunciante ou o lado publisher, e um ranking agrupado por qualquer uma de seis dimensões:

Qualquer uma dessas visões também pode ser filtrada por campanha, criativo, zona, host do referenciador ou destino, e os mesmos números estão disponíveis pela API.

Antes de qualquer contagem, o tráfego passa pelo filtro de bots, que a casa opera em um de três modos: block (o padrão: as requisições filtradas recebem o anúncio do mesmo jeito, só não contam), log (contam e ficam registradas à parte, para medir antes de decidir) e off.

Integrar

Referência da API

URL base https://api.ad.forhosting.com. Envie sua chave como token Bearer; corpos e respostas são JSON. Toda resposta tem a forma {"success":true,"data":…} ou {"success":false,"error":{"code","message"}} com o status HTTP correspondente.

curl https://api.ad.forhosting.com/me \
  -H "Authorization: Bearer ads_ten_…"

Escopos das credenciais

Uma credencial tenant, read ou session opera sempre a sua própria conta — um tenantId enviado pelo cliente é ignorado. Um id que pertence a outro devolve 404, não 403: a API nunca confirma que ele existe.

Rotas

Todas as rotas que o serviço anuncia, com o escopo que o roteador exige — derivado do próprio roteador a cada build.

pública: sem credencial — o caminho de veiculação · qualquer: qualquer credencial válida, na sua própria conta · leitura: tenant, session ou read · escrita: tenant ou session (read é recusado) · system: só a casa

Erros que vale conhecer: 401 unauthorized (credencial ausente ou expirada), 403 forbidden (o escopo não pode fazer isso), 404 not_found, 400 bad_request com o motivo na mensagem, 409 conflict (uma transição de estado não permitida), 402 insufficient_balance ao pagar um pedido e 503 payments_disabled se as vendas estiverem pausadas.

FAQ

Perguntas técnicas