# 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…

- Página: <https://www.datafirefly.com/pt/documentation/dffbadspixel/>
- Idioma: pt
- Atualizado em: 2026-09-14
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/dffbadspixel/index.md), [en](https://www.datafirefly.com/en/documentation/dffbadspixel-2/index.md), [es](https://www.datafirefly.com/es/documentation/dffbadspixel-3/index.md), [de](https://www.datafirefly.com/de/documentation/dffbadspixel-4/index.md), [it](https://www.datafirefly.com/it/documentation/dffbadspixel-5/index.md), [pl](https://www.datafirefly.com/pl/documentation/dffbadspixel/index.md), [nl](https://www.datafirefly.com/nl/documentation/dffbadspixel/index.md)
- Índice: <https://www.datafirefly.com/pt/documentation/llms.txt>

## 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.

Compatível com PrestaShop 8.0 a 9.x, PHP 7.4 a 8.3, multiloja e multilingue. O `cURL` é necessário para a API de Conversões. Nenhuma dependência Composer em produção.

Para uma loja portuguesa, a combinação de feed a declarar no Meta é tipicamente Portugal / Português / EUR; para as ilhas, o cálculo dos portes reais (ver abaixo) só reflete os Açores e a Madeira se estes existirem como zonas de transportadora distintas na sua configuração PrestaShop.

## 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.

Comece sem mapeamento de categorias: o Meta aceita o feed sem `google_product_category`. Acrescente-o progressivamente nas suas categorias principais para melhorar a difusão.

## 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.

Os eventos são deduplicados com o pixel do navegador graças a um `event_id` partilhado (por exemplo `order-1234` para uma compra). Os dados do utilizador são transformados em hash SHA-256 antes do envio.

### Estados que acionam o Purchase

Desde a versão 2.1.0, o evento Purchase é emitido quando a encomenda **passa para um estado acionador**, e não na sua criação. Assinale os estados pretendidos no separador API de Conversões: na instalação, os estados que o PrestaShop marca como pagos são pré-selecionados. Se nenhum estado for assinalado, o módulo recorre a esses mesmos estados pagos.

Este funcionamento é indispensável com pagamentos assíncronos (transferência, MB Way, SEPA, Klarna): a encomenda é criada a aguardar pagamento e o Purchase só é enviado depois de o pagamento ser confirmado. Sendo o envio totalmente do lado do servidor, não depende da página de confirmação, mesmo que o cliente nunca regresse à loja. Uma proteção por `event_id` evita duplicados se a encomenda mudar de estado várias vezes.

### Dados de utilizador enviados

Quando disponíveis, o módulo transmite: `em` (email), `ph` (telefone), `fn`, `ln`, `ct`, `zp`, `external_id`, `fbp`, `fbc`, `client_ip_address` e `client_user_agent`. Todos os dados pessoais são codificados com SHA-256 antes do envio. O `external_id` usa o ID do cliente (ou o identificador de visitante convidado). O `fbc` é lido do cookie `_fbc` e, se ainda não existir, reconstruído a partir do parâmetro de URL `fbclid`.

## Consentimento RGPD e CMP

O separador **Consentimento** aplica o consentimento de marketing ao pixel _e_ aos envios do servidor. Enquanto não for concedido, o pixel permanece em modo `revoke` (Consent Mode da Meta) e nenhum evento é colocado em fila nem enviado pela API de Conversões.

A deteção é em cascata:

1. **IAB TCF v2.2**: leitura de `__tcfapi` (finalidade 1 e vendor Meta 89).
2. **Cookie do seu CMP**: nome e valor esperado configuráveis (Axeptio, Cookiebot, Didomi, módulos RGPD para PrestaShop…).
3. **API JavaScript**: chame `window.dffbConsentGrant()` na aceitação e `window.dffbConsentRevoke()` na recusa a partir de um banner próprio.

A decisão lida no navegador é refletida num cookie `dffb_consent`, permitindo que a API de Conversões aplique exatamente a mesma escolha do lado do servidor. É também emitido um evento `dffb:consent` em `document`.

## 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.

Depois de uma rotação de token, lembre-se de atualizar as suas fontes de feed no Business Manager e depois de invalidar o token antigo a partir do separador Segurança para fechar a janela de transição.

## 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.