Este documento foi atualizado.
A tradução para Português (Brasil) não foi concluída ainda.

Atualização em inglês: 27 de fev

3: Implementação do desenvolvedor

Esta página lida com a integração manual e abrange:

Como construir a carga para integração de CRM
Como gerar um token de acesso e preparar uma chamada de API
Como enviar uma carga de teste
Como enviar dados de produção

Esta seção só é aplicável se decidir concluir essa integração por meio de uma integração manual e de recursos de desenvolvedor. Em vez disso, se você desejar concluir essa integração usando um parceiro, siga as respectivas instruções de parceiro para a integração. Você pode pular para a seção 4: Verifique os seus dados deste guia assim que a integração de parceiros estiver concluída.

Você precisará de acesso de administrador do Gerenciador de Negócios para concluir essas etapas de integração. Você pode obter acesso a partir do email enviado se recebeu um convite como desenvolvedor. Caso contrário, entre em contato com um administrador do Gerenciador de Negócios para pedir acesso.

Etapa 1: Construir uma carga

Esta etapa definirá as especificações de carga para a integração de cadastros de conversão e fornecerá algumas recomendações sobre como enviá-la a partir do seu servidor.

Abra o guia de integração de CRM na aba Configurações do seu pixel de CRM para começar.

Leia o Guia de desenvolvedores da API de Conversões para entender como a API de Conversões funciona.

Recomendamos usar o Auxiliar de carga para construir sua carga. O Auxiliar de carga formatará sua carga e verificará se há erros. Assim que todos os erros de carga forem resolvidos, clique no botão Obter código dentro do Auxiliar de carga para gerar um modelo de código para sua linguagem de programação.

Veja a seguir a lista de parâmetros obrigatórios. Leia o Guia Integração de cadastro de conversão – Payload Specification para ver a descrição completa de cada parâmetro. Essa especificação de carga deve ser usada apenas para eventos de otimização de cadastros de conversão. Isso significa que os eventos devem referir-se apenas aos anúncios de cadastros da Meta e ter um ID de cadastro válido. Evite usar essa especificação de carga para outros tipos de eventos, como cadastros de site.

Parâmetros

Nome	Descrição
`event_name` string	Campo de formulário livre para capturar os estágios de cadastro usados no CRM. O parâmetro `event_name` deve indicar um cadastro que se move pelo funil de vendas no CRM. Certifique-se de enviar todos os estágios conforme forem atualizados, incluindo o cadastro inicial.
`event_time` inteiro	Um registro de data e hora do Unix em segundos indicando quando o evento de atualização do estágio do cadastro é atualizado pelo CRM. O registro de data e hora deve ocorrer após o horário de geração do cadastro ou, caso contrário, o evento pode ser descartado.
`action_source` string	Valor:`system_generated` (Ao usar a API de Conversões, você concorda em garantir a precisão do parâmetro `action_source` conforme seu conhecimento.)
`lead_id` inteiro	O `leadgen_id` de 15 ou 16 dígitos dos seus cadastros baixados.
`lead_event_source` string	O nome do CRM de onde os eventos são provenientes.
`event_source` string	Valor:`crm`

Exemplo
Um exemplo de carga pode ter a seguinte aparência. Nota: você deve usar um lead_id válido ou, caso contrário, o sistema rejeitará seu evento.

{
    "data": [
        {
            "event_name": "initial_lead",
            "event_time": 1629424350,
            "action_source": "system_generated",
            "user_data": {
                "lead_id": 525645896321548
            },
            "custom_data": {
                "event_source": "crm",
                "lead_event_source": "salesforce"
            }
        }
    ]
}

Se os eventos não seguirem a especificação de carga ou não corresponderem a um anúncio de cadastro da Meta, eles não serão reconhecidos para a integração e não serão usados para treinar o modelo.
Por exemplo, a carga da web será aceita pela API de Conversões e será exibida no Gerenciador de Eventos, mas não será reconhecida para essa integração. Você também deve usar um lead_id válido ou, caso contrário, o sistema rejeitará seu evento.
Somente a carga de Cadastros de conversão será reconhecida para a integração e usada para treinamento.

