MarketingArtigo
Pixel da Meta e API de Conversões: como instalar na loja virtual e conferir se os eventos chegam
Em resumo
O Pixel da Meta e a API de Conversões avisam a Meta, dona do Facebook e do Instagram, quando um visitante da loja virtual vê um produto ou conclui uma compra. O Pixel roda no navegador; a API envia o aviso pelo servidor, o computador que processa os pedidos da loja. O ConnectWeek mostra como instalar cada um, como evitar a venda contada duas vezes e como conferir, no painel da Meta, se os avisos chegaram.
O Pixel da Meta e a API de Conversões são as duas formas de a loja virtual avisar a Meta, dona do Facebook e do Instagram, de que um visitante do site viu um produto, pôs um item no carrinho ou concluiu uma compra. O Pixel é um código que roda no navegador do visitante. A API de Conversões envia o mesmo aviso a partir de um servidor, o computador ligado à internet que processa os pedidos da loja. A Meta chama cada aviso de evento e usa os eventos para medir o resultado dos anúncios e decidir a quem mostrá-los. Este artigo segue a documentação da Meta para desenvolvedores. Mostra como o Pixel e a API são instalados e como evitar que a mesma venda seja contada duas vezes. Mostra também como conferir se os dados estão chegando ao Gerenciador de Eventos, o painel da Meta que lista os eventos recebidos. As páginas citadas foram consultadas pelo ConnectWeek em 13 de outubro de 2026.
O que o Pixel faz e o que a API de Conversões acrescenta
A página “Começar a usar o Pixel da Meta” define o Pixel como um código em JavaScript, linguagem de programação que funciona dentro do navegador. Esse código carrega no site um pequeno conjunto de funções, a biblioteca do Pixel, e usa cookies do Facebook, pequenos arquivos gravados no navegador, para ligar o visitante do site à conta que ele tem na rede social. Por padrão, registra os endereços e os domínios visitados e o dispositivo do visitante. Com as funções da biblioteca, a loja registra conversões, que são as ações que ela quer medir, como a compra. Também monta públicos personalizados, as listas de pessoas para quem anunciar, e configura os anúncios de catálogo Advantage+, montados com os produtos do catálogo da loja.
A visão geral da API de Conversões descreve a ferramenta como uma conexão entre os dados de marketing do anunciante e os sistemas da Meta. Os dados podem sair de um servidor, de um site, de uma plataforma, de um aplicativo ou de um sistema de gestão do relacionamento com clientes (CRM). Segundo a página, os eventos enviados pelo servidor ficam ligados à identificação de um conjunto de dados e são processados como os eventos do Pixel.
A Meta recomenda as duas ferramentas juntas, com os mesmos eventos enviados pelas duas. A página “Boas práticas da API de Conversões” chama esse arranjo de configuração de evento redundante. O motivo declarado é que a API permite enviar eventos do site que o Pixel pode perder por problema de conexão de rede ou por erro no carregamento da página.
Instalação do Pixel: onde o código entra e como saber se funcionou
Para instalar, a página de primeiros passos lista três requisitos: acesso ao código do site, o código de base do Pixel ou a identificação dele, e acesso ao Gerenciador de Anúncios. O código de base fica no Gerenciador de Eventos, dentro do Gerenciador de Anúncios.
A recomendação é colar o código de base entre as marcações de abertura e de fechamento do <head>, o cabeçalho do código da página, em todas as páginas em que a loja quer registrar ações. A documentação dá dois motivos. Nessa posição, é menor a chance de um navegador ou de um código de terceiros bloquear o Pixel. E o código roda mais cedo, o que aumenta a chance de registrar o visitante antes que ele saia.
O Pixel também funciona na maioria dos gerenciadores de tags, programas que reúnem em um só lugar os códigos de medição do site. A instalação por uma marcação de imagem é possível, mas a página não a recomenda. Entre os gerenciadores, o do Google, chamado Gerenciador de tags, é apresentado em Google Tag Manager na loja virtual: o que é e a primeira configuração.
A conferência descrita pela Meta tem três passos:
- Abrir no navegador uma página da loja que tenha o código. Isso dispara o evento
PageView, a visualização de página. - Entrar no Gerenciador de Eventos, localizar o Pixel e abrir os detalhes. Um
PageViewnovo indica que a instalação deu certo. Se a confirmação não aparecer, a orientação é aguardar alguns minutos e atualizar a página. - Se o evento continuar ausente, usar o Consultor de Dados de Anúncios da Meta, uma extensão do navegador Chrome que aponta erros do Pixel.
Os eventos que uma loja virtual registra
O código de base envia o PageView automaticamente. Os demais eventos dependem de um comando, o fbq('track'), que a loja ou a plataforma acrescenta nas páginas certas. A referência do Pixel lista os eventos-padrão. Os que descrevem o caminho de uma compra são estes:
| Evento | Quando acontece, segundo a referência |
|---|---|
ViewContent | Visita a uma página de interesse, como a página de um produto |
Search | Pesquisa feita no site |
AddToCart | Produto adicionado ao carrinho |
InitiateCheckout | Início da finalização da compra, ainda sem concluí-la |
AddPaymentInfo | Dados de pagamento adicionados durante a finalização |
Purchase | Compra feita ou fluxo de finalização concluído, com chegada à página de confirmação |
No evento Purchase, a referência marca como obrigatórios o valor e a moeda da compra. Na avaliação do ConnectWeek, é o valor que permite ao painel de anúncios calcular o retorno sobre o gasto, o ROAS. A leitura desse número e a diferença entre ROAS e lucro estão no artigo sobre tráfego pago para pequeno e-commerce.
API de Conversões: os caminhos de instalação
A documentação consultada descreve mais de um caminho, com esforço diferente em cada um. A visão geral da API informa que a loja que já tem um Pixel no site pode configurar a API de Conversões em um clique, pelo Gerenciador de Eventos, para os eventos do site, sem código e sem taxa de configuração.
O segundo caminho passa pela plataforma da loja. A página de boas práticas tem uma seção para plataformas de sites parceiras da Meta, que podem oferecer a API de Conversões aos anunciantes que são seus clientes. Para saber se a plataforma da loja oferece a API de Conversões e como ativá-la, a consulta é à ajuda de cada fornecedor.
O terceiro é a integração direta, feita por desenvolvedor: o servidor da loja envia os eventos para a Meta. A página “Começar a usar a API de Conversões” lista o que é preciso: a identificação do Pixel, uma conta no Meta Business Suite e um token de acesso, a chave que autoriza o envio. A Meta recomenda gerar o token no Gerenciador de Eventos, na aba de configurações do Pixel. O link para gerar o token só aparece para usuários com privilégio de desenvolvedor na empresa. A página pede que a loja use a mesma identificação de Pixel nos eventos do navegador e nos do servidor.
Desduplicação: a mesma venda não pode contar duas vezes
Com o Pixel e a API enviando o mesmo evento, a Meta recebe duas notificações da mesma compra. A página “Como gerenciar eventos duplicados de Pixel e da API de Conversões” diz que, nesse caso, o anunciante precisa configurar um método de desduplicação, termo da Meta para a eliminação dos eventos repetidos. Quem não envia o mesmo evento pelas duas vias não precisa dessa configuração.
O método que a página recomenda usa dois campos. O nome do evento tem de ser igual nos dois envios. E os dois precisam levar o mesmo identificador: o parâmetro eventID no Pixel e o event_id na API de Conversões. Quando a Meta encontra a mesma combinação de nome e identificador, enviada para o mesmo Pixel, em um intervalo de 48 horas, descarta os eventos que chegam depois do primeiro. O texto ressalva que a Meta usa várias estratégias nessa eliminação e que, quando o evento do servidor e o do navegador não têm conteúdo significativamente diferente, em geral fica com o que chegou primeiro.
Na avaliação do ConnectWeek, o número do pedido é um bom candidato a identificador do evento de compra. Ele é único e está disponível tanto na página de confirmação, onde o Pixel roda, quanto no servidor, de onde a API envia. Um exemplo hipotético: no pedido 10482, o Pixel envia Purchase com eventID igual a pedido-10482, e o servidor envia Purchase com event_id igual a pedido-10482. A Meta fica com um só.
A página descreve um segundo método, sem identificador de evento. Ele compara o evento do servidor com o do navegador pela combinação do nome do evento com o fbp, identificador do navegador gravado em cookie pelo Pixel, com o external_id, identificador que a própria loja atribui ao cliente, ou com os dois. O texto lista duas limitações. Em geral, esse método só elimina a repetição quando o evento do navegador chega antes do evento do servidor. E não elimina eventos repetidos vindos da mesma fonte.
Dados do cliente: o que acompanha o evento do servidor
A página de boas práticas traz três parâmetros como obrigatórios. O action_source, que informa onde a conversão aconteceu, vale para todos os eventos. O event_source_url, o endereço da página, e o client_user_agent, a identificação do navegador, valem para todos os eventos de site.
Além deles, a loja pode enviar informações do cliente para a Meta localizar a conta correspondente. A documentação cita como exemplos de informações de alta qualidade o endereço de e-mail, o endereço IP, que é o número que identifica a conexão do cliente, o nome e o telefone. Segundo o texto, só os eventos com correspondência servem para atribuir vendas aos anúncios e para a Meta ajustar a quem os anúncios são mostrados. Os eventos sem correspondência servem para medição básica.
As informações de contato, como e-mail, nome e telefone, não seguem do jeito que o cliente digitou. A página “Parâmetros de informações do cliente” informa que os sistemas da Meta foram feitos para aceitar as informações de contato apenas convertidas em hash, com as exceções que ela lista. Hash é um código embaralhado, gerado por uma fórmula a partir do dado original. O algoritmo indicado nos exemplos da página é o SHA256. Quem usa o SDK de Negócios da Meta, o pacote de programação da empresa, tem a conversão feita automaticamente. O endereço IP e a identificação do navegador são exceções: a página orienta a enviá-los sem conversão em hash.
A página de primeiros passos do Pixel avisa que, conforme o lugar em que a empresa atua, pode ser necessário cumprir o regulamento europeu de proteção de dados. Para a loja brasileira, o que a Lei Geral de Proteção de Dados (LGPD) e a Agência Nacional de Proteção de Dados (ANPD) pedem sobre cookies e dados de clientes em publicidade está em dois artigos do ConnectWeek: o do banner de cookies e o de remarketing sem cookie de terceiros. Para as tags do Google, a escolha feita no banner chega pelo modo de consentimento.
Quatro verificações no Gerenciador de Eventos
A página “Como verificar sua configuração” divide a conferência em quatro perguntas.
Os eventos chegaram? Depois do envio, eles podem ser vistos no Gerenciador de Eventos em até 20 minutos. Na visão geral do Pixel, o campo “Método de conexão” mostra por qual via cada evento chegou.
Chegaram a tempo? A Meta recomenda o menor intervalo possível entre o momento em que o evento acontece e o envio. A aba “Atualização do evento” mostra o atraso médio, em uma escala que vai de tempo real a semanal. A página “Como usar a API” fixa um limite: o horário informado no evento pode ser de até 7 dias antes do envio. Passado esse prazo, o envio inteiro retorna erro e nenhum dos eventos que estavam nele é processado.
A desduplicação funciona? A aba “Desduplicação de eventos” mostra a taxa de eventos desduplicados por fonte e a parcela de eventos que levam cada chave de desduplicação, isto é, cada identificador usado para comparar os eventos. O painel exibe um alerta quando a taxa está muito baixa. A aba mostra ainda a sobreposição, a parcela de eventos que chegaram com a mesma chave pelas duas fontes. Segundo a documentação, sobreposição baixa indica que a loja envia chaves que não são únicas, por uma das fontes ou pelas duas, ou envia eventos com a chave por apenas uma das fontes.
A Meta reconhece o cliente? A qualidade da correspondência de eventos é uma nota de 1 a 10 que mede a eficácia dos dados do cliente para ligar o evento do servidor a uma conta do Facebook. A documentação recomenda nota igual ou maior que 6, sempre que possível, e informa que um clique na nota abre as recomendações para melhorá-la. Pela página de boas práticas, a nota está disponível, atualmente, para os eventos da web, os que vêm do site.
Eventos de teste: um cuidado antes de usar
Para testar a conexão antes de pôr a integração em uso, a Meta oferece a ferramenta Eventos de Teste, no Gerenciador de Eventos. Segundo a página “Como usar a API”, a ferramenta gera um código, enviado no campo test_event_code, e os eventos marcados com ele aparecem na janela de teste. A página traz dois avisos. O campo serve apenas para teste e precisa sair da configuração de produção. E os eventos enviados com o código não são descartados: vão para o Gerenciador de Eventos e são usados no direcionamento e na medição dos anúncios.
Na avaliação do ConnectWeek, isso pede cuidado com o valor do pedido de teste. Uma compra fictícia de valor alto, enviada como Purchase, pode entrar na medição junto com as vendas reais.
Com as quatro verificações em ordem, o passo seguinte é decidir o que fazer com os dados. As campanhas que escolhem o público por conta própria, a partir dos eventos, estão no artigo sobre anúncios com IA no Advantage+ e na Performance Max.
Comece por aqui Novo no assunto? Leia primeiro o que é e-commerce, o texto-base desta cobertura.
Fonte: Meta for Developers
Perguntas frequentes
Qual é a diferença entre o Pixel da Meta e a API de Conversões?
O Pixel da Meta é um código JavaScript instalado nas páginas da loja, que roda no navegador do visitante e registra o que ele faz no site. A API de Conversões envia os mesmos registros, chamados de eventos, a partir de um servidor, de uma plataforma ou de um sistema de gestão do relacionamento com clientes. Segundo a documentação da Meta, os eventos enviados pelo servidor são processados como os eventos do Pixel.
É preciso usar o Pixel e a API de Conversões ao mesmo tempo?
Não é obrigatório, mas é o que a Meta recomenda. A página de boas práticas da API de Conversões orienta a enviar os mesmos eventos pelas duas ferramentas, arranjo que ela chama de configuração de evento redundante. O motivo declarado é que a API permite enviar eventos do site que o Pixel pode perder por problema de conexão de rede ou por erro no carregamento da página.
O que é desduplicação de eventos na Meta?
É a eliminação dos eventos repetidos quando o Pixel e a API de Conversões enviam a mesma ação, como uma compra. No método que a Meta recomenda, os dois envios levam o mesmo nome de evento e o mesmo identificador: eventID no Pixel e event_id na API. Quando a combinação se repete para o mesmo Pixel em um intervalo de 48 horas, a Meta descarta os eventos que chegam depois do primeiro.
O que é a qualidade da correspondência de eventos?
É uma nota de 1 a 10, exibida no Gerenciador de Eventos, que mede a eficácia dos dados do cliente enviados com o evento do servidor para ligá-lo a uma conta do Facebook. A página “Como verificar sua configuração”, da Meta, recomenda nota igual ou maior que 6, sempre que possível. Um clique na nota abre as recomendações para melhorá-la.
Como saber se o Pixel da Meta foi instalado corretamente?
A documentação da Meta orienta a abrir no navegador uma página da loja que tenha o código e depois conferir, no Gerenciador de Eventos, se apareceu um evento PageView novo nos detalhes do Pixel. Se a confirmação não aparecer, a orientação é aguardar alguns minutos e atualizar a página. Persistindo a falha, a Meta indica o Consultor de Dados de Anúncios, uma extensão do navegador Chrome.
