Guia de configuração do Prebid.js: do zero ao seu primeiro leilão em produção

Por Ataíde Penteado · Atualizado em 4 de novembro de 2026

Comece a configuração do Prebid.js com uma build personalizada no lado do cliente, um bloco de anúncios de display já validado e poucos bidders. Defina um timeout de leilão que você consiga justificar e configure os itens de linha no GAM para corresponder aos valores de hb_pb e hb_bidder enviados pelo Prebid via GPT. Valide esse fluxo em produção. Com a integração funcionando sem falhas, amplie a lista de bidders e os formatos, implemente a atualização de anúncios ou adicione o Prebid Server.

Principais pontos

Use uma build personalizada do Prebid.js e mantenha apenas os adaptadores e módulos necessários para a entrada em produção.
Escolha os bidders pelo ganho mensurável, não pela quantidade de nomes que você consegue adicionar ao wrapper.
Alinhe os buckets de preço do Prebid, a sequência de execução do GPT e os itens de linha do GAM antes de entrar em produção.
Teste a segmentação, os tempos de execução e as falhas silenciosas, não apenas se os lances aparecem no navegador.
O risco para a receita na primeira semana costuma vir de desvios na configuração, não do leilão em si.

Onde o Prebid.js se encaixa na estrutura de header bidding

O Prebid.js roda o leilão no navegador, antes de enviar a solicitação ao servidor de anúncios. Google Ad Manager continua decidindo qual anúncio será veiculado. O papel do Prebid.js é coordenar a demanda: chamar os adaptadores, receber os lances e definir a segmentação. Configurar itens de linha, hospedar criativos e fazer previsões de entrega ficam fora desse escopo. Ele também não passa por cima das regras de prioridade do GAM.

Para colocar o primeiro leilão em produção, siga a ordem da integração. Carregue a build personalizada do Prebid.js, defina os blocos de anúncios e solicite lances aos adaptadores selecionados. Espere o leilão terminar, chame setTargetingForGPTAsync e só então libere o GPT para solicitar o anúncio ao GAM. Essa ordem importa. A documentação para desenvolvedores do Prebid.org descreve o fluxo básico de impressão e seus componentes nos materiais de primeiros passos Documentação do Prebid.org.

Essa divisão de responsabilidades ajuda a localizar muitas falhas na estreia em produção. Os lances aparecem no navegador, mas o GAM entrega um anúncio institucional? Não comece refazendo a build do wrapper. Confira se hb_pb e hb_bidder chegaram ao slot do GPT e se o item de linha correspondente no GAM está qualificado para veiculação, com o criativo associado. Depois, verifique se uma campanha de prioridade mais alta, uma proteção ou uma incompatibilidade de tamanho bloqueou a entrega.

A divisão de tarefas na prática

O Prebid.js controla a solicitação do leilão. É ele que define quais adaptadores de bidders serão chamados para cada bloco de anúncios e quais tipos de mídia podem participar. Também determina o tempo de resposta dos bidders, o agrupamento dos preços dos lances em buckets e as chaves-valor que o GPT vai repassar ao GAM.

O GPT controla a solicitação de anúncio ao GAM. Cabe a ele definir os slots, gerenciar o comportamento das solicitações no nível da página e determinar quando a segmentação chega ao GAM. Dali em diante, o GAM avalia os itens de linha qualificados e suas prioridades. Entram nessa avaliação as chaves-valor, a compatibilidade dos criativos, os roadblocks, as configurações de frequência, as exclusões competitivas, as proteções e a demanda de venda direta.

Trabalhe com uma divisão clara: o Prebid coleta lances e grava sinais; o GAM usa esses sinais para monetizar o inventário conforme a configuração das campanhas. Isso orienta a investigação de problemas. Se um item de linha aponta para o bloco de anúncios errado, corrija o GAM, não refaça o Prebid. Se um adaptador não é acionado no navegador, alterar as prioridades do GAM não resolve.

Quando o Prebid.js no lado do cliente já não é suficiente

Uma implementação inteiramente no lado do cliente funciona melhor com poucos bidders, peso de página sob controle e tratamento de consentimento bem entendido. A depuração fica concentrada no navegador. Os limites aparecem quando cada posicionamento chama uma lista extensa de adaptadores ou quando a latência já é perceptível nos templates para dispositivos móveis. Outro sinal para rever a configuração: um parceiro de demanda entrega melhor desempenho pelo lado do servidor.

Nessas condições, vale testar o Prebid Server ou uma configuração híbrida separadamente. O guia da Playwire organiza o ecossistema por implementação: Prebid.js no lado do cliente e Prebid Server no lado do servidor, além de Prebid Mobile e Prebid Vídeo para outras necessidades Playwire. Levar mais operações para o lado do servidor pode aliviar o trabalho do navegador. A contrapartida aparece na gestão de identidade, nos relatórios, no diagnóstico de problemas e na configuração dos parceiros, que também mudam.

