Facebook Dynamic Ads + Pixel PRO: guia completo

Apresentação

O Facebook Dynamic Ads + Pixel PRO liga o seu catálogo PrestaShop ao Facebook e ao Instagram. O módulo exporta um feed de produtos de alta qualidade (XML no formato Facebook RSS ou CSV), instala o pixel do Facebook na sua loja e ativa a API de Conversões para um acompanhamento fiável do lado do servidor. Gera um feed distinto por combinação País / Idioma / Moeda, oferece um controlo fino dos dados exportados (exclusões, etiquetas personalizadas, mapeamento das categorias Google) e foi concebido para catálogos volumosos até 200 000 produtos.

Instalação

1. No seu back-office, abra Módulos → Gestor de módulos → Instalar um módulo.
2. Carregue o ficheiro dffbadspixel.zip.
3. O módulo instala-se e cria automaticamente as suas tabelas (dffbadspixel_exclusion, dffbadspixel_label, dffbadspixel_capi_queue) e o separador de administração Facebook Dynamic Ads + Pixel.

É gerado um token de segurança único na instalação. Protege os URLs do feed e do CRON, e é apresentado no separador URLs e CRON do módulo.

Separador Feed de produtos

É o coração do módulo. Escolhe aí o formato e o modo de geração, a seleção dos produtos e o detalhe dos dados exportados.

Formato e geração

• Formato: XML (Facebook RSS + namespace Google), CSV, ou ambos.
• Modo de geração: Na hora (streaming a cada chamada do URL) ou CRON (ficheiros em cache, recomendado para os grandes catálogos).
• Compressão gzip, tamanho do lote (chunking) e apenas países ativados para otimizar o desempenho.

Seleção e granularidade

• Exportar por categoria ou por marca, com seleção fina (um campo de filtro facilita a pesquisa na lista).
• Granularidade por produto ou por declinação.
• Construção do ID do feed: ID do back-office (com opção idioma e/ou declinação), referência ou EAN.
• Tipo de descrição (curta/longa), disponibilidade (segundo o stock ou sempre em stock), cores, tamanhos, imagens adicionais ou apenas imagem de capa.

Portes, tracking e qualidade

• Portes reais calculados através das suas transportadoras PrestaShop (zona, intervalos de peso/preço), transportadora de referência ou a mais barata, com portes grátis parametrizáveis.
• Parâmetros UTM e integração GA4.
• Limites de qualidade: comprimentos máximos de título e de descrição usados pelo validador (separador Diagnóstico).

Exclusões gerais

Diretamente sob o separador Feed: excluir os produtos esgotados, sem EAN/MPN, ou abaixo de um preço mínimo.

Exclusões avançadas

No separador Exclusões, adicione regras específicas para afastar certos produtos do feed. Cada regra assenta num tipo e num valor:

• Palavra / expressão: exclui se o nome ou a descrição contiver o termo.
• Produto, Declinação, Fornecedor: por ID.
• Valor de característica ou Atributo: por ID.

Etiquetas personalizadas e tags de vestuário

As etiquetas personalizadas (custom_label_0 a custom_label_4) enriquecem a segmentação das suas campanhas: nome de categoria, valor de uma característica, intervalo de preço, ou etiquetas « novo » / « mais vendido ».

O separador Tags de vestuário acrescenta os campos Meta dedicados ao pronto-a-vestir: age_group, gender, bem como pattern (padrão) e material (material) mapeados em características de produto.

Mapeamento das categorias e moedas

No separador Mapeamento e moedas, associe as suas categorias PrestaShop às categorias Google/Facebook:

• Importação CSV no formato id_category;google_category (separador ; ou ,, cabeçalho opcional).
• Importação a partir de outro módulo DataFirefly instalado (versão standard, Google Merchant Center, GMC Pro ou TikTok Ads).
• Sugestão automática por palavras-chave: preenche as correspondências vazias a partir do nome da categoria.
• Edição manual linha a linha, com filtro de pesquisa.

A tabela Moeda / País define a moeda usada para cada país na geração dos feeds multipaís. Sem associação, é usada a moeda por defeito da loja.

Pixel do Facebook

No separador Pixel, ative o pixel e preencha o seu ID de pixel. O módulo injeta o código base (PageView) e os eventos contextuais: ViewContent, ViewCategory, Search, InitiateCheckout, AddToCart e AddToWishlist.

