# Rastreamento de eventos

> Registre o que as pessoas fazem na sua aplicação e no seu site como eventos do workspace ou personalizados, vincule-os a contatos e receba-os em webhooks.

O rastreamento de eventos permite registrar o que as pessoas fazem no seu próprio produto: um pedido, uma mudança de plano, um cadastro, a visualização de um produto. Você envia os eventos do seu site com o script de rastreamento ou dos seus servidores com a API. O Emailit os armazena junto com os eventos que ele mesmo registra, vincula-os a contatos e pode enviá-los aos seus webhooks.

O rastreamento de eventos está incluído nos planos Pro, Business e Custom. No Pay as you go, enviar eventos e definir eventos do workspace retornam `403` com `"error": "plan_required"`, e as requisições do script de rastreamento são recusadas.

## Três escopos de eventos

Todo evento tem um tipo, e o prefixo do tipo indica o **escopo** dele:

| Escopo | Tipo | Quem o define | Exemplo |
| --- | --- | --- | --- |
| Sistema | `<name>` | O Emailit. Esses eventos registram o que acontece com os seus e-mails, contatos e outros recursos. Você não pode enviá-los. | `email.delivered` |
| Workspace | `w:<name>` | O seu workspace. Primeiro você declara o evento e o tipo de cada propriedade, e o Emailit rejeita os eventos que não correspondem à declaração. | `w:customer.type` |
| Personalizado | `c:<name>` | Ninguém. Qualquer nome, com qualquer objeto JSON como propriedades. | `c:order.completed` |

Use um **evento do workspace** quando vários sistemas enviarem o mesmo evento e você quiser que eles continuem consistentes, ou quando pessoas da sua equipe dependerem dos campos dele. Use um **evento personalizado** quando quiser manter a sua própria estrutura de dados, por exemplo, o formato de pedido da sua loja, sem declará-la antes. Você pode começar com um evento personalizado e defini-lo como evento do workspace depois; os dois são tipos separados, então `c:order.completed` e `w:order.completed` não se misturam.

## Nomes de eventos

Os nomes têm de 1 a 100 letras, dígitos, pontos, hifens ou sublinhados e começam com uma letra ou um dígito: `customer.type`, `order-completed`, `cart_updated`. Os nomes diferenciam maiúsculas de minúsculas.

Os nomes de propriedades dos eventos do workspace seguem as mesmas regras, sem pontos, porque os filtros de webhook e os templates usam pontos para acessar valores aninhados.

## Formas de enviar eventos

| De onde | Como | Credenciais |
| --- | --- | --- |
| O seu site | O [script de rastreamento](/pt/docs/events/tracking-script/) | Uma chave de rastreamento pública, limitada aos seus sites |
| Os seus servidores | [Enviar um evento](/pt/docs/api-reference/events/send/) ou [Enviar eventos em lote](/pt/docs/api-reference/events/batch/) | Uma chave de API com **Full Access** ou **Events Only**. Consulte [Enviar eventos do seu backend](/pt/docs/events/send-events/). |
| O painel | **Send event** em **Email API → Events** | O seu login. Feito para testar um webhook ou uma integração. |

É melhor enviar dos seus servidores os eventos que envolvem dinheiro, como pedidos e pagamentos. Os eventos do navegador podem ser bloqueados, e qualquer pessoa pode enviar eventos com uma chave pública.

## Eventos e contatos

Um evento pode indicar a pessoa a que se refere, por `email` ou por `contact_id`.

- Os contatos são procurados, nunca criados. Se nenhum contato tiver o e-mail, o endereço é armazenado mesmo assim, e o evento aparece na atividade do contato assim que você o criar.
- Um `contact_id` precisa pertencer a um contato do workspace.
- Os eventos sem uma pessoa podem trazer um `anonymous_id`. O script de rastreamento adiciona um a cada evento que envia.

Os eventos vinculados a um contato aparecem no **Activity log** do contato, junto com os e-mails que ele recebeu. Os eventos do workspace que têm um título mostram esse título ali.

## Para onde vão os eventos

- **O log de eventos.** **Email API → Events** lista todos os eventos na aba **Log**. Filtre por **Scope** para ver só eventos do sistema, do workspace ou personalizados. Pela API, use o parâmetro `scope` de [Listar eventos](/pt/docs/api-reference/events/list/).
- **Webhooks.** Inscreva um webhook em um tipo como `c:order.completed`, ou em todos os eventos do workspace ou personalizados com `w:*` e `c:*`. Um webhook com **All events** ativado não os recebe, a menos que você também os escolha. Consulte [Tipos de evento](/pt/docs/webhooks/event-types/#workspace-and-custom-events).
- **Contatos.** Consulte [Eventos e contatos](#events-and-contacts).
- **Automações.** Um [gatilho](/pt/docs/automations/triggers/#custom-event) **Custom event** inicia uma execução para o contato do evento, opcionalmente apenas quando as propriedades dele correspondem. Os mesmos eventos podem encerrar execuções, atingir metas e retomar etapas **Wait until**. Só os eventos que você envia do seu servidor com a [API de eventos](/pt/docs/events/send-events/) fazem isso: qualquer pessoa com a sua chave de rastreamento pública pode atribuir uma identidade a um visitante, então os eventos do [script de rastreamento](/pt/docs/events/tracking-script/#identify-visitors) são registrados e chegam aos webhooks, mas não iniciam, não encerram nem fazem avançar execuções. O gatilho **Custom event** está incluído nos planos Business e Custom, e as condições de saída, metas e esperas com esses eventos, nos planos Pro, Business e Custom. Consulte [Condições de saída e metas](/pt/docs/automations/exits-and-goals/).

## Retenção

Os eventos fazem parte dos **Logs** do seu workspace, então são guardados pelo período de retenção de logs do seu plano e depois excluídos. Consulte [Retenção de dados](/pt/docs/data-retention/). Guarde nos seus próprios sistemas os pedidos e outros registros de que você precisa por mais tempo.

## Limites

| | Pay as you go | Pro | Business | Custom |
| --- | --- | --- | --- | --- |
| Tipos de eventos do workspace e personalizados | — | 100 | 1.000 | Ilimitados |
| Script de rastreamento do site | — | Incluído | Incluído | Incluído |

- **Tipos de evento** são os tipos distintos de eventos do workspace e personalizados que um workspace envia, como `c:order.completed` e `w:customer.type`. Os tipos que ele já enviou continuam funcionando. Quando ele chega ao número de tipos do plano, os eventos de um tipo novo são rejeitados com `422`.
- Eventos do workspace: tantos quanto os tipos de evento do plano, cada um com até 50 propriedades.
- Propriedades de eventos personalizados com até 32 KB de JSON e até 8 níveis de aninhamento.
- Até 100 eventos por requisição em lote.
- 25 chaves de rastreamento por workspace.

Mais em [Limites](/pt/docs/limits/#other-limits).

## Veja também

  - [Eventos do workspace](/pt/docs/events/workspace-events/): Defina eventos e os tipos das propriedades deles.
  - [Enviar eventos do seu backend](/pt/docs/events/send-events/): Registre eventos com a API.
  - [Script de rastreamento](/pt/docs/events/tracking-script/): Envie eventos do seu site.
  - [API de eventos](/pt/docs/api-reference/events/): Envie, liste e obtenha eventos.

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