Etapa 2: Criar um token de acesso e uma chamada de API

Assim que configurar o que você enviará, a próxima etapa é configurar para onde enviará os dados.

Essa etapa ajudará você a gerar um token de acesso para seu pixel da Meta, que será usado para estabelecer uma conexão entre seu servidor e a API de Conversões.

Você pode voltar ao guia de integração de CRM a partir da aba Configurações do pixel de CRM.

Role a tela para baixo até à seção Criar ponto de extremidade e clique no botão Gerar token de acesso. O token de acesso será usado para criar a chamada de API.
Você pode gerar um novo token de acesso retornando ao guia de integração ou na aba Configurações em Gerenciador de Eventos navegando até a seção API de Conversões e clicando no link Gerar token de acesso.

O resto deste guia variará dependendo de você estar utilizando ou não o SDK da Meta. Usar o SDK de Negócios da Meta é recomendado, porque ele oferece melhores mensagens de erro e diagnóstico. Você precisará do ID do pixel e do token de acesso para fazer a chamada da API por meio do SDK de Negócios da Meta. Para obter o token de acesso, clique em Copiar token de acesso no guia de integração de CRM e salve-o. Exemplos de chamadas de API do SDK podem ser encontrados em Como usar a API ou na funcionalidade Obter Código dentro do Auxiliar de carga da Meta.

Este é o formato do ponto de extremidade para fazer uma solicitação POST à API de Conversões sem o SDK. Você pode obter todo o ponto de extremidade clicando em Copiar ponto de extremidade no guia de integração do CRM e salvando-o.
```
https://graph.facebook.com/API_VERSION/PIXEL_ID/events?access_token=ACCESS_TOKEN
```
- API_VERSION: a versão atual da API de Marketing
- PIXEL_ID: o ID do pixel pode ser obtido no Gerenciador de Eventos para cada pixel
- ACCESS_TOKEN: o token de acesso gerado acima
Você pode ver as datas de lançamento e de validade da API de Marketing na documentação Versões. Certifique-se de atualizar a versão da API ou o SDK de Negócios da Meta no código antes da data de validade da API de Marketing. Usar uma versão obsoleta no código pode resultar em erros, e seus eventos podem ser descartados pelo sistema.

Etapa 3: Testar uma carga (opcional)

Neste momento, é possível enviar uma carga de teste para o pixel antes de implementar o código no servidor. Você pode fazer isso por meio da aba Eventos de Teste no Gerenciador de Eventos.

Na seção Testar eventos do servidor, clique no link Explorador da Graph API. Usar este link exclusivo preencherá algumas informações do pixel. (Você também pode acessar diretamente o Explorador da Graph API se desejar.) Preste atenção no valor test_event_code, que pode mudar ao longo do tempo.

Complete o seguinte na ferramenta Explorador da Graph API:
1. Certifique-se de que esteja no modo POST.
2. Verifique se a versão da API e o ID do pixel estão corretos.
3. Mude para a visualização JSON.
4. Insira sua carga. Ela pode ser criada ou gerada manualmente usando o Auxiliar de carga. Certifique-se de incluir o parâmetro test_event_code da etapa anterior e um lead_id válido.
Insira seu token de acesso do pixel e clique no botão Enviar.

Se a sua carga não tiver nenhum erro relacionado à sintaxe ou à API, você deverá receber uma mensagem de sucesso com um fbtrace_id.

Após alguns momentos, o evento de teste deve aparecer na aba Eventos de teste no Gerenciador de Eventos.

Etapa 4: enviar dados de produção

Os dados de produção devem estar no mesmo formato que a carga gerada na Etapa 3, exceto se os dados forem provenientes diretamente do servidor. Esta etapa variará de acordo com a integração; por isso, esta seção fornecerá orientações em vez de uma apresentação.

Envie o lead_id em vez de PII para correspondência.

Certifique-se de enviar todos os estágios dos cadastros conforme são atualizados, incluindo o evento de cadastro inicial que representa todos os cadastros gerados na Meta e baixados para o CRM. Veja a seguir um exemplo de funil. Os nomes e estágios do evento são definidos pelo anunciante, então, não precisam seguir este exemplo.

