# Script de rastreamento

> Envie eventos do workspace e eventos personalizados do seu site com o script de rastreamento do Emailit e uma chave de rastreamento pública. Instale-o, rastreie eventos, identifique visitantes e limite a chave aos seus sites.

O script de rastreamento envia eventos do seu site: visualizações de produtos, cadastros, itens adicionados a um carrinho. Ele não precisa de uma chamada de configuração; a chave de rastreamento faz parte da URL dele. Esta página explica como criar uma chave, adicionar o script, rastrear eventos e vinculá-los aos seus visitantes.

## Antes de começar

- O script de rastreamento está incluído nos planos Pro, Business e Custom. No Pay as you go, não é possível criar chaves de rastreamento, e as requisições do script retornam `403`, inclusive com chaves criadas antes da mudança para o Pay as you go.
- Para criar chaves de rastreamento no painel, é preciso ter o papel **Admin** no workspace. Pela API, use uma chave **Full Access**.
- Você precisa poder editar o HTML do seu site ou adicionar uma tag HTML personalizada no seu gerenciador de tags.

## Criar uma chave de rastreamento

As chaves de rastreamento são públicas: elas ficam nas suas páginas web, então qualquer pessoa pode lê-las. Elas só podem enviar eventos do workspace e eventos personalizados, nunca ler dados, e você pode limitá-las aos seus próprios sites.

