Implementação de ponta a ponta da API de Conversões

A API de Conversões oferece suporte aos esforços dos anunciantes para fornecer aos consumidores transparência e controle de dados apropriados, ao mesmo tempo que os ajuda a continuar proporcionando experiências pessoais. Com a API, você pode compartilhar dados diretamente do seu servidor em vez de usar um navegador.

Benefícios da integração

• Visibilidade de funil profundo: a API de Conversões permite que você compartilhe uma matriz de dados mais ampla em comparação com o pixel da Meta. Com a API, você pode tomar decisões levando em consideração mais informações, como dados de CRM, eventos de funil inferior (incluindo cadastros qualificados) e caminhos de conversão de vários sites em um site e uma localização física.

• Controle de dados: quando usada por meio de uma implementação somente de servidor (por exemplo, sem o pixel da Meta), a API de Conversões oferece controle adicional sobre quais dados você compartilha. É possível optar por acrescentar informações aos seus eventos, fornecendo dados como margens de produtos ou informações de histórico (como pontuações de valor do cliente).

• Confiabilidade e resiliência do sinal: o compartilhamento de dados por meio da API de Conversões pode ser mais confiável do que métodos baseados apenas em navegador, como o pixel da Meta. A API foi desenvolvida para ser menos suscetível a problemas como travamento do navegador ou falhas de conectividade. As novas restrições de transmissão de dados do setor podem limitar a eficácia dos cookies e do rastreamento de pixels. Por isso, a API de Conversões ajuda você a ter controle sobre o compartilhamento de sinais que podem não ser mais capturados pelo pixel.

Visão geral

A integração da API de Conversões tem dois estágios principais:

• Preparação: selecione o tipo de integração mais adequado para você, defina os eventos a serem enviados e analise as opções de otimização disponíveis.

• Execução: saiba como implementar a API. Para esse estágio, também é possível usar uma integração de parceiros.

Confira a seguir o processo de integração completo:

Usuários do pixel existentes

Se você já usa o pixel da Meta, a integração da API de Conversões deve ser criada como uma extensão da integração de pixel, em vez de uma conexão totalmente diferente.

Consentimento geral

Se você tiver uma lógica para controle do consentimento em relação ao compartilhamento de dados de pixel, use-a também na API de Conversões.

Alternativas

• Caso você queira otimizar os anúncios para eventos do app, use a API de Eventos do App.

Preparação

Escolher o tipo de integração

Para começar, selecione a opção de integração a ser implementada:

Definir eventos para enviar

Depois de escolher a abordagem de integração, é possível definir quais eventos serão enviados. Os sinais serão mais úteis se tiverem correspondência com números de identificação do usuário da Meta. Por isso, é importante refletir sobre os parâmetros a serem enviados com um evento e a frequência de envio.

Opções de evento

Envie os eventos que são mais relevantes para sua empresa. Veja uma lista completa de eventos do tipo padrão e personalizado que são aceitos pela Meta.

Parâmetros dos eventos

É possível enviar diversos parâmetros em cada evento. Consulte os Parâmetros usados pela API de Conversões para saber mais sobre esses campos.

Diversos tipos de ID podem ser adicionados aos eventos, incluindo event_id, external_id e order_id. Veja a diferença entre esses parâmetros:

Nível de atualidade dos dados

Recomendamos que você envie eventos em tempo real ou em lotes com base em uma linha do tempo específica por meio da API de Conversões. Enviar os eventos em tempo real ou na janela de uma hora ajuda a garantir que eles possam ser usados para atribuição e otimizados para veiculação de anúncio.

Se eles forem enviados mais de duas horas após a ocorrência, isso pode reduzir o desempenho de anúncios otimizados para os eventos em questão. Os eventos enviados com um atraso de 24 horas ou mais podem ter problemas significativos na atribuição e na otimização da veiculação de anúncio.

Se você estiver usando janelas de conversão longas, envie o evento o mais próximo possível do tempo real de conclusão da conversão.

Passe para a próxima etapa depois de definir o seguinte:

• Uma lista de eventos para enviar.
• Os campos específicos que você quer enviar em cada evento.
• A frequência de envio dos eventos.

Tipos de otimização disponíveis

A API de Conversões oferece os seguintes tipos de otimização:

Execução

