Facebook Events

Visão Geral

O módulo de Facebook Events permite o envio de eventos de conversão diretamente do servidor para a Graph API do Facebook.

Esta integração, amplamente conhecida como Conversions API (CAPI), complementa o rastreamento tradicional via Pixel do navegador, garantindo que as ações cruciais dos usuários sejam registradas de forma resiliente.

A utilização da CAPI é fundamental para contornar limitações modernas de privacidade, como bloqueadores de anúncios e restrições de cookies de terceiros em navegadores.

Ao processar os eventos no lado do servidor, a plataforma Uappi assegura uma maior precisão nos dados de marketing, permitindo uma otimização mais assertiva das campanhas publicitárias e uma mensuração fiel do funil de vendas.

Isso possibilita que os eventos sejam disparados de forma assíncrona a partir de interações diretas no front-end da loja, enviando os dados necessários para que o servidor realize a comunicação segura com os endpoints do Facebook.

Entidades Envolvidas

* App: Representa o aplicativo interno FACEBOOK_GRAPH_API que gerencia as chaves de acesso e tokens.

* Customer: O cliente da loja cujas ações (vistas de página, adições ao carrinho, compras) estão sendo rastreadas.

* OrderGroup: Entidade utilizada especificamente no evento de compra para consolidar os dados da transação.

Notas e Considerações

A execução dos eventos é centralizada através do core da plataforma, utilizando o método executeApp.

Este fluxo garante que a lógica de comunicação, tratamento de erros de API externa e renovação de tokens de acesso fiquem isoladas no microserviço de aplicativos, proporcionando uma arquitetura limpa e de fácil manutenção.

É imprescindível que o aplicativo do Facebook esteja devidamente instalado e ativo no painel administrativo da loja para que os disparos ocorram com sucesso.

Caso contrário, a plataforma retornará erros específicos de disponibilidade do serviço.

Os identificadores de rastreamento do Pixel do Facebook (_fbp e _fbc), além do IP e User-Agent do visitante, são capturados automaticamente pelo servidor a partir dos cookies e cabeçalhos da própria requisição.

Visualização de Página

Descrição

O endpoint de Visualização de Página (PageView) é responsável por registrar o acesso básico de um usuário a qualquer página da loja na Facebook Graph API.

Este é o evento fundamental para o rastreamento de tráfego, servindo como base para a criação de públicos e análise de comportamento.

Através deste disparo, o Facebook consegue identificar a jornada do cliente desde o primeiro contato, permitindo que lojistas compreendam melhor quais páginas institucionais, de categorias ou marcas estão atraindo mais interesse.

É a unidade de medida primária para qualquer estratégia de marketing digital baseada em dados.

Isso assegura que a comunicação entre o front-end e o servidor ocorra de forma protegida, mantendo a consistência dos dados enviados para a plataforma do Facebook.

Parâmetros

Headers Obrigatórios

Parâmetros do Corpo

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/third-party/facebook/event/page-view \
3  --header "Content-Type: application/json" \
4  --data '{
5    "customerId": 12345
6  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1"Sucesso"

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Visualização de Conteúdo

Descrição

O registro de Visualização de Conteúdo (ViewContent) é essencial para informar ao Facebook quais produtos específicos estão sendo navegados pelos usuários.

Este evento deve ser disparado sempre que um cliente acessa a página de detalhes de um produto, permitindo uma segmentação granulada do interesse de compra.

Ao utilizar este endpoint, a plataforma Uappi envia os identificadores necessários para que o Facebook possa associar a navegação do usuário ao catálogo de produtos da loja.

Isso é vital para a execução de campanhas de Retargeting Dinâmico, onde anúncios personalizados são exibidos para o usuário com base nos itens que ele visualizou anteriormente.

Essa camada de segurança garante que apenas requisições autorizadas disparem eventos para a Conversions API, protegendo a integridade dos dados de marketing da loja.

Parâmetros

Headers Obrigatórios

Parâmetros do Corpo

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/third-party/facebook/event/view-content \
3  --header "Content-Type: application/json" \
4  --data '{
5    "customerId": 12345,
6    "productId": 54321
7  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1"Sucesso"

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Adicionar ao Carrinho (Facebook)

Descrição

O evento de Adicionar ao Carrinho (AddToCart) é um dos marcos mais importantes do funil de conversão na Facebook Graph API.

Ele sinaliza que um produto despertou um interesse de compra real, permitindo que o Facebook otimize a entrega de anúncios para usuários com perfis semelhantes e propensão de compra elevada.

Ao registrar este evento através da Conversions API, a Uappi envia detalhes cruciais como o SKU do produto, a quantidade adicionada e o valor unitário.

