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, pausa ou encerra. Só são veiculados os criativos ativos de uma campanha ativa — pausar a campanha interrompe a entrega na hora.

Entre os criativos elegíveis o motor escolhe ao acaso, ponderado pelo peso que você dá a cada um. Um criativo com limite de entrega 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.

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 uma pessoa o verifica antes que suas zonas possam vender — um domínio sem verificação não pode receber repasse. Retirar um site inicia um resfriamento de 90 dias sobre o domínio: nesse período ninguém mais pode cadastrá-lo 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). Uma zona intersticial também declara quais links disparam a camada — por padrão p a, nav a, h2 a — e os segundos até poder fechá-la.

A etiqueta

Cole onde o anúncio deve aparecer. O id da zona vem do painel (Sites e zonas). A mesma etiqueta veicula todos os formatos que a zona aceita; uma zona intersticial também usa a etiqueta padrão.

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 undefined minutos e ninguém edita nenhum template (hoje serve v6, 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.

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 por criativo, zona, campanha, site ou host do referenciador. Só o host do referenciador é guardado, nunca a URL.

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