Para a primeira implantação no site de um publisher de médio a grande porte dos EUA, o Prebid.js no lado do cliente costuma ser a opção mais segura para levar um leilão controlado à produção. Mas exige disciplina. Cada adaptador ou módulo acrescentado, assim como cada exceção de bloco de anúncios e mapeamento no GAM, abre mais um ponto para problemas de latência, consentimento, segmentação ou relatórios.

Monte o wrapper do jeito certo: instale, personalize e mantenha tudo enxuto

Monte uma build personalizada do Prebid.js com apenas os adaptadores de bidders e os módulos necessários para a estreia. Deixe o restante de fora. O guia de implementação do MonetizationGuy recomenda o mesmo caminho: baixar um arquivo Prebid.js personalizado, incluindo somente os adaptadores que você pretende usar. Assim, o arquivo que vai para produção fica menor MonetizationGuy. Você encontra o projeto de código aberto e os materiais para desenvolvedores do ecossistema Prebid.js no GitHub e na documentação GitHub.

Comece pelo projeto e pela documentação oficiais, não por um wrapper copiado de uma propriedade antiga. O repositório prebid/Prebid.js no GitHub descreve o Prebid.js como um software gratuito e de código aberto e direciona os desenvolvedores à documentação e a exemplos funcionais para os detalhes de implementação GitHub prebid/Prebid.js.
Crie uma compilação personalizada em vez de colocar em produção adaptadores de bidders que você não usa. O passo a passo de implementação do Monetization Guy apresenta essa orientação como a primeira ação prática da configuração: baixe uma versão personalizada que inclua apenas os adaptadores com os quais você pretende trabalhar, para manter o arquivo menor e facilitar a preservação do desempenho de carregamento da página Monetization Guy.
Selecione apenas os módulos essenciais para o lançamento. Na primeira versão, isso geralmente significa adaptadores de bidders, os tipos de mídia que você realmente vende, suporte a consentimento se o seu tráfego exigir, tratamento de moedas se os lances chegarem em várias moedas e analytics somente se alguém for usar os dados durante a semana de lançamento.
Defina os blocos de anúncios de modo que reflitam seu inventário no GAM. Use códigos estáveis, tamanhos reais e parâmetros de bidders compatíveis com os contratos assinados com os parceiros. Não deixe nomes de desenvolvimento como div-gpt-ad-test-1 chegarem ao mapeamento de produção sem que sua equipe de ad ops consiga reconhecê-los depois.
Defina a granularidade de preços antes de configurar os itens de linha. O GAM não consegue fazer a correspondência de preços para os quais você não criou itens de linha, e o Prebid não deve enviar faixas de preço que a configuração do seu ad server não consegue monetizar. Se usar faixas personalizadas, documente o preço máximo, o incremento, a moeda considerada e qual intervalo de itens de linha corresponde a cada faixa.
Decida se a conversão de moedas deve entrar no primeiro build. Se todos os bidders da estreia operam em USD e sua rede do GAM está configurada em USD, mantenha o tratamento de moedas simples. Se você recebe demanda em outras moedas, configure a conversão de maneira planejada, em vez de deixar as equipes de relatórios conciliarem valores de lances inconsistentes após a entrada em produção.
Integre a gestão de consentimento apenas no grau exigido pelos seus requisitos jurídicos e de produto. Se seu site depende de uma plataforma de gestão de consentimento e de sinais do IAB TCF, inclua o fluxo da CMP no QA de lançamento, em vez de deixá-lo como uma tarefa de privacidade para depois. A lógica de consentimento pode mudar quais bidders são chamados, quais IDs de usuário ficam disponíveis e se os parceiros de demanda retornam lances.
Deixe vídeo fora da primeira entrada em produção de display na web, a menos que esse inventário faça parte da entrega. O Prebid Vídeo tem uma implementação própria dentro do ecossistema Prebid, e incluí-lo em uma estreia voltada apenas a display acrescenta verificações de criativos, renderizadores, players e relatórios que não ajudam no primeiro leilão.
Versione o build e mantenha um histórico de alterações que a equipe de ad ops consiga entender. Registre a versão do Prebid.js, os adaptadores, os módulos, o timeout, a granularidade de preços e a data do mapeamento no GAM. Quando a receita mudar após uma atualização, você precisa saber se a mudança ocorreu no wrapper, na demanda ou no GAM.
Carregue o wrapper na sequência da página que você pretende usar em produção. Um build que funciona em um exemplo local ainda pode falhar quando seu site real tem lazy loading, rolagem infinita, bloqueios por consentimento, roteamento de aplicação de página única, regras de atualização de anúncios ou scripts concorrentes que interagem com o GPT.

Mantenha o primeiro build enxuto para facilitar a operação. A estética não entra nessa conta. Com menos adaptadores, você tem menos chamadas de rede para inspecionar e parâmetros de bidders para validar, além de menos exceções de consentimento e bugs específicos de cada adaptador para investigar. Acrescente complexidade quando um posicionamento já tiver comprovado que Prebid, GPT e GAM estão alinhados no mesmo leilão.

Escolha bidders, defina timeouts e evite os erros comuns que prejudicam a receita

