# Agilize Docs para IA - Página atual

Este arquivo contém uma versão focada e legível por IA da página aberta na documentação pública da Agilize.
Use esta versão quando a pergunta do usuário estiver restrita ao documento atual.

Última geração: 2026-11-10T17:01:02.400Z

## Página

- Título: Rastreamento de formulários públicos
- URL humana: https://agilize.app/docs/desenvolvedores/guias-integracao/rastreamento-formulario-publico
- Leitura completa para IA: https://agilize.app/docs/llms.txt
- Descrição: Integre o formulário incorporado ao GTM, receba eventos e preserve UTMs e identificadores de clique no CRM.

## Seções

- Use o código de incorporação
- Preserve a origem da visita
- Eventos disponíveis
- Configure o Google Tag Manager
- Receba os eventos por JavaScript
- Use o envio opcional da Agilize
- Limites e diagnóstico

## Conteúdo da página

# 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](/docs/configuracao/crm-dados/criar-formulario-publico). A [versão da documentação para IA](https://agilize.app/docs/llms.txt) 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.

```html
<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`.

| Parâmetros da página | Destino ao criar uma oportunidade |
| --- | --- |
| `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term` | `lead.utm.source`, `medium`, `campaign`, `content`, `term` |
| `utm_id`, `campaign_id` ou `ad_campaign_id` | `lead.utm.campaignId` |
| `adset_id`, `ad_set_id`, `adgroup_id` ou `ad_group_id` | `lead.utm.groupId` |
| `ad_id` ou `ad_creative_id` | `lead.utm.creativeId` |
| `gclid`, `gbraid`, `wbraid`, `fbclid`, `ttclid` | Campos correspondentes em `lead.utmClick` |
| `ctwa_clid` ou `ctwaclid` | `lead.utmClick.ctwaClid` |

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.

| Evento | Quando ocorre |
| --- | --- |
| `agilize_form_ready` | A comunicação do formulário com o embed ficou pronta. |
| `agilize_form_start` | Primeira interação com uma pergunta. |
| `agilize_form_submitted` | A resposta foi persistida. Não confirma o destino no CRM. |
| `agilize_form_lead_confirmed` | Pelo menos um destino de oportunidade foi concluído com referência a um registro no CRM. |
| `agilize_form_processing_failed` | O processamento terminou com falha. Não é emitido para uma tentativa ainda recuperável. |

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.

```json
{
  "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:

```js
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:

| Destino | Dados necessários | Evento enviado após confirmar a oportunidade |
| --- | --- | --- |
| Meta | ID numérico do pixel | `fbq('trackSingle', pixelId, 'Lead', {}, { eventID })` |
| Google Analytics 4 | ID `G-...` | `generate_lead` com `send_to` explícito |
| Google Ads | ID `AW-...` e rótulo da ação | `conversion` com `send_to: 'AW-.../rotulo'` |

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.

| Sintoma | O que conferir |
| --- | --- |
| Não há eventos na página | Uso do script oficial, origem autorizada e iframe carregado. |
| Há resposta recebida, mas não confirmação | Destino de oportunidade, situação em Respostas e tempo de processamento. |
| A origem não acompanha a nova oportunidade | Parâmetros na página do embed, uso do script oficial e modo criar/localizar configurado. |
| O evento chegou ao GTM, mas não à plataforma | Gatilho, tag, destino, consentimento, bloqueadores e diagnóstico da ferramenta de campanhas. |
| O resultado foi contado duas vezes | Tags duplicadas, listeners próprios e automações de conversão existentes no CRM. |