• Correspondência avançada (advanced matching): envia informações adicionais do cliente, em hash SHA-256, para melhorar as suas audiências.
• Seletores HTML personalizáveis para os botões « lista de desejos » e « encomendar », úteis se o seu tema tiver modificado a marcação por defeito.
• Montante Purchase configurável: com ou sem imposto, com ou sem portes e/ou embalagem.

API de Conversões (assíncrona)

A API de Conversões envia os eventos diretamente a partir do seu servidor e recupera as conversões que o pixel sozinho não deteta (bloqueadores, cookies). No separador API de Conversões:

1. Ative a API de Conversões e cole o token de acesso gerado no seu Business Manager Meta.
2. Deixe o modo assíncrono ativado (recomendado): os eventos são colocados em fila e depois enviados por lotes através do CRON, sem abrandar a loja.
3. Ajuste o tamanho do lote e o número de tentativas máx. (retry) se necessário. Um código de evento de teste permite validar a integração no Business Manager.

URLs do feed e tarefa CRON

O separador URLs e CRON mostra o URL base do feed, o URL do CRON e a lista dos URLs por combinação País / Idioma / Moeda.

URL do feed

https://a-sua-loja.pt/index.php?fc=module&module=dffbadspixel&controller=feed&token=O_SEU_TOKEN&id_lang=1&id_currency=1&id_country=15&format=xml

Os parâmetros id_lang, id_currency, id_country e format (xml ou csv) selecionam o feed a servir. É este URL que declara como fonte do feed no catálogo Meta.

Tarefa CRON

Em modo CRON, agende a chamada do endpoint para (re)gerar os ficheiros em cache e esvaziar a fila da API de Conversões:

*/30 * * * * curl -s "https://a-sua-loja.pt/index.php?fc=module&module=dffbadspixel&controller=cron&token=O_SEU_TOKEN" > /dev/null

O parâmetro opcional job visa uma tarefa precisa: feeds (geração dos feeds), capi (envio da fila da API de Conversões) ou all (por defeito). A resposta é um resumo em texto.

Diagnóstico: pré-visualização e validação

O separador Diagnóstico reúne duas ferramentas:

• Fila da API de Conversões: número de eventos pendentes, falhados e enviados.
• Pré-visualização e validação do feed: gera uma amostra XML e um relatório de qualidade que assinala as linhas problemáticas: imagem em falta, GTIN inválido (verificado por dígito de controlo), título ou descrição demasiado longos, identificador de produto insuficiente.

Segurança

No separador Segurança:

• Lista de IPs autorizados: restringe o acesso ao feed e ao CRON a certos endereços ou intervalos CIDR (por exemplo os servidores Meta). Vazio = nenhuma restrição.
• Rotação do token: regenera o token dos URLs. O antigo continua tolerado até à invalidação, o tempo de atualizar os seus feeds no Meta.

Resolução de problemas

O feed devolve « Forbidden »

O token está ausente, incorreto, ou o IP chamador não está na lista autorizada. Verifique o token no separador URLs e CRON e esvazie a lista de IPs autorizados durante o teste.

O feed está vazio ou incompleto

Verifique a seleção de categorias/marcas (vazio = todo o catálogo), as regras de exclusão e o stock se a exclusão « esgotados » estiver ativa. Em modo CRON, lance primeiro a tarefa job=feeds para gerar a cache.

Os eventos da API de Conversões não chegam ao Meta

Certifique-se de que o cURL está disponível, que o token de acesso é válido, e execute a tarefa job=capi. Acompanhe a fila no separador Diagnóstico; os erros são registados em Parâmetros avançados → Registos com o prefixo [dffbadspixel].

O pixel não dispara num botão

Se o seu tema modificou a marcação, ajuste os seletores HTML « lista de desejos » e « encomendar » no separador Pixel.

Boas práticas

• Use o modo CRON + gzip para os catálogos volumosos: a geração na hora continua possível mas é mais custosa a cada chamada.
• Ative pixel e API de Conversões em conjunto: a deduplicação por event_id evita a dupla contagem melhorando ao mesmo tempo a cobertura.
• Preencha o mapeamento das categorias Google e os GTIN para maximizar a elegibilidade dos seus produtos para os posicionamentos Advantage+ e Shopping.