Para colocar um leilão mínimo em produção, escolha um build personalizado do Prebid.js com apenas os bidders que você vai chamar na estreia. Carregue esse arquivo antes do código do leilão. Defina um bloco de anúncios de display, por exemplo: code: 'top_leaderboard', mediaTypes: { banner: { sizes: [[728,90],[970,250]] } }, bids: [{ bidder: 'yourBidder', params: { placementId: 'provided_by_partner' } }]. Em produção, use os parâmetros reais fornecidos pelo parceiro. Os valores de exemplo ficam fora.

Decisão de configuração	O que verificar	Regra operacional	Falha comum ao ignorar a regra	Fonte de referência
Qualidade da demanda do bidder	O parceiro tem demanda real para seu segmento, sua região, sua distribuição de dispositivos e seus formatos?	Adicione um bidder somente se você souber indicar em qual inventário ele deve vencer e em quais blocos de anúncios deve competir.	Um bidder permanece no wrapper porque está aprovado, não porque vence leilões que trazem resultado.	O Prebid.js permite que vários parceiros de demanda deem lances pelo inventário por meio de adaptadores; o valor depende de uma implementação cuidadosa, não apenas da quantidade de adaptadores Playwire.
Confiabilidade do adaptador	O adaptador recebe suporte ativo, está parametrizado corretamente e é compatível com seus tipos de mídia?	Valide um posicionamento por formato antes de expandir para o restante do site.	As requisições de lance são disparadas, mas os parâmetros estão errados, as respostas sem lance parecem normais e o parceiro nunca chega a competir.	O projeto de código aberto Prebid.js orienta quem faz a implementação a usar documentação atualizada e exemplos funcionais, em vez de tratar código copiado como referência definitiva GitHub prebid/Prebid.js.
Perfil de latência	Quanto tempo o bidder leva para responder em desktop, web móvel e tráfego de refresh?	Na implantação, use um timeout justificável por dispositivo e posicionamento; teste de 700 a 1.200 ms como faixa inicial e depois ajuste com base nas respostas que chegam fora do prazo.	Uma demanda lenta obriga o GPT a esperar, enquanto um timeout curto demais descarta lances antes que o leilão reúna competição suficiente para fazer diferença.	A documentação para desenvolvedores do Prebid.org inclui exemplos de refresh por unidade de anúncio e rolagem infinita, justamente os casos em que o comportamento dos tempos exige testes de QA específicos documentação do Prebid.org.
Carga de manutenção	Quem é responsável pelo relacionamento com o parceiro do adaptador, pelas alterações de parâmetros, pelos requisitos de schain ou sincronização de usuários e pela conciliação de relatórios?	Remova bidders que exigem tratamento constante de exceções sem contribuição visível para o leilão.	O wrapper vira um depósito de parceiros legados, e cada versão leva mais tempo para ser testada.	As orientações de implementação para publishers recomendam baixar uma versão personalizada do Prebid.js apenas com os adaptadores previstos, pois componentes sem uso aumentam o peso e a complexidade Monetization Guy.
Adequação ao posicionamento	Esse bidder deve rodar em todas as unidades de anúncio ou apenas nos posicionamentos de alto valor?	Não habilite, por padrão, a lista completa de bidders em inventário com baixa visibilidade, móvel, abaixo da dobra ou com alta frequência de refresh.	Impressões de baixo valor pagam um custo de latência que a demanda não consegue compensar.	Os exemplos documentados do Prebid incluem diferentes configurações de inventário, como refresh e múltiplos formatos, que devem ser configuradas de forma deliberada, em vez de copiadas para todos os slots documentação do Prebid.org.

Coloque a lógica do leilão na fila pbjs.que. Assim, ela espera o Prebid carregar: var pbjs = pbjs || {}; pbjs.que = pbjs.que || []; pbjs.que.push(function(){ pbjs.addAdUnits(adUnits); pbjs.requestBids({ timeout: 1000, bidsBackHandler: function(){ pbjs.setTargetingForGPTAsync(['top_leaderboard']); googletag.cmd.push(function(){ googletag.pubads().refresh([topSlot]); }); } }); });. O timeout de 1000 é um exemplo, não uma recomendação para qualquer página. Defina o seu com base nos resultados dos testes na própria página.

A sequência do GPT precisa acompanhar a do leilão. Defina o slot antes de atualizá-lo: googletag.cmd.push(function(){ topSlot = googletag.defineSlot('/1234567/site/top_leaderboard', [[728,90],[970,250]], 'div-gpt-top').addService(googletag.pubads()); googletag.pubads().disableInitialLoad(); googletag.enableServices(); });. O ponto é este: a requisição de anúncio ao GAM só pode sair depois que setTargetingForGPTAsync tiver definido as chaves do Prebid para esse slot.

O critério de corte dos bidders no lançamento

Na configuração básica do GAM, crie as chaves-valor hb_pb e hb_bidder com os valores que a sua configuração do Prebid envia. Configure os itens de linha para segmentar esses valores e o mesmo bloco de anúncios.