Há duas maneiras de implementar a integração:

• Integração direta: você, como anunciante, implementa diretamente a API de Conversões.
• Integração como plataforma: você, como parceiro de marketing, oferece a API de Conversões como um serviço para os seus clientes.

Integração direta

Etapa 1: configurar requisitos

Antes de usar a API de Conversões, configure os seguintes ativos:

Quando os ativos estiverem prontos, inicie a etapa implementar a API. Salve os IDs dos ativos, pois eles serão usados nas chamadas de API.

Etapa 2: implementar a API

Depois de concluir os requisitos, inicie o processo de implementação. Consulte a documentação para desenvolvedores ao criar na API de Conversões.

Chamadas de teste (opcional)

Se essa for a primeira vez que você usa a API, comece com uma chamada de teste. Para fazer isso, você precisa de uma carga e um método para fazer chamadas de API. Depois que a chamada for concluída, visite o Gerenciador de Eventos para verificar se a chamada funcionou conforme o esperado.

{
  "data": [
   {
    "event_name": "Purchase",
    "event_time": 1601673450,
    "user_data": {
      "em": "7b17fb0bd173f625b58636fb796407c22b3d16fc78302d79f0fd30c2fc2fc068",
      "ph": null
     },
    "custom_data": {
      "currency": "USD",
      "value": "142.52"
    }
   }
  ]
}

{
  "events_received": 1,
  "messages": [],
  "fbtrace_id": <FB-TRACE-ID>
}

Quando tiver concluído sua primeira chamada, verifique os eventos em Gerenciador de Eventos > Seu pixel > Visão geral.

Depois de verificar os eventos de teste no Gerenciador de Eventos, inicie a etapa Enviar e verificar eventos

Enviar e verificar eventos

Para enviar eventos, faça uma solicitação POST para a borda da API /events. Anexe uma carga à sua chamada. Se precisar de ajuda para gerar a carga, acesse o Auxiliar de carga. Consulte os seguintes recursos para ver mais informações e exemplos de código:

• Enviar solicitações
• Eventos abandonados
• Tempo de carregamento versus tempo de transação do evento
• Solicitações em lote
• Uso de hash

Depois de começar a enviar eventos, visite o Gerenciador de Eventos para verificar se os recebemos. Saiba como fazer a Verificação de eventos.

Se a implementação estiver complementando um pixel de navegador, acesse as configurações de desduplicação. Caso contrário, está tudo pronto. Caso ainda tenha dúvidas, visite Suporte.

Etapa 3: adicionar parâmetros para a desduplicação

Se você estiver enviando eventos idênticos por meio do pixel e da API de Conversões, será necessário configurar a desduplicação deles. Antes, leia a documentação para desenvolvedores sobre a lógica da desduplicação.

Desduplicação baseada em eventos

Se encontrarmos a mesma combinação de chave de servidor (event_id, event_name) e de navegador (eventID, event) enviadas ao mesmo ID do Pixel dentro de 48 horas, descartaremos o evento duplicado enviado por último.

Veja como ajudar a garantir que os eventos sejam desduplicados:

• Para os eventos correspondentes, estes parâmetros devem ser definidos com o mesmo valor:

  • event_id do evento do servidor e eventID do evento do navegador;
  • event_name do evento do servidor e do evento do navegador.
• Depois de enviar eventos duplicados, visite o Gerenciador de Eventos para verificar se os eventos corretos estão sendo descartados.
• Certifique-se de que cada evento único enviado via Pixel e API de Conversões tem o próprio event_id. O ID não deve ser compartilhado com outros eventos.

Alternativa para desduplicação baseada em eventos

Embora o ID do evento seja sempre a melhor forma de desduplicar eventos, esse é um processo de implementação complexo. É possível aproveitar soluções alternativas usando o parâmetro external_id ou fbp. Se você configurou os parâmetros external_id ou fbp para serem passados por meio do navegador e do servidor, desduplicaremos os eventos com os mesmos parâmetros automaticamente em 48 horas.

Etapa 4 (opcional): explorar os recursos do SDK de Negócios

O SDK de Negócios da Meta tem recursos avançados criados especialmente para os usuários da API de Conversões:

