> ## 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.

# Instalação do Script

> Cole o script no <head> do seu funil e comece a rastrear leads em segundos.

Insira o script em **todas as páginas do seu funil** (landing, checkout, obrigado), imediatamente após a abertura da tag `<head>`. O script detecta automaticamente a plataforma de anúncios (Kwai, TikTok, Meta, Google) pelo parâmetro de click na URL e gera um `LeadId` persistente que cola clique → sessão → venda.

## Escolha a versão do script

<Tabs>
  <Tab title="Recomendado (V2 — Lead System)">
    ```html theme={null}
    <script
      src="https://cdn.xtracky.com/scripts/experimental.js"
      data-token="SEU_PRODUCT_ID"
      data-step-id="checkout"
      async>
    </script>
    ```

    <Check>
      **V2 — Sistema de Leads**\
      Detecção automática de plataforma, tracking multi-step, suporte a SPA e deduplicação inteligente. Gera um `LeadId` único por visitante (ex: `TT-1763007625226-yn4xita3qylwh`).
    </Check>
  </Tab>

  <Tab title="Padrão (V1 — UTM Handler)">
    ```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>
    ```

    <Info>
      Use o V1 se você já tem uma integração legada dependendo do formato clássico UTM. Para novas integrações, prefira sempre o V2.
    </Info>
  </Tab>

  <Tab title="CDN Alternativo (anti-bloqueio)">
    ```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>
    ```

    <Warning>
      Use esta opção se a URL principal (`cdn.xtracky.com`) estiver sendo bloqueada por ferramentas de URL scan. Ver [Evitar URL Scan](/scripts/avoid-urlscan).
    </Warning>
  </Tab>
</Tabs>

## Atributos do script

<ParamField path="data-token" type="string" required>
  ID do seu produto na xTracky (UUID). Encontrado no painel em **Produtos → Detalhes do Produto**.
</ParamField>

<ParamField path="data-step-id" type="string">
  Identificador da etapa do funil (ex: `checkout`, `upsell`, `obrigado`). Usado no V2 para tracking multi-step.
</ParamField>

<ParamField path="data-click-id-param" type="string" default="click_id">
  Nome do parâmetro de click ID na URL. Usado no V1. Padrão: `click_id`.
</ParamField>

## Detecção automática de plataforma (V2)

O script V2 identifica a plataforma de origem lendo o parâmetro de click na URL e escolhe o prefixo do `LeadId`:

| Parâmetro na URL | Plataforma      | Prefixo do Lead                              |
| ---------------- | --------------- | -------------------------------------------- |
| `click_id`       | Kwai            | <span style={{color:'#3b82f6'}}>`KW-`</span> |
| `ttclid`         | TikTok          | <span style={{color:'#a855f7'}}>`TT-`</span> |
| `fbclid`         | Facebook / Meta | <span style={{color:'#3b82f6'}}>`FB-`</span> |
| `gclid`          | Google Ads      | <span style={{color:'#22c55e'}}>`GG-`</span> |

<Tip>
  Configure suas campanhas para preservar esses parâmetros na URL de destino. A xTracky captura automaticamente e mantém o `LeadId` no cookie/localStorage do visitante — mesmo se ele navegar entre páginas ou abandonar e voltar depois.
</Tip>

## Próximo passo

<Card title="Enviar sua primeira conversão" icon="rocket" href="/comece-aqui/primeira-conversao">
  Do lead capturado à venda registrada na xTracky
</Card>
