> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xtracky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# UTM Handler (V1)

> Script legado da xTracky — captura UTMs clássicas via URL. Preserve pra integrações antigas.

<Warning>
  **V1 é legado.** Para novas integrações use o [Lead System V2](/scripts/lead-system). O V1 permanece mantido pra retrocompatibilidade e casos de uso simples que não precisam atribuição multi-plataforma.
</Warning>

## Instalação

```html theme={null}
<script
  src="https://cdn.xtracky.com/scripts/utm-handler.js"
  data-token="SEU_PRODUCT_ID"
  data-click-id-param="click_id">
</script>
```

## Atributos

<ParamField path="data-token" type="string" required>
  Product ID (UUID) do seu produto na xTracky.
</ParamField>

<ParamField path="data-click-id-param" type="string" default="click_id">
  Nome do parâmetro na URL onde o click ID chega. Padrão `click_id` (Kwai). Use `ttclid`, `fbclid` ou `gclid` conforme a plataforma.
</ParamField>

## O que ele faz

* Captura os parâmetros UTM clássicos (`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`) da URL
* Persiste no cookie por 30 dias
* Preenche automaticamente inputs `<input name="utm_source">`, `<input name="utm_medium">`, etc. em qualquer formulário da página

## O que ele **não** faz

* Não detecta plataforma automaticamente
* Não gera `LeadId`
* Não escuta navegação SPA
* Não dispara eventos multi-step

## Enviando a conversão

Ao enviar a venda via API, envie o valor de `utm_source` que você capturou:

```javascript theme={null}
const utmSource = new URLSearchParams(location.search).get('utm_source') || '';

fetch('https://api.xtracky.com/api/integrations/api', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    orderId: 'ORDER_123',
    amount: 9990,
    status: 'paid',
    utm_source: utmSource,
  }),
});
```

## CDN alternativo

Se o CDN principal estiver bloqueado, use jsDelivr:

```html theme={null}
<script
  src="https://cdn.jsdelivr.net/gh/xTracky/static/utm-handler.js"
  data-token="SEU_PRODUCT_ID"
  data-click-id-param="click_id">
</script>
```

Ver [Evitar URL Scan](/scripts/avoid-urlscan) pra contexto.