• Solicitações assíncronas – Use esse recurso se não quiser bloquear a execução do seu programa para aguardar a conclusão de uma solicitação. Com essa abordagem, você faz a solicitação e recebe um sinal do servidor quando ela é concluída. Enquanto você espera a resposta, o programa pode continuar em execução.
• Lotes simultâneos – Aproveite as solicitações assíncronas para aumentar a taxa de transferência ao usar os recursos mais eficientes. Crie solicitações em lote para gerenciar casos de uso como solicitação de evento de funcionários, tarefas agendadas e muito mais.
• Interface de serviço HTTP – Substitua o serviço-padrão HTTP do SDK de Negócios e implemente o próprio serviço personalizado com o método ou a biblioteca da sua preferência.

Integração como plataforma

As instruções a seguir são para parceiros que oferecem a API de Conversões como um serviço para anunciantes.

Etapa 1: configurar requisitos

Seu app deve obter os seguintes recursos e permissões:

• Nível de acesso: acesso avançado
• Recurso: acesso padrão ao gerenciamento de anúncios
• Permissões: ads_management, pages_read_engagement e ads_read.

Etapa 2: enviar eventos em nome de clientes

Primeiro, siga as etapas de integração direta e teste a integração. Depois, solicite autorização para enviar eventos em nome de clientes. Você tem as seguintes opções de autenticação:

Abordagem da Extensão da Meta para Empresas (recomendada)

A Extensão da Meta para Empresas retorna todas as informações necessárias para enviar eventos em nome do cliente por meio do processo a seguir. Ela fornece um ponto de extremidade para recuperar os tokens de acesso do usuário do sistema criados no Gerenciador de Negócios do cliente. O processo inclui as permissões para enviar eventos do servidor, além de ser feito de forma automática e segura.

O ponto de extremidade requer um token de acesso do usuário como parâmetro de entrada. Após configurar a extensão, os novos usuários da Extensão da Meta para Empresas precisam fazer uma chamada ao ponto de extremidade para buscar o token de acesso do usuário do sistema. Os usuários existentes precisam solicitar uma nova autenticação antes de fazer chamadas para o novo ponto de extremidade da API.

Token de acesso do usuário do sistema do cliente

Seu cliente precisa criar um token de acesso do usuário do sistema manualmente por meio da API de Conversões nas configurações do Pixel. Depois, envie eventos para o Pixel do anunciante com o token.

Um usuário do sistema ou um usuário administrador do sistema precisa instalar o app que será usado para gerar o token de acesso. Com essa configuração, o app tem permissão para fazer chamadas de API em nome do usuário do sistema ou do usuário administrador do sistema.

O cliente compartilha o Pixel com o Gerenciador de Negócios do parceiro

Nessa opção, o cliente compartilha o Pixel com o parceiro por meio das configurações do Gerenciador de Negócios ou por meio da API. Depois, é possível atribuir o usuário do sistema parceiro ao Pixel do cliente e gerar um token de acesso para enviar eventos do servidor.

Etapa 3: atribuir eventos à sua plataforma

Para atribuir eventos da API de Conversões à sua plataforma, use o campo partner_agent. Isso permite que você defina seu identificador de plataforma ao enviar eventos em nome de um cliente. Caso você seja um parceiro gerenciado, trabalhe com o representante da Meta para definir o identificador. O valor deve ter menos de 23 caracteres e pelo menos dois caracteres alfabéticos. Depois, envie-o com todos os eventos do servidor.

Suporte

Para todos os parceiros

Consulte as informações sobre depuração e os artigos da Central de Ajuda para Empresas.

Para parceiros gerenciados

Para que seu representante da Meta ajude você nos testes de integração e na solução de problemas, forneça a ele estas informações: ID do Gerenciador de Negócios; ID do app e ID do Pixel.

Documentação da API

• Primeiros passos: teste a API no próprio Gerenciador de Negócios
• Como usar a API
• Boas práticas da API de Conversões
• Setup Conversions API as a Platform
• Eventos-padrão da Meta
• Eventos personalizados da Meta
• Parâmetros
• Auxiliar de carga
• Data Processing Options for Conversions API and Offline Conversions API
• Se você deseja otimizar para eventos do app, use a API de Eventos do App
• Se os eventos forem vendas no estabelecimento, use a API de Conversões Offline: eventos offline que não são vendas no estabelecimento são qualificados para API de Conversões