Associe um criativo do Prebid que renderize o lance vencedor pelo ID do anúncio no leilão e inclua todos os tamanhos permitidos no bloco do Prebid. Durante o teste de veiculação, confira também a prioridade: o item de linha não deve perder para anúncios internos ou demanda direta por causa dessa configuração.

Escolha os bidders da estreia pela adequação ao posicionamento e pelo suporte que você consegue manter. A quantidade de parceiros não deve guiar essa decisão.

Para continuar na lista, o bidder precisa ter o adaptador acionado e os parâmetros obrigatórios preenchidos, responder dentro do timeout com frequência suficiente para fazer diferença e enviar lances compatíveis com os itens de linha do GAM. O parceiro também precisa ter um papel claro nesse inventário.

Aplique o mesmo critério ao tráfego com refresh: em blocos sticky, rolagem infinita e posicionamentos com refresh rápido, comece com menos bidders. Amplie a lista quando conseguir analisar a latência e a densidade de lances por posicionamento.

Uma comparação prática das opções de configuração antes do lançamento

Lançamento enxuto no client-side: o bundle fica menor porque o build personalizado leva apenas os adaptadores e módulos necessários. Entre as opções client-side, é a de menor risco de latência, já que executa menos adaptadores no navegador. A depuração também é mais simples: você vê as chamadas dos adaptadores e a segmentação nas ferramentas do navegador. No GAM, começar com um único padrão de faixas de preço reduz a complexidade da configuração. É a opção mais segura para o lançamento, indicada para quem precisa colocar um leilão em produção sem problemas e só depois expandir. Sobre as fontes: os materiais para desenvolvedores do Prebid e o GitHub cobrem builds personalizados e exemplos funcionais. Documentação do Prebid.org GitHub.

Lançamento mais amplo no client-side: mais adaptadores e módulos chegam ao navegador, aumentando o tamanho do bundle. As chamadas adicionais aos bidders elevam o risco de latência. Depurar também dá mais trabalho, com mais ocorrências de no-bid, timeouts e parâmetros sobrepostos para investigar. No GAM, a configuração fica mais complexa quando os posicionamentos usam tamanhos ou faixas de preço diferentes. A segurança do lançamento é média. Essa opção faz mais sentido para uma equipe que já validou os parâmetros dos bidders e tem os modelos de configuração do GAM prontos. Sobre a fonte: o modelo de componentes do Prebid e as orientações para builds personalizados recomendam incluir apenas os componentes necessários. Documentação do Prebid.org.

Configuração híbrida com Prebid.js e Prebid Server: a demanda server-side pode reduzir o peso do bundle no navegador, mas transfere a complexidade de implementação para a configuração do servidor. Em páginas que sobrecarregam o navegador, a latência pode cair. O resultado depende da identidade, da configuração dos parceiros e do roteamento. Como parte do leilão acontece fora do navegador, a depuração fica mais difícil. No GAM, a complexidade permanece semelhante se você mantiver as mesmas chaves de segmentação e faixas de preço; já a conciliação dos relatórios exige mais trabalho. Para um primeiro leilão, a segurança do lançamento é de média a baixa. Esse caminho é mais indicado para quem já comprovou que a latência no navegador ou o peso da página é o gargalo. Sobre a fonte: a Playwire apresenta Prebid.js e Prebid Server como caminhos distintos de implementação. Playwire.

No lançamento conservador por etapas, o impacto no tamanho do bundle começa baixo e só cresce depois do controle de qualidade. Você estabelece uma linha de base antes de adicionar cada bidder ou posicionamento, o que ajuda a controlar o risco de latência e mantém a depuração administrável.

A configuração no GAM também avança em lotes planejados. É a opção mais segura para lançar em múltiplas propriedades, especialmente para publishers de médio a grande porte com muitos templates, regras de refresh ou unidades de negócio que não podem absorver os problemas de um lançamento mal executado.