Se as suas campanhas gerarem 100 cadastros, esperamos que 100 eventos de "Cadastro inicial" sejam carregados para representar o primeiro estágio do cadastro. Enviar o primeiro estágio de cadastro informará o sistema de que o cadastro foi recebido e processado. À medida que os cadastros descem no funil de vendas, esperamos que 70 estágios de "Cadastro qualificado de marketing", 30 de "Oportunidade de vendas" e 15 de "Convertidos" sejam carregados.

Para recapitular, 100 cadastros são gerados a partir das campanhas, mas esperamos que 215 eventos sejam carregados neste cenário de exemplo.

Crie uma função que recupere atualizações da API ou do banco de dados do CRM sempre que o status do cadastro for atualizado. Depois, envie sua carga para a API de Conversões da Meta usando uma função personalizada ou o SDK de Negócios da Meta. O que faz mais sentido para sua integração dependerá do CRM e da configuração de banco de dados.

Variáveis são recomendadas para:
- lead_id
- event_name
- event_time
Por exemplo, uma carga que indica explicitamente os valores dos parâmetros pode parecer com a seguinte:
```
{
  "event_name": "initial_lead",
  "event_time": 1628294742,
  "user_data": {
    "lead_id": 1234567890123456
  },
  "action_source": "system_generated",
  "custom_data:" {
    "lead_event_source": "Salesforce",
    "event_source": "crm"
  }
}
```
Uma carga que passa em valores a partir do banco de dados usando variáveis pode parecer com a seguinte:
```
{
  "event_name": lead_stage // "initial_lead"
  "event_time": unix_time // 1628294742
  "user_data": {
    "lead_id": fb_lead_id // 1234567890123456
  },
  "action_source": "system_generated",
  "custom_data:" {
    "lead_event_source": "Salesforce",
    "event_source": "crm"
  }
}
```

Carregue dados pelo menos uma vez por dia. O ideal é que as chamadas para o CRM sejam feitas em tempo real, mas você pode utilizar métodos de lote diários ou de hora se uma integração em tempo real não for viável.
Se escolher os métodos de lote, certifique-se de capturar o histórico de alterações no status dos cadastros em vez de um instantâneo do cadastro no momento do lote. Por exemplo, se o status de um cadastro for atualizado 3 vezes entre os lotes, esperaríamos 3 eventos para esse cadastro em vez de apenas a atualização final.
Nota: cada lote pode incluir até 1.000 eventos. Se houver um erro no lote, todo o lote será descartado; então, RECOMENDAMOS que utilize lotes menores e adicione lógica para tentar novamente.

Opcional. Recomendamos registrar mensagens de erro a partir da chamada da CAPI e criar alertas se houver problemas. Também seria recomendável incluir uma manipulação de exceções para esses erros.

Você pode preencher seus dados por até 7 dias no passado. A diferença de tempo é calculada entre event_time e upload_time. Preencher alguns dados pode acelerar o processo de treinamento.
AVISO: não tente preencher mais de 7 dias de dados modificando os valores event_time. O modelo depende de um horário preciso para ser otimizado. Ao fazer isso, todos os seus dados preenchidos poderão ser descartados.
Certifique-se de que os valores event_time fiquem após o registro de data e hora da geração de cadastros; caso contrário, seus eventos podem ser descartados.

Você deve começar a ver eventos no Gerenciador de Eventos para seu pixel dentro de uma hora se a sua integração estiver carregando eventos para a Meta. Lembre-se de usar um lead_id válido nas suas cargas para os eventos aparecerem. Abra cada evento enviado para a integração de CRM de cadastros de conversão no Gerenciador de Eventos e verifique se eles têm os parâmetros personalizados lead_event_source e event_source preenchidos. Se o evento não tiver esses parâmetros, ele não será registado como um evento de cadastros de conversão.
O sistema verificará se algum dos seus eventos é válido para cadastros de conversão. Após 1 dia, uma marca de seleção verde aparecerá ao lado da etapa Enviar um evento de CRM da integração se for detectado um evento válido.

< 2: Getting Started With the CRM Integration

4: Verificar os dados >