Conceito
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 | Uma chave de rastreamento pública, limitada aos seus sites |
| Os seus servidores | Enviar um evento ou Enviar eventos em lote | Uma chave de API com Full Access ou Events Only. Consulte Enviar eventos do seu backend. |
| O painel | Send event em Email APIEvents | 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_idprecisa 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 APIEvents 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
scopede Listar eventos. - Webhooks. Inscreva um webhook em um tipo como
c:order.completed, ou em todos os eventos do workspace ou personalizados comw:*ec:*. Um webhook com All events ativado não os recebe, a menos que você também os escolha. Consulte Tipos de evento. - Contatos. Consulte Eventos e contatos.
- Automações. Um gatilho 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 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 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.
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. 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.completedew: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 com422. - 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.