Caminho de configuração	Mais indicado para	Pressão sobre o tamanho do bundle	Risco de latência	Facilidade de depuração	Complexidade no GAM	Segurança na entrada em produção	Referência de apoio
Build enxuto no client-side: poucos adaptadores, apenas display, seleção conservadora de módulos	Publisher que está implementando Prebid.js nos posicionamentos prioritários de display com um grupo pequeno de parceiros de demanda já validados	Baixo, porque adaptadores e módulos não utilizados ficam de fora	Moderado, porque todas as chamadas aos bidders ainda são executadas no navegador	Alta, porque as ferramentas de desenvolvedor do navegador e o Professor Prebid permitem observar a maior parte do comportamento do leilão	Moderada, desde que as faixas de preço e os pares de chave-valor correspondam aos itens de linha	Alta para um primeiro leilão em produção; caminho mais simples para isolar falhas	A Monetization Guy recomenda builds personalizados apenas com os adaptadores previstos para reduzir o tamanho do arquivo e preservar o desempenho de carregamento.
Build amplo no client-side: muitos adaptadores, vários formatos, analytics desde o primeiro dia	Publisher com uma operação de ad ops madura e demanda de parceiros existentes que precisa ser testada em conjunto	Alto, porque cada adaptador ou módulo adicionado aumenta o volume de código entregue e a matriz de testes de QA	Alto, especialmente na web móvel e em templates com uso intenso de refresh	Moderada a baixa, porque as falhas podem se sobrepor entre adaptadores, formatos e fluxos de consentimento	Alta, porque é preciso alinhar mais faixas de preço, premissas sobre os criativos e exceções por bloco de anúncios	Menor, a menos que a equipe tenha um ambiente de homologação que reproduza o comportamento dos anúncios em produção	O Prebid.org documenta vários componentes e exemplos, incluindo anúncios multiformato, native, vídeo, refresh e analytics, que devem ser tratados como frentes de implementação separadas segundo a documentação do Prebid.org.
Configuração híbrida com Prebid.js e Prebid Server	Publisher que precisa de controle no lado do cliente para alguns parceiros, mas quer transferir parte da demanda para fora do navegador	Moderado, porque parte do processamento sai da página, mas o código no cliente permanece	Variável; a carga no navegador pode diminuir, mas a configuração do fluxo no servidor e o comportamento da identidade precisam ser revisados	Moderado, porque a depuração no navegador deixa de mostrar todo o caminho da demanda	Moderado a alto, dependendo de a demanda no servidor usar a mesma lógica de preços e segmentação	Boa opção depois de validar o mapeamento dos parceiros; arriscada se for usada para esconder uma implementação inicial complexa demais	A Playwire identifica o Prebid Server como um componente separado do ecossistema Prebid que opera no servidor, e não como um substituto direto do Prebid.js segundo a Playwire.
Implementação inicial com timeout e pisos de preço conservadores	Publisher que prioriza renderização estável, visibilidade e facilidade de validação no GAM em vez do maior volume inicial de lances possível	Baixo a moderado, dependendo do número de bidders	Menor, porque os leilões encerram de maneira previsível	Alta, porque há menos respostas atrasadas para complicar a interpretação	Moderado, porque os intervalos de preço ainda precisam de correspondência exata	Alta quando o objetivo é estabelecer uma referência inicial consistente antes de ampliar o yield	O fluxo do Prebid envia os resultados do leilão para a segmentação do servidor de anúncios, por isso tempos previsíveis facilitam a validação do repasse ao GPT segundo a documentação do Prebid.org.
Timeout agressivo ou testes abrangentes de pisos de preço desde o primeiro dia	Publisher que já tem um wrapper maduro e um plano de experimentação controlado, não uma primeira implementação	Não muda com o timeout, mas costuma vir acompanhado de mais fontes de demanda	Alto se os bidders que demoram a responder puderem reter a requisição de anúncio por tempo demais	Baixo durante o lançamento, porque respostas fora do timeout, lances baixos e efeitos dos pisos de preço se confundem	Alto, porque os itens de linha e os buckets de preço no GAM precisam cobrir as faixas do teste	Baixo para a primeira entrada em produção; melhor como otimização de segunda fase	O projeto no GitHub apresenta o Prebid.js como um software de código aberto com documentação e exemplos, o que oferece flexibilidade, mas não elimina a necessidade de controles operacionais GitHub prebid/Prebid.js.

Na maioria das primeiras implantações, comece com uma versão client-side enxuta ou avance por etapas conservadoras. Ambas dão a você uma base de referência confiável. Primeiro, confirme que o leilão resulta em uma veiculação pelo GAM com o criativo esperado do Prebid. A partir daí, adicionar um bidder ou testar o Prebid Server vira um experimento controlado. Sem essa base, você corre o risco de transformar a expansão em uma operação de resgate.

Ampliar a abordagem só compensa quando você sabe onde está o gargalo. O navegador demora para executar o código? Teste a demanda híbrida primeiro no template lento. Se faltar pressão de preços em um posicionamento premium, aumente a cobertura de bidders ali antes de alterar o inventário de menor valor. Já se o GAM estiver rejeitando lances válidos, resolva a configuração de veiculação. Trocar a arquitetura não corrige esse problema.

Conecte o Prebid.js ao Google Ad Manager sem quebrar a lógica dos itens de linha

O Prebid.js só gera receita quando o lance vencedor vira segmentação no GAM e encontra itens de linha e criativos elegíveis. Uma resposta de lance válida no navegador não basta. O GAM vai ignorá-la se o valor de hb_pb não corresponder a um item de linha, se a segmentação de hb_bidder estiver incorreta ou se houver erro no mapeamento dos slots. Disparar a requisição de anúncio antes de definir a segmentação leva ao mesmo resultado.

A sequência básica é esta: defina os slots do GPT, execute o leilão do Prebid e aplique a segmentação aos slots correspondentes do GPT. Só então faça a requisição de anúncio ao GAM. Se o GPT pedir o anúncio antes de o Prebid definir a segmentação, o GAM avaliará a impressão sem os sinais do lance. Para implementar esse fluxo, use como referência os materiais e exemplos para desenvolvedores do Prebid Documentação do Prebid.org.

Os pares chave-valor e os buckets de preço precisam corresponder exatamente