**Painel**

  1. **Abra o rastreamento.** Acesse **Email API → Events**, selecione a aba **Tracking** e depois **Create tracking key**.

  2. **Dê um nome à chave.** Em **Name**, digite um nome que indique onde ela é usada, como `Online shop`.

  3. **Limite-a aos seus sites.** Em **Allowed origins**, digite os seus sites, um por linha, por exemplo, `https://shop.example.com` ou `*.example.com`. Deixe o campo vazio para aceitar qualquer site. Consulte [Sites permitidos](#allowed-sites).

  4. **Crie a chave.** Selecione **Create**. A aba **Tracking** passa a mostrar o snippet com a sua chave já preenchida.

**API**

  Chame [Criar uma chave de rastreamento](/pt/docs/api-reference/tracking-keys/create/). O valor de `key` na resposta vai na URL do script.

```bash
curl -X POST https://api.emailit.com/v2/tracking-keys \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Online shop", "allowed_origins": ["https://shop.example.com"] }'
```

## Adicionar o script

Cole as duas tags em todas as páginas, de preferência antes de `</head>`, com a sua chave no lugar de `TRACKING_KEY`:

```html
<script>window.emailit=window.emailit||function(){(window._emailitq=window._emailitq||[]).push(arguments)};</script>
<script async src="https://js.emailit.com/track/TRACKING_KEY/events.js"></script>
```

A primeira tag coloca na fila as chamadas feitas antes de o script carregar, então você pode chamar `emailit(...)` imediatamente. O script carrega de forma assíncrona, nunca lança erros na sua página e também funciona a partir de um gerenciador de tags.

- Se o [script de formulários](/pt/docs/forms/install/) do Emailit também estiver na página, mantenha os dois. Eles compartilham `window.emailit`.
- Se o seu site usa uma Content Security Policy, permita `https://js.emailit.com` em `script-src` e `connect-src`.

## Rastrear eventos

```javascript
// Custom event: any name after "c:", any properties
emailit("track", "c:product.viewed", { sku: "TS-42", price: 19.9 });

// Workspace event: checked against its definition
emailit("track", "w:customer.type", { segment: "b2b" });
```

O tipo precisa começar com `c:` ou `w:`; o script ignora as outras chamadas. Propriedades que não são um objeto são enviadas como `{}`. Para eventos que aconteceram antes, você pode passar um terceiro argumento com `occurred_at`, uma data e hora ISO 8601.

O script não registra visualizações de página por conta própria. Rastreie as páginas e ações que importam para você, por exemplo, um evento `c:page.viewed` a cada mudança de rota de uma single-page app.

### Comandos de loja

Para lojas virtuais, o script também tem os comandos `product`, `cart`, `purchase` e `page`. Eles registram visualizações de produtos, carrinhos e pedidos para o [e-commerce](/pt/docs/commerce/) e os enviam ao log de eventos como os eventos do sistema `product.viewed`, `cart.updated` e `order.placed`. O e-commerce está em alfa e aberto apenas à equipe do Emailit; nos demais workspaces, esses comandos são rejeitados. Consulte [Conectar a sua loja](/pt/docs/commerce/connect-your-shop/#record-shop-activity).

## Identificar visitantes

Assim que souber quem é o visitante, por exemplo, depois que ele fizer login ou se inscrever, informe o script:

```javascript
emailit("identify", { email: "jane@example.com" });
// or, if you store Emailit contact IDs:
emailit("identify", { contact_id: "con_2wPq7Lm3XcN8bV1zKd4RtY6sHf9" });
```

Todos os eventos seguintes trazem esse e-mail ou ID de contato, nesta página e nas próximas visitas, para que o Emailit possa vinculá-los ao contato. Quando o visitante sair da conta, esqueça-o:

```javascript
emailit("reset");
```

`reset` também inicia um novo ID anônimo de visitante, para que a próxima pessoa em um computador compartilhado não seja confundida com a anterior.

Os eventos com um e-mail que nenhum contato tem são mantidos e aparecem no contato assim que ele existir. Um `contact_id` que não corresponde a nenhum contato é removido do evento, sem erro, para que uma chave pública não possa ser usada para testar quais IDs de contato existem.

Qualquer pessoa com a sua chave de rastreamento pode chamar `identify` com qualquer endereço, então o Emailit não deixa os eventos do script acionarem automações. Eles são registrados, aparecem no contato e chegam aos webhooks, mas não iniciam, não encerram nem fazem avançar [execuções de automações](/pt/docs/automations/triggers/#custom-event). Envie do seu servidor, com a [API de eventos](/pt/docs/events/send-events/), os eventos que devem fazer isso. Cada evento do script que indica um contato tem `identity_verified`: ele só é `true` quando um link assinado em um dos seus e-mails identificou o visitante, o que faz parte da fase alfa do [e-commerce](/pt/docs/commerce/connect-your-shop/#identify-visitors), e esses eventos acionam automações.

## O que o script envia

Além do tipo e das propriedades que você passa, cada evento traz:

| Campo | Conteúdo |
| --- | --- |
| `anonymous_id` | Um ID aleatório de visitante (`anon_…`), guardado no armazenamento local do navegador. |
| `email`, `contact_id` | O que você passou para `identify`, se houver. |
| `context.page` | `url`, `path`, `title` e `referrer` da página. |
| `context.campaign` | Os parâmetros UTM da página (`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`), como `source`, `medium`, `name`, `term` e `content`. |
| `context.locale`, `context.timezone` | O idioma e o fuso horário do navegador. |

O Emailit adiciona `identity_verified` aos eventos que indicam um contato (consulte [Identificar visitantes](#identify-visitors)) e armazena o user agent do navegador. Ele não armazena endereços IP, e o script não define cookies. O script guarda o ID do visitante em `emailit:aid` e a identidade em `emailit:identity` no armazenamento local; se o armazenamento local estiver bloqueado, eles duram só enquanto a página estiver aberta.

Os eventos são reunidos por um instante e enviados juntos, no máximo 20 de cada vez. Quando o visitante sai da página, os restantes são enviados com `sendBeacon`.

Se o seu site precisa de consentimento para análises, carregue o script só depois que o visitante concordar.

## Sites permitidos

`allowed_origins` limita quais sites podem enviar eventos com uma chave. Cada entrada é uma destas:

| Entrada | Corresponde a |
| --- | --- |
| `https://shop.example.com` | Exatamente essa origem: esquema, host e porta. |
| `shop.example.com` | Esse host em qualquer esquema ou porta. |
| `*.example.com` | `example.com` e todos os subdomínios. |

Uma lista vazia aceita qualquer site. O Emailit verifica o cabeçalho `Origin` que os navegadores enviam em toda requisição, então outros sites não conseguem enviar eventos com a sua chave. Um script fora de um navegador, porém, pode definir qualquer cabeçalho, então trate os eventos do navegador como entrada não confiável e envie pedidos e pagamentos [do seu backend](/pt/docs/events/send-events/).

## Eventos inválidos

Ao contrário da API, o endpoint do script armazena os eventos válidos de uma requisição mesmo quando outros são inválidos. Os eventos inválidos são descartados, por exemplo, um evento `w:` com uma propriedade do tipo errado, ou um evento de um tipo novo quando o workspace já usa o número de [tipos de evento](/pt/docs/events/#limits) do plano. Use a [depuração](#debug) para ver o motivo.

## Depuração

Ative o log no console do navegador de uma destas formas:

- Chame `emailit("debug", true)`.
- Adicione `data-debug` à tag do script.
- Abra a página com `?emailit_debug=1` na URL.

O console passa a mostrar cada evento e a resposta do Emailit, incluindo os motivos dos eventos rejeitados.

## Solução de problemas

| Resposta no console | Causa | Solução |
| --- | --- | --- |
| `403` `Origin not allowed for this tracking key` | O site da página não está em **Allowed origins**. | Adicione-o, por exemplo, `https://example.com` e também `https://www.example.com`, ou use `*.example.com`. |
| `403` `This tracking key is disabled` | A chave está desativada. | Ative-a na aba **Tracking**. |
| `403` `Website tracking is included with Pro and Business.` | O workspace está no Pay as you go. | Faça upgrade para o Pro ou o Business. |
| `404` `Unknown tracking key` | A chave na URL do script foi excluída ou digitada errado. | Copie o snippet de novo da aba **Tracking**. |
| `422` com todos os eventos em `rejected` | Nenhum dos eventos era válido. | Confira os motivos em `rejected`. |
| `429` | A chave enviou eventos demais em pouco tempo. | Envie menos eventos por visitante, por exemplo, nenhum evento por rolagem ou movimento do mouse. |
| Nada | Um bloqueador de anúncios ou de rastreamento impediu o script, ou ele não está na página. | Teste em um navegador sem bloqueadores e confira se o snippet está na página. |

## Veja também

  - [Rastreamento de eventos](/pt/docs/events/): Escopos, nomes e para onde vão os eventos.
  - [Eventos do workspace](/pt/docs/events/workspace-events/): Defina eventos e as propriedades deles.
  - [API de chaves de rastreamento](/pt/docs/api-reference/tracking-keys/): Crie, atualize e exclua chaves.
  - [Enviar eventos do seu backend](/pt/docs/events/send-events/): Para pedidos e pagamentos.

---
Fonte: https://emailit.com/pt/docs/events/tracking-script/