API de Conversões para o Gerenciador de tags do Google no lado do servidor

A API de Conversões foi desenvolvida para criar uma conexão direta entre seus dados de marketing e os sistemas que ajudam a otimizar o direcionamento de anúncios, diminuir o custo por ação e mensurar os resultados em tecnologias da Meta. É possível configurar um servidor no Google Cloud Platform (GCP) ou outro provedor de nuvem para enviar dados importantes de eventos offline e da web por meio da API de Conversões. Com esse processo, depois de configurar a tag da web do Google Analytics 4 (GA4), você pode enviar os dados ao seu próprio servidor hospedado no Google Cloud Platform (GCP) e, por fim, à Meta usando a API de Conversões.

A tag da API de Conversões é escrita e mantida pela Meta com base no modelo de tag personalizado do Google. Entre em contato com o Google se tiver dúvidas sobre como configurar os produtos ou acessar a documentação para desenvolvedores da empresa.

Este documento descreve o seguinte:

• Pré-requisitos, incluindo como criar um contêiner de servidor
• Como configurar o contêiner para oferecer compatibilidade com sua implementação da tag da web do GA4
• Como enviar dados do seu site para o servidor do GCP
• Como compartilhar esses dados com a Meta por meio da API de Conversões
• Perguntas frequentes

Pré-requisitos

Antes de prosseguir com essa integração, recomendamos que você faça o seguinte:

1. Conheça a integração da API de Conversões e as boas práticas para configuração.
2. Explore a marcação no servidor e o modelo de tag personalizado.

Caso seu sistema use uma versão anterior ao GA4, atualize a configuração do gerenciador de tags atual para usar o GA4 antes de continuar com essa integração.

Integração

Criar um contêiner de servidor do Gerenciador de tags do Google

Você precisará configurar um contêiner de servidor e um da web:

• Contêiner da web: se for a primeira vez que você usa o Gerenciador de tags do Google (GTM, pelas iniciais em inglês), comece instalando um contêiner da web na sua conta. Saiba mais aqui.
• Contêiner de servidor: você terá que criar um contêiner de servidor no seu portal do GTM para configurar uma URL do servidor de marcação. Saiba mais sobre esta etapa.

Para configurar um contêiner de servidor, é preciso definir um servidor de marcação. O processo padrão de implantação do GCP pode ser realizado ao configurar o contêiner do servidor. Siga estas orientações. Para outros provedores de nuvem (como AWS ou Microsoft Azure), consulte o guia de configuração manual do servidor.

Configurar contêineres de servidor e da web

1. No seu contêiner da web, crie os seguintes artefatos:
   • Configuração do GA4 para definir a URL do servidor de marcação
   • Evento do GA4 para definir o esquema de eventos a ser entregue ao servidor
2. No seu contêiner de servidor, crie os seguintes artefatos:
   • Cliente do GA4, um ouvinte que dispara o evento para a Meta
   • Tag da API de Conversões da Meta, uma tag do lado do servidor que converte o modelo de evento padrão do cliente do GA4 para o esquema de eventos da API de Conversões e o envia a graph.facebook.com

Etapa 1 – Configuração do GA4: definir a URL do servidor de marcação

Configure o contêiner da web para enviar os dados do seu site ao servidor de marcação que foi criado. Saiba mais sobre como configurar a tag Google Analytics: configuração do GA4.

• Caso selecione Enviar para contêiner do servidor, configure a respectiva URL como a URL do servidor de marcação.
• Caso não tenha selecionado Enviar para contêiner do servidor, adicione uma linha em Campos a serem definidos e configure:

  • Nome do campo: transport_url
  • Valor do campo: a URL do servidor de marcação

É possível configurar campos adicionais como parâmetros a serem enviados para todos os eventos.

• Defina o sinalizador first_party_collection como true. É necessário fazer isso se você quiser passar os parâmetros user_data para o GTM no lado do servidor. Adicione uma linha em Campos a serem definidos e configure:

  • Nome do campo: first_party_collection
  • Valor do campo: true

Como usar uma tag de configuração existente do GA4

Caso você já tenha configurado o GA4, é possível fazer alterações ou criar uma tag de configuração adicional para o GTM do servidor.

Se você estiver configurando o GTM do servidor pela primeira vez, adicionar a URL do contêiner do servidor iniciará o envio de todo o seu tráfego para ele. Caso queira continuar enviando dados para o GA4, será preciso adicionar a tag desse servidor no contêiner, garantindo que ele seja acionado em todos os eventos. Talvez seja necessário criar outras tags de evento do GA4 ou modificar as existentes para garantir um mapeamento completo dos eventos de pixel da Meta.

