Rastreamento de formulários públicos

Este guia é destinado a quem mantém o site ou configura as tags de campanhas. Para criar e incorporar o formulário, siga Criar um formulário público e organizar as respostas. A versão da documentação para IA também está disponível.

Use o código de incorporação

Use o código gerado em Incorporar. O repasse da atribuição e a publicação dos eventos na página são automáticos no script oficial, sem opção ou atributo adicional. Não são necessários token do CRM, chave de API ou SDK adicional. O envio às plataformas começa desligado: pode ser configurado no cadastro do formulário ou pela integração do site.

<script async
  src="https://agilize.app/public-experience-form-embed.js"
  data-form="00000000000000000000000000000000"
  data-title="Solicitar contato"
  data-height="640"></script>

Substitua data-form pelo identificador presente no código do seu formulário. Autorize a origem HTTPS do site no cadastro. O script cria um iframe e usa uma comunicação validada por origem, janela, formulário e instância. Os campos não ficam diretamente no DOM da página hospedeira.

O código já instalado continua válido; não é necessário acrescentar data-tracking. Esses eventos se aplicam ao formulário incorporado pelo script oficial, não ao embed de portais ou agendas nem ao formulário aberto diretamente por link.

Preserve a origem da visita

O script lê os parâmetros do endereço da página que contém o formulário quando a incorporação fica pronta. Encaminha somente os parâmetros permitidos, sem copiar o fragmento nem parâmetros arbitrários. Atribuição e respostas não são publicadas no dataLayer.

Também são aceitos click_id/clickid e a referência ref, conforme o contrato de atribuição. O provedor é inferido dos identificadores e da origem. Os identificadores de clique preservam maiúsculas e minúsculas; os valores encaminhados são limitados a 500 caracteres e o endereço a 8.192 caracteres.

As dimensões são as mesmas usadas pelo BI: utm.provider, utm.source, utm.medium, utm.campaignId, utm.campaign, utm.groupId, utm.creativeId, utm.content e utm.term. Os campos utm.group e utm.creative continuam no contrato do CRM, mas não são inferidos de utm_term ou utm_content. Para relacionar resultados às entidades de mídia, informe os IDs na URL; GCLID/FBCLID não substituem os IDs de campanha, grupo e anúncio. Em ad_id, use o ID do anúncio, não o ID do objeto de criativo da plataforma.

Quando há FBCLID, o normalizador também deriva utmClick.fbc com o instante da captura e o preserva no envio. placement, lpvar, destvar, segment, cluster e offer são preservados no endereço filtrado para contexto; não criam novas dimensões no BI.

Essa integração não lê cookies de publicidade da página, não persiste atribuição nela nem recupera parâmetros de uma página visitada anteriormente. A campanha deve estar no endereço da página que contém o embed. O endereço filtrado acompanha a atribuição em utm.url.

Quando o destino localiza uma oportunidade existente, seus dados de origem não são substituídos. A atribuição deste envio permanece na resposta do formulário.

Eventos disponíveis

Cada evento é publicado no window.dataLayer da página hospedeira e como CustomEvent no window da mesma página.

O payload contém event e form_id. Os três eventos relacionados ao envio também contêm submission_id e event_id. O submission_id é o identificador público da resposta; não é o ID interno da oportunidade. O event_id, no formato form_<submission_id>, permite correlacionar os eventos desse envio. Nome, telefone, email, respostas e identificadores de clique não são incluídos.

{
  "event": "agilize_form_lead_confirmed",
  "form_id": "00000000000000000000000000000000",
  "submission_id": "11111111111111111111111111111111",
  "event_id": "form_11111111111111111111111111111111"
}

Oportunidade confirmada não significa necessariamente oportunidade nova. No modo localizar ou criar, um registro existente também pode satisfazer o destino. O evento confirma o resultado desse envio; ele não contabiliza exclusivamente novos cadastros.

O evento não depende de todos os outros destinos terminarem: uma oportunidade pode estar confirmada enquanto outro destino ainda está em processamento ou termina com falha. Formulários com destino somente de contato, empresa ou sem destinos não emitem agilize_form_lead_confirmed.

Configure o Google Tag Manager

Mantenha Enviar conversões pelo formulário desligado se o GTM já envia a mesma conversão ao mesmo destino.