As chaves padrão de segmentação do Prebid precisam encontrar uma configuração correspondente no GAM. Sem isso, não têm utilidade. Em uma implantação básica de display, hb_pb informa o bucket de preço e hb_bidder identifica o bidder. Já o criativo do Prebid usa o ID do anúncio no leilão para renderizar o vencedor. Só aprove o código quando a equipe de ad ops conseguir conferir esses valores exatos tanto no navegador quanto na segmentação do GAM.

O bucket de preço é um ponto frágil. Se o Prebid arredondar um lance para um bucket sem item de linha elegível no GAM, o leilão pode parecer saudável no navegador sem gerar receita. Confira também se o GAM usa o mesmo nome de chave, formato de valor, bloco de anúncios e tipo de correspondência que o Prebid define via GPT. Uma divergência em qualquer um desses pontos produz a mesma falha.

A granularidade de preços não pode ficar só nas mãos dos desenvolvedores. Ad ops precisa conhecer a estrutura dos buckets para configurar a veiculação; a engenharia precisa receber os nomes definitivos dos pares chave-valor antes da publicação. O Prebid.org trata a granularidade de preços personalizada em seus tópicos para desenvolvedores. O recado para a implementação é direto: desenhe os buckets durante o planejamento, em vez de deixar essa decisão para os ajustes após o lançamento Documentação do Prebid.org.

A sequência de execução do GPT determina se o leilão entra na decisão

O GPT faz a comunicação com o GAM. Por isso, o momento da requisição define se a segmentação do Prebid estará disponível quando o GAM tomar a decisão. Defina o slot do GPT e adie a requisição inicial, se necessário. Execute requestBids, chame setTargetingForGPTAsync para o slot e só depois chame display ou refresh. Nas atualizações seguintes do slot, rode um novo leilão ou escolha, de maneira deliberada, um fluxo sem Prebid para aquela atualização.

Em aplicações de página única e templates com rolagem infinita, há mais oportunidades para esse fluxo falhar. Cada slot inserido precisa de definição própria no GPT e mapeamento de unidade de anúncio no Prebid. Depois vêm o leilão, a gravação da segmentação e a solicitação de anúncio. Para atualizar um slot, você também precisa de uma nova lógica de lances. Cuidado com valores antigos de hb_pb ou hb_bidder: os anúncios podem continuar aparecendo mesmo com a integridade do leilão comprometida.

Mantenha os nomes dos slots consistentes nas unidades de anúncio do Prebid, nos slots do GPT e nas unidades de anúncio do GAM. Considere um código top_leaderboard no Prebid cuja solicitação do GPT aponta para outra div ou outro caminho no GAM. O console de depuração pode mostrar os dois objetos e dar a impressão de que tudo está no lugar. Ainda assim, o GAM fica sem segmentação utilizável do Prebid para a impressão que você está tentando monetizar.

Os erros do GAM que parecem erros do Prebid

Os erros de configuração que mais custam costumam estar no básico das campanhas. O item de linha aponta para a unidade de anúncio errada no GAM, ou o criativo está ausente. Às vezes, o tamanho do criativo não corresponde ao slot.

Durante o teste, uma campanha de prioridade mais alta pode vencer o item de linha do Prebid. Confira também as chaves: hb_pb pode existir no Prebid e faltar no GAM, enquanto hb_bidder pode ter um formato de valor diferente da chave do bidder enviada pela página.

Receber uma resposta de lance não prova que esse lance pode gerar uma exibição. O GAM ainda precisa aplicar suas próprias regras. Proteções, rótulos e exclusões competitivas podem bloquear o item de linha vinculado ao Prebid. O mesmo vale para incompatibilidades de tamanho de criativo, configurações de frequência, patrocínios ou campanhas diretas de prioridade mais alta. O leilão no navegador pode ter funcionado corretamente e, mesmo assim, o item de linha ficar impedido de veicular.

Configure um posicionamento de teste e confira se ele funciona antes de ampliar a implantação. Comece com uma unidade de anúncio, um ou dois bidders, poucos tamanhos e uma configuração do GAM que você consiga inspecionar manualmente. Um exemplo: mapeie top_leaderboard no Prebid para a div do GPT do mesmo slot leaderboard, configure a segmentação por hb_pb e hb_bidder no GAM e confirme que o GAM renderiza o criativo do Prebid. Só então replique a configuração nas outras propriedades.

Testes antes de entrar em produção: o que verificar, o que ignorar e como detectar falhas silenciosas

No QA pelo navegador, percorra o fluxo inteiro. Ver um anúncio na tela não basta. Confira as requisições aos bidders no painel Network e inspecione os lances retornados com pbjs.getBidResponses(). Verifique se pbjs.setTargetingForGPTAsync gravou hb_pb e hb_bidder e abra o Google Publisher Console para examinar o slot do GAM. Para uma checagem visual rápida das chamadas de leilão e da segmentação, use o Professor Prebid. O GeeksforGeeks descreve a ferramenta como uma extensão do Chrome para depurar e analisar configurações do Prebid.js GeeksforGeeks.