Esses dados são fundamentais para estratégias de abandono de carrinho, possibilitando que a loja re-impacte o cliente com comuni

O disparo deve ser realizado no momento da ação do usuário (clique no botão de comprar), garantindo que a intenção de compra seja capturada em tempo real.

Parâmetros

Headers Obrigatórios

Parâmetros do Corpo

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/third-party/facebook/event/add-to-cart \
3  --header "Content-Type: application/json" \
4  --data '{
5    "customerId": 12345,
6    "sku": "PROD-ABC-123",
7    "quantity": 2,
8    "price": 49.90
9  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1"Sucesso"

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Iniciar Checkout

Descrição

Este endpoint é utilizado para registrar o evento de início de checkout na Graph API do Facebook.

Ele deve ser invocado no exato momento em que um usuário avança do carrinho para a etapa de finalização de compra, sinalizando uma intenção clara de conversão.

O registro deste evento é processado de forma assíncrona pelo aplicativo de integração, que utiliza o identificador do cliente para recuperar dados complementares e enriquecer o evento.

Esse processo aumenta significativamente a taxa de correspondência (Match Rate) do Facebook, tornando o rastreamento mais preciso e eficiente.

Parâmetros

Headers Obrigatórios

Parâmetros do Corpo

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/third-party/facebook/event/initiate-checkout \
3  --header "Content-Type: application/json" \
4  --data '{
5    "customerId": 12345
6  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1"Sucesso"

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Adicionar Informações de Pagamento

Descrição

O evento de Adicionar Informações de Pagamento (AddPaymentInfo) registra o momento em que o usuário preenche ou seleciona uma forma de pagamento durante o checkout.

Este é um passo crítico do funil, indicando uma probabilidade extremamente alta de conclusão de compra.

Ao informar o Facebook sobre esta ação, a plataforma permite que as campanhas de marketing identifiquem usuários que chegaram à beira da conversão, mas que por algum motivo não finalizaram o pedido.

Isso possibilita a criação de públicos de alta intenção, otimizando a entrega de anúncios de reforço para garantir o fechamento da venda.

A correta implementação deste evento é vital para uma análise profunda do funil de checkout e para a melhoria das taxas de conversão da loja.

Parâmetros

Headers Obrigatórios

Parâmetros do Corpo

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/third-party/facebook/event/add-payment-info \
3  --header "Content-Type: application/json" \
4  --data '{
5    "customerId": 12345,
6    "totalValue": 150.00
7  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1"Sucesso"

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Compra (Facebook)

Descrição

O endpoint de Compra (Purchase) representa o evento de conversão final e o mais valioso na integração com a Facebook Graph API.

Ele notifica o Facebook sobre o fechamento de uma venda, permitindo o cálculo preciso do Retorno sobre Investimento Publicitário (ROAS) e a otimização máxima das campanhas.

Diferente de outros eventos, este exige apenas o identificador do grupo de pedidos (orderGroupId).

A partir deste ID, o servidor da Uappi processa internamente toda a complexidade da transação, coletando dados de produtos, valores, impostos e informações do cliente para compor um evento rico e detalhado para a Conversions API.

O disparo deve ocorrer na página de confirmação de pedido ou logo após o processamento bem-sucedido do pagamento, garantindo que cada conversão seja atribuída corretamente às fontes de tráfego.

Parâmetros

Headers Obrigatórios

Parâmetros do Corpo

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/third-party/facebook/event/purchase \
3  --header "Content-Type: application/json" \
4  --data '{
5    "orderGroupId": 98765
6  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1"Sucesso"

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Busca (Facebook)

Descrição

O evento de Busca (Search) informa ao Facebook que um usuário realizou uma pesquisa dentro da loja, sinalizando um interesse ativo por determinados produtos ou termos.

Ao registrar este evento através da Conversions API, a Uappi envia o termo pesquisado e, opcionalmente, os identificadores dos produtos retornados na busca, permitindo que o Facebook associe essa intenção de compra ao catálogo da loja.

Esse dado é utilizado para refinar a segmentação de campanhas e alimentar estratégias de remarketing baseadas em interesse de busca.

O disparo deve ser realizado no momento em que o usuário submete uma pesquisa (ex: barra de busca do site).

Parâmetros

Headers Obrigatórios

Parâmetros do Corpo

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/third-party/facebook/event/search \
3  --header "Content-Type: application/json" \
4  --data '{
5    "customerId": 12345,
6    "searchTerm": "tenis nike",
7    "contentIds": ["SKU-001", "SKU-002"]
8  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1"Sucesso"

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.