1. Mantenha o GTM instalado na página que contém o formulário.
2. Crie um gatilho de Evento personalizado com o nome agilize_form_lead_confirmed.
3. Se a página contém vários formulários, crie uma variável da camada de dados para form_id e filtre o formulário desejado.
4. Vincule esse gatilho à tag de conversão escolhida: evento generate_lead do GA4, conversão do Google Ads ou tag da Meta. Informe os IDs e labels exigidos pela respectiva ferramenta.
5. Configure o consentimento na ferramenta de tags do site. A disponibilidade dos eventos não altera a decisão de privacidade do visitante.
6. Use o modo de visualização do GTM e confira a recepção na ferramenta de destino com uma submissão de teste.

Se o objetivo é apenas contar respostas recebidas, use agilize_form_submitted em vez da confirmação no CRM. Não use o clique no botão Enviar nem o gatilho genérico de envio de formulário para inferir sucesso dentro do iframe.

Escolha um único caminho para disparar a mesma conversão. Por exemplo, não configure simultaneamente uma tag no GTM e um listener JavaScript que enviem a mesma conversão ao mesmo destino. Importar o mesmo resultado do GA4 e medi-lo diretamente no Google Ads também exige revisar quais ações contam como conversão principal.

Receba os eventos por JavaScript

Registre o listener antes do script do embed para observar também os eventos iniciais:

window.addEventListener('agilize_form_lead_confirmed', function (event) {
  const { form_id, submission_id, event_id } = event.detail
  // Encaminhe estes metadados pela integração de sua escolha.
})

A Agilize não dispara conversões pela simples presença de um pixel na página. Sem configurar o envio no cadastro, não instala Meta Pixel/Google tag. As tags ou os listeners do cliente continuam sob controle da integração do site. O event_id não garante, por si só, deduplicação entre navegador e servidor em todas as plataformas.

Use o envio opcional da Agilize

Em Incorporar, ative Enviar conversões pelo formulário, adicione os destinos e clique em Salvar. Aguarde a atualização ficar disponível. É necessário um destino de oportunidade no CRM. A configuração aceita até quatro destinos distintos, sem código JavaScript arbitrário:

O visitante deve permitir a medição no formulário. Recusar não bloqueia o envio da resposta nem a captura de origem no CRM. A preferência é lembrada por formulário e configuração; pode ser revista em Preferências de medição. Uma mudança nos destinos exige nova escolha.

Os SDKs são carregados somente para enviar a confirmação autorizada, em um iframe técnico separado do formulário, sem respostas ou identificadores internos do CRM. São repassados apenas os campos de campanha selecionados e os identificadores gclid, gbraid, wbraid e fbclid disponíveis na atribuição. URLs arbitrárias, fragmentos e campos das respostas não são encaminhados. Os eventos públicos continuam sendo publicados normalmente.

O envio usa form_<submission_id> como identificador do evento e da transação Google, com controle de repetição por destino e resposta na sessão do navegador. Não há envio automático de PageView nem de conversão para um pixel apenas detectado no site. As configurações de agenda continuam independentes.

Essa opção também funciona no link direto do formulário. Para desativá-la, desligue a opção e clique em Salvar. Não há conversões pelo servidor nesta integração.

Como a medição nativa do formulário incorporado ocorre em outro contexto de domínio, restrições de cookies podem limitar a atribuição. Ela não compartilha automaticamente o identificador de cliente ou a sessão do GA4 já instalado na landing page. Para manter a sessão e os cookies da página hospedeira, use os eventos públicos com as tags do próprio site.

Limites e diagnóstico

Após um envio pelo embed, ou pelo link direto com envio nativo ativado, o formulário faz até cinco consultas de status para disponibilizar a confirmação no CRM, com intervalos de 1, 2, 4, 8 e 15 segundos. Interrompe as consultas quando o processamento termina, se houver erro de rede ou quando o formulário é desmontado. O período de espera soma 30 segundos, além do tempo das requisições. Não há consultas periódicas antes do envio, e as consultas não enviam dados a ferramentas de campanhas.

Se o processamento continuar, o botão Verificar processamento permite consultar novamente e publicar a confirmação quando disponível. Um mesmo tipo de evento para a mesma resposta é publicado uma única vez por instância do embed. Isso não substitui o controle de duplicidade da ferramenta de destino.

O acompanhamento depende de a página permanecer aberta. Fechar a página ou bloquear as tags pode impedir a conversão no navegador, mesmo com a resposta e a oportunidade registradas. Para acompanhar resultados depois que a página foi fechada, avalie uma integração de conversões pelo servidor separadamente.