Abra o template real da página com as ferramentas de desenvolvedor do navegador e confirme que seu arquivo Prebid.js é carregado uma única vez, a partir do caminho esperado e na versão esperada. Um wrapper duplicado pode gerar leilões conflitantes que parecem comportamento aleatório dos bidders.
Use o Professor Prebid para inspecionar unidades de anúncio, chamadas aos bidders, respostas de lances e valores de segmentação. O GeeksforGeeks descreve o Professor Prebid como uma extensão do Chrome para depurar e analisar configurações do Prebid.js, o que o torna útil para o QA de lançamento, mesmo que o diagnóstico mais aprofundado continue sendo feito nas ferramentas de desenvolvedor Professor Prebid.
Verifique as requisições aos bidders no painel de rede. Confirme que os adaptadores previstos são acionados apenas nos posicionamentos previstos e que os slots de dispositivos móveis, desktop, atualização e carregamento sob demanda não compartilham, por engano, a lista errada de bidders.
Inspecione as respostas de lances em relação ao timeout configurado. Separe os casos reais de ausência de lance dos lances atrasados e das chamadas bloqueadas. Uma resposta que chega após o encerramento do leilão pode aparecer nos registros de rede, mas não deve ser contabilizada como demanda disponível para aquela impressão.
Verifique a segmentação gravada pelo Prebid antes de o GPT enviar a solicitação de anúncio. Procure a faixa de preço, o bidder, o ID do anúncio e quaisquer chaves específicas do posicionamento das quais seus itens de linha no GAM dependam. Se a segmentação aparecer depois da solicitação ao GAM, a sequência está errada.
Confirme que a solicitação ao GAM contém os pares de chave-valor esperados. A segmentação do Prebid no navegador não basta; os valores precisam ser enviados na solicitação de anúncio que o GAM avalia.
Teste um item de linha em uma faixa de preço conhecida. Force uma condição restrita em que um lance deva corresponder à segmentação e verifique se o GAM exibe o criativo esperado. Isso revela a diferença entre “o leilão funciona” e “o ad server consegue veicular o vencedor do leilão.”
Execute testes dos estados de consentimento se sua implementação depender de uma plataforma de gestão de consentimento (CMP). Teste os estados de consentimento aceito, rejeitado e sem escolha, caso existam no seu site, e confirme que os sinais do IAB TCF ou os dados enviados pela CMP alteram o comportamento dos bidders conforme sua política exige.
Acompanhe o console, mas não tente resolver cada aviso antes de comprovar que a monetização funciona. O que impede a entrada em produção é o wrapper não carregar, os bidders não serem chamados, o targeting estar vazio, as requisições ao GAM dispararem cedo demais, o criativo não renderizar e o comportamento de consentimento contrariar seus requisitos.
Faça um teste limitado em produção com um pequeno conjunto de posicionamentos antes de expandir para outras propriedades. Monitore latência, perdas por timeout, padrões de no-bid e veiculação no GAM nesses posicionamentos, em vez de consolidar os resultados em uma média do site inteiro que esconde o slot com problema.

Falhas silenciosas custam mais que as explícitas: os anúncios continuam aparecendo, e o problema passa despercebido. Uma campanha direta, um item de linha do AdX ou um anúncio da casa pode preencher o slot sem que a demanda do Prebid entre na disputa.

Siga uma impressão pelo fluxo inteiro, da requisição do adapter à resposta do lance, da gravação do targeting à elegibilidade do item de linha no GAM, até a seleção e a renderização do criativo. Receita registrada em algum lugar não comprova que o primeiro leilão em produção funciona.

O checklist de lançamento que mantém a receita estável na primeira semana

Use a primeira semana após o lançamento para medir a estabilidade. A expansão vem depois. Analise os resultados por posicionamento, categoria de dispositivo, estado de consentimento, template e mapeamento no GAM. Procure consistência nos leilões: os adapters precisam disparar onde deveriam, e os timeouts precisam ter explicação. Confira também se os valores de hb_pb correspondem às faixas de preço configuradas no GAM. O mesmo slot não deve alternar entre veiculação correta pelo Prebid e ausência de targeting.