Como enviar a identificação do navegador e a identificação do clique da Meta

Se você configurou um domínio personalizado e tem um domínio de servidor de marcação primário do GTM, a identificação do navegador e a identificação do clique da Meta são enviadas automaticamente.

Se você usar o domínio padrão ou perceber que os campos de identificação do navegador e identificação do clique não estão sendo enviados no Gerenciador de Eventos, é possível configurar esses campos da seguinte forma:

• Navegue até a seção de variáveis e crie uma definida pelo usuário como a identificação do navegador e a identificação de clique da Meta. Use o tipo de variável de cookies internos.

  • Para a identificação do navegador da Meta, defina o nome do cookie como _fbp.
  • Para a do clique da Meta, defina o nome como _fbc.
• Salve essas variáveis.
• Na tag de configuração do GA4, adicione uma linha em Campos a serem definidos e configure:

  • Nome do campo: x-fb-ck-fbp
  • Valor do campo: a variável de identificação do Navegador da Meta
• Adicione outra linha para a identificação de clique:
• Nome do campo: x-fb-ck-fbc
• Valor do campo: a variável de identificação do clique da Meta

Crie uma variável de camada de dados para cada parâmetro user_data do esquema de eventos comum do GTM. Saiba mais sobre como configurar variáveis de camada de dados. Por exemplo, para transmitir um endereço de email para o GTM no lado do servidor, crie uma variável (como user_data_email_address) que pode ser mapeada até o nome da variável de camada de dados, eventModel.user_data.email_address.

Caso você não esteja usando a camada de dados, configure as variáveis de cada parâmetro conforme indicado abaixo. A lista abaixo mostra todos os mapeamentos para parâmetros user_data da Meta e do GTM e a prioridade geral de cada um deles para ajudar a aumentar a qualidade da correspondência de eventos. Para aproveitar ao máximo os anúncios da Meta, siga as boas práticas da API de Conversões ao configurar uma integração. Caso você já tenha configurado a API de Conversões, considere seguir estas boas práticas para aprimorar sua configuração. As boas práticas da API de Conversões podem ajudar a melhorar o desempenho do seu anúncio reduzindo o custo por ação.

Etapa 2 – Evento do GA4: configurar o esquema de eventos a ser entregue ao servidor

• Configure o contêiner da web para enviar os dados do seu site ao servidor de marcação que foi criado para adicionar o Google Analytics. Saiba mais sobre como configurar a tag Google Analytics: configuração do GA4.

• Adicione a tag Google Analytics: evento do GA4 ao Workspace usando a galeria de modelos.

  • Configure um nome de evento para a tag. Isso pode ser definido como um valor estático ou configurado para ler a partir de uma variável. Para determinados eventos padrão, mapearemos os do Google Analytics aos equivalentes da Meta. Nesses eventos, é possível usar o nome do evento do Google Analytics ou o da Meta. Nos outros eventos padrão, use o da Meta. Em eventos personalizados, use o nome do evento personalizado. Saiba mais. Saiba mais.

• Na seção de parâmetros do evento, faça o seguinte:

  • Se você está usando o Pixel da Meta, adicione o parâmetro de ID do evento. Use event_id como nome do parâmetro e a variável criada para o ID do evento como o valor do parâmetro. Consulte a seção Desduplicação para saber como criar a variável de ID do evento e modificar o Pixel da Meta.
  • Mapeie cada um dos parâmetros que você quer configurar. O nome da variável será lido a partir do evento usando um esquema de eventos comum. Por exemplo, para configurar "email" como um parâmetro de evento, defina o nome de parâmetro user_data.email_address e o valor como o nome da variável que lê o email_address (definida na etapa 1).
  • Para ver a lista completa, consulte a seção Parâmetros de dados personalizados.

Etapa 3 – Criar um ouvinte para o evento que aciona o evento para a Meta

Cada contêiner no lado do servidor do GTM vem com um cliente do GA4 padrão para ouvir eventos configurados a partir da sua tag da web do GA4. O cliente do GA4 detecta a rota /g/collect na URL do servidor de marcação e envia o eventModel à tag posterior. Se o cliente padrão do GA4 já estiver instalado no seu contêiner de servidor, pule para a etapa 4.

Etapa 4 – Criar a tag da API de Conversões da Meta, uma tag do lado do servidor que converte o modelo de evento padrão do cliente do GA4 para o esquema de eventos da API de Conversões e o envia a graph.facebook.com