Confira o bundle publicado antes de ampliar o tráfego: versão do Prebid.js, lista de adapters, módulos, timeout, tipos de mídia, tratamento de moedas, comportamento do módulo de consentimento e configuração de analytics, se utilizada.
Fixe o mapeamento inicial no GAM: nomes dos blocos de anúncios, chaves-valor, faixas de preço, intervalos dos itens de linha, criativos, prioridades e quaisquer proteções que possam bloquear a demanda de header bidding.
Acompanhe a densidade de lances por posicionamento e dispositivo. Um banner no topo da página inicial, um bloco no meio do artigo em dispositivos móveis e um slot de rolagem infinita não devem ser avaliados pela mesma métrica agregada.
Monitore o comportamento de timeout separadamente do comportamento de no-bid. Um bidder que nunca responde dentro da janela do leilão exige uma correção diferente da de um bidder que responde rápido, mas não atribui valor ao inventário.
Analise os padrões de no-bid por adapter. Se um parceiro retorna no-bid em todos os posicionamentos, confira os parâmetros e a configuração da conta antes de concluir que a demanda é fraca.
Compare a veiculação no GAM com o targeting do Prebid. Se há lances vencedores, mas os itens de linha correspondentes raramente veiculam, investigue a elegibilidade no ad server antes de alterar o wrapper.
Monitore com mais rigor o inventário com refresh. O refresh pode inflar o volume de requisições e, ao mesmo tempo, adicionar latência e leilões de baixo valor se todos os parceiros forem chamados a cada atualização.
Trate atualizações de adapters como releases. Após qualquer atualização do build do Prebid.js, alteração nos parâmetros de um parceiro de demanda ou adição de módulo, repita o mesmo teste de posicionamento já validado, desde a chamada ao bidder até a veiculação no GAM.
Programe uma revisão de limpeza após acumular tráfego real. Remova bidders que sobrecarregam a página sem gerar vitórias aproveitáveis, restrinja os bidders aos posicionamentos em que são competitivos e documente cada corte para que as equipes comerciais não voltem a adicionar peso morto depois.
Avalie se o primeiro build ficou amplo demais, lento demais ou frágil demais antes de adicionar recursos. Amplo demais significa excesso de bidders fracos; lento demais significa problemas de timeout e sobrecarga no navegador; frágil demais significa que o GAM ou a sequência de execução falha durante o funcionamento normal da página.

Você pode entrar em produção quando cumprir estes critérios: o posicionamento de teste veicula um criativo do Prebid pelo GAM; os valores de hb_pb e hb_bidder exibidos no navegador correspondem a itens de linha elegíveis no GAM; o criativo renderiza em todos os tamanhos permitidos; a requisição de anúncio acontece após setTargetingForGPTAsync.

Confira também se nenhum conflito de teste com prioridade superior mascara o resultado e se os parâmetros dos bidders são reais. O comportamento de timeout precisa ser conhecido nos templates de desktop e dispositivos móveis. Para o rollback, deve bastar desativar o wrapper ou remover os itens de linha de teste.

Perguntas frequentes

Você precisa do Google Ad Manager para usar o Prebid.js?

Não. Mas o GAM é a combinação mais comum entre publishers que usam o Prebid.js em escala. Confira se as chaves de targeting, as prioridades dos itens de linha, a configuração dos criativos e as faixas de preço correspondem ao que o Prebid retorna por meio do GPT. Com outro ad server, o leilão ainda pode funcionar. O que muda é a lógica de repasse e o checklist de configuração das campanhas.

Devo começar com Prebid.js no client-side ou com Prebid Server?

Comece pelo client-side se a prioridade é fazer uma primeira implantação controlada com rapidez, depurar pelo navegador e enxergar diretamente as chamadas dos adapters. É o caminho mais simples para acompanhar o que acontece. Passe para o Prebid Server ou para uma configuração híbrida quando houver um gargalo comprovado de latência no navegador, peso da página ou desempenho em dispositivos móveis. Na primeira implementação de um publisher de médio a grande porte, o client-side costuma ser o ponto de partida mais seguro.

Quantos bidders devem entrar na primeira build?

Inclua apenas bidders cuja participação faça sentido no inventário de lançamento. Para a primeira build, trabalhe com um ou dois parceiros já validados em um único posicionamento de teste. Depois, expanda de maneira controlada por bloco de anúncios ou propriedade.

Para manter um bidder em produção, confira se os parâmetros são válidos e se ele responde dentro do timeout com frequência suficiente para influenciar os leilões. Os lances também precisam corresponder às faixas de preço do GAM, e sua equipe precisa conseguir lidar com as discrepâncias desse parceiro.

Qual ferramenta usar primeiro quando os lances não aparecem?

Use o Professor Prebid na primeira verificação: ele reúne o leilão, as chamadas dos adapters e a segmentação em um só lugar. Depois, passe ao GAM. Confira hb_pb e hb_bidder, os itens de linha, os tamanhos dos criativos e as faixas de preço. Tudo precisa corresponder aos valores que o Prebid envia por meio do GPT. Os lances aparecem no navegador, mas o GAM veicula outra coisa? A falha costuma estar no repasse.

O que costuma dar errado no primeiro leilão em produção?

Para investigar um leilão com falha em produção, siga esta ordem. Primeiro, veja se a build personalizada do Prebid contém o adapter e se os parâmetros do bidder estão presentes. Depois, confira se o consentimento ou a lógica da página bloqueiam a requisição e se os lances retornam antes do timeout.

Verifique então se setTargetingForGPTAsync grava hb_pb e hb_bidder no slot correto do GPT e se o GAM tem os pares de chave-valor e os itens de linha correspondentes. Por último, examine a compatibilidade dos criativos e os conflitos de prioridade.

Só atribua o problema à demanda depois de descartar falhas no fluxo entre o leilão e o GAM.

Como fizemos a pesquisa

Fontes consultadas para este artigo:

Ataíde Penteado