Para enviar o evento à API de Conversões, você precisa instalar a tag da API de Conversões da Meta usando a Galeria de modelos. O modelo de marcação se chama Tag da API de Conversões pelo facebookincubator. É possível configurar essa tag para ser acionada em eventos recebidos pelo cliente do GA4 na etapa anterior e enviada à API de Conversões. Para instalar a tag da API de Conversões da Meta, você precisa ter uma identificação do pixel e um token de acesso, além de especificar a fonte da ação como "site". Ao usar a API de Conversões, você concorda em garantir a precisão do parâmetro action_source conforme seu conhecimento.

Como testar a integração

Recomendamos usar o modo de prévia do Gerenciador de tags do Google para testar as integrações antes de publicar as alterações. Os contêineres da web e do servidor possuem modos de prévia e podem ser executados ao mesmo tempo.

É possível usar o recurso Eventos de Teste do Gerenciador de Eventos para verificar se os seus eventos de servidor estão sendo recebidos conforme esperado. Para encontrar a ferramenta, vá para Gerenciador de Eventos > Fontes de dados > Pixel de [nome do usuário] > Eventos de Teste.

A ferramenta Eventos de Teste gera um ID de teste. Envie esse ID de teste como um parâmetro test_event_code na tag de API de Conversões para ver a atividade do evento na janela dos Eventos de Teste. Remova-o antes de publicar as alterações.

A ferramenta de eventos de teste permite que você verifique se os eventos estão sendo recebidos e as respectivas duplicações estão sendo eliminadas corretamente. Caso não veja os eventos após um minuto ou dois, consulte o depurador do servidor do GTM para verificar se a solicitação foi realizada corretamente:

1. No depurador do servidor, escolha o evento a ser verificado no menu à esquerda.
2. Verifique se a tag está sendo exibida na seção de tags acionadas. Se for o caso, você verá "Conversions API Tag - Succeeded" ou "Conversions API Tag - Failed".
   • Tag não acionada: verifique o gatilho da tag da API de Conversões e o do evento do GA4 relacionado no contêiner da web. Consulte o depurador da web para ver se o evento do GA4 foi acionado.
   • Tag acionada com sucesso: clique na tag e verifique se o código do evento de teste está correto. Se necessário, atualize esse código e reinicie o modo de prévia.
   • Tag acionada com falha: abra a aba de solicitação e clique na solicitação de saída enviada para https://graph.facebook.com. Analise o corpo da resposta nos detalhes na parte inferior da solicitação para ver o tipo de erro e atualize a integração conforme necessário. Não esqueça de reiniciar o modo de prévia depois de fazer alterações.

Quando os eventos forem exibidos, verifique se os IDs de evento estão sendo enviados, bem como se todas as chaves de correspondência esperadas e os parâmetros de dados personalizados estão sendo mostrados corretamente. A ferramenta de eventos de teste mostrará se a desduplicação dos eventos está ocorrendo corretamente. Caso os IDs de evento sejam diferentes, garanta que as tags do GA4 e do Pixel da Meta sejam acionadas no mesmo gatilho e revise sua implementação da variável de ID de evento.

Desduplicação

Recomendamos que você use uma configuração de evento redundante e compartilhe os mesmos eventos da API de Conversões e do Pixel da Meta. Verifique se ambos os eventos usam o mesmo event_name e se event_id ou uma combinação de external_id e fbp estão incluídos.

Isso permite que a Meta desduplique eventos e diminua os relatórios duplos de eventos idênticos. Saiba mais sobre a desduplicação, quando ela é necessária e como configurá-la. external_id e fbp são soluções alternativas para desduplicação e também ajudam a melhorar a qualidade da configuração. Recomendamos incluir os três parâmetros sempre que possível.

O GTM tem diversas maneiras de configurar um parâmetro com o mesmo valor em uma tag de navegador e uma de servidor. Uma delas é usar o mesmo evento do GA4 para acionar a tag do Pixel da Meta e o evento do servidor. Para fazer isso:

• Use o mesmo gatilho para a tag de HTML personalizada e a tag de evento do GA4 do seu Pixel da Meta. Por exemplo, é possível definir uma condição de gatilho com base na URL da página de confirmação do pedido.
• Use a mesma event_id nas duas tags:

  1. Crie uma identificação única do cliente: defina um parâmetro personalizado (x-fb-event_id) a partir do evento gtag. Gere uma identificação única (por evento) no site usando um método JavaScript (ou a variável JavaScript personalizada do Gerenciador de tags do Google) e defina o valor no evento como:

  gtag('event', 'purchase', {
   'x-fb-event_id': generateEventId(),
  ...:...
  
   });

  É possível criar uma variável que direcione para o JavaScript personalizado mostrado acima. Sempre que a variável for consultada, o JavaScript abaixo será carregado na linha:

  function() {
  var gtmData = window.google_tag_manager[{{Container ID}}].dataLayer.get('gtm');
  return gtmData.start + '.' + gtmData.uniqueEventId;
  }

  2. Crie e preencha uma variável de camada de dados: você pode criar sua própria variável no contêiner da web para ler o valor de event_id. Para fazer isso, crie uma nova variável de camada de dados, por exemplo, FBEventIdVar, com o nome definido como eventModel.event_id.
  3. Depois que a variável for definida, conecte-a ao evento da web na sua tag HTML personalizada e no evento do servidor como um parâmetro de evento do GA4 adicional.
  4. Na web, você pode configurar sua tag da Meta nos contêineres da web do Gerenciador de tags do Google para ler event_id a partir da variável.

  fbq('track', Purchase, {..}, {eventID: FBEventIDVar });

  Configure o evento do GA4 para enviar um parâmetro extra, chamado event_id e definido como a variável FBEventIdVar.

Parâmetros de dados personalizados

Para enviar dados personalizados, use os mapeamentos abaixo nas suas tags de eventos do GA4:

Enviar dados do seu site ao servidor do GCP

Depois de concluir essas configurações, envie um exemplo de evento do seu site para verificar o evento do servidor. Um exemplo de evento com os parâmetros configurados pode ter esta aparência:

 gtag('event', 'purchase', 
  {
    'event_id': generateEventId(),
    'transaction_id': 't_12345',
    'currency': 'USD',
    'value': 1.23,
    user_data: {
      email_address: '<HASHED_DATA>',
      phone_number: '<HASHED_DATA>',
      address: {
        first_name: '<HASHED_DATA>',
        last_name: '<HASHED_DATA>',
        city: '<HASHED DATA>',
        region: '<HASHED_DATA>',
        postal_code: '<HASHED_DATA>',
        country: '<HASHED_DATA>'     
      },    
    },
    items: [
      {
        item_id: '1',
        item_name: 'foo',
        quantity: 5,
        price: 123.45,
        item_category: 'bar',
        item_brand: 'baz'     
      }
    ], 
  });      
     

Depois que o evento for acionado, você deverá ver uma solicitação enviada (por exemplo, para um link de amostra: www.analytics.example.com/g/collect), com os parâmetros configurados. Adicione o código do evento de teste à tag da API de Conversões da Meta para verificar eventos enviados a essa API. O código do evento de teste só deve ser usado em testes. É necessário removê-lo ao enviar sua carga de produção.

Depois de publicar as alterações, consulte Verifying Your Setup para garantir os eventos sejam enviados corretamente na verificação de configuração da API de Conversões e analise se a integração de qualidade atende às nossas boas práticas.

Perguntas frequentes

Existem planos para adicionar a capacidade de enviar parâmetros personalizados? Se a resposta for afirmativa, quando esse recurso estará disponível?
R: Adicionamos mapeamento para a maioria dos parâmetros personalizados padrão da API de Conversões que são compatíveis com o esquema do GTM. Também fornecemos mapeamento personalizado. Clique aqui para saber mais.

Um único servidor ou cluster é capaz de executar vários contêineres?
R: Atualmente, o GTM é compatível apenas com o mapeamento individual. Leia as recomendações sobre como organizar contêineres.

O GTM no servidor requer uma tag baseada em navegador para emitir eventos?
R: Sim.

É possível manter a integração do GA4 separada do servidor?
R: Para manter integrações separadas do GA4 e do GTM do servidor, é possível criar um ID de mensuração adicional no Google Analytics. Crie uma tag de configuração do GA4 separada para o GTM do servidor usando o ID de mensuração e seguindo as etapas acima. Neste cenário, a tag de configuração existente do GA4 continuará a enviar o tráfego do GA pelo contêiner da web. Já a nova tag de configuração enviará dados ao contêiner do servidor. Crie outras tags de evento do GA4 conforme a etapa 2 para enviar eventos do servidor usando a nova tag de Configuração.

A integração da API de Conversões do GTM funciona com soluções de hospedagem na nuvem que não sejam o GCP?
R: A integração da API de Conversões do GTM deve funcionar com o GCP ou qualquer outra plataforma da sua escolha. Leia mais sobre provisionamento manual.

Saiba mais

• API de Conversões
• Sobre a desduplicação de eventos do Pixel da Meta e da API de Conversões