Visão geral
Os eventos personalizados registram ações dos usuários vindas de sistemas externos (e-commerce, CRM, ferramentas de análise). Eles aparecem na linha do tempo do contato, e as metas deles permitem criar segmentos RFM (Recência, Frequência, Valor monetário).
Linha do tempo do contato
Todo evento personalizado cria uma entrada na linha do tempo do contato, então você vê o histórico completo das interações de um contato:
Cada evento mostra o seu event_name como o tipo da entrada na linha do tempo (por exemplo, “order.completed”, “subscription.started”). O campo properties guarda o contexto adicional, visível nos detalhes da linha do tempo.
Tipos de meta
Os segmentos são criados a partir de metas. Cada evento pode acompanhar uma meta:
| Tipo | Caso de uso | goal_value |
|---|---|---|
purchase | Pedidos de e-commerce, pagamentos únicos | Obrigatório |
subscription | Assinaturas de SaaS, planos de associação | Obrigatório |
lead | Formulários de contato, pedidos de demonstração | Opcional |
signup | Cadastros de conta | Opcional |
booking | Agendamentos, consultas | Opcional |
trial | Ativações de teste gratuito | Opcional |
other | Eventos de conversão personalizados | Opcional |
Criar segmentos RFM
A análise RFM (Recência, Frequência, Valor monetário) encontra os seus melhores clientes. Use o criador de segmentos com condições de Meta:
Valor monetário: gasto total
Escolha o tipo de meta Compra e a agregação total, depois defina um valor mínimo para encontrar os clientes que mais gastam.
Frequência: número de compras
Escolha o tipo de meta Compra e a agregação contagem, depois defina um número mínimo para encontrar os clientes que compram de novo.
Recência: atividade recente
Use o filtro de período “nos últimos X dias” para encontrar os clientes com compras recentes.
Exemplos de segmentos RFM
- Clientes VIP: gastaram US$ 1000 ou mais E fizeram 5 pedidos ou mais E compraram nos últimos 60 dias
- Alto valor em risco: gastaram US$ 500 ou mais E não compram há 90 dias
- Novos com alto potencial: primeira compra acima de US$ 200 nos últimos 30 dias
Opções de agregação
| Opção | Descrição |
|---|---|
| Total | Soma de todos os valores da meta (gasto ao longo do tempo) |
| Contagem | Número de eventos (número de pedidos) |
| Média | Valor médio da meta (ticket médio) |
| Mínimo | Menor valor da meta |
| Máximo | Maior valor da meta |
Opções de período
| Opção | Descrição |
|---|---|
| A qualquer momento | Todo o histórico |
| Nos últimos X dias | Janela móvel |
| No intervalo de datas | Período específico |
| Antes da data | Corte no histórico |
| Depois da data | A partir de uma data específica |
Registrar eventos
Evento único
curl -X POST "https://your-instance.com/api/customEvents.upsert" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workspace_id": "your_workspace",
"email": "customer@example.com",
"event_name": "order.completed",
"external_id": "order_12345",
"properties": {
"items": ["Product A", "Product B"],
"currency": "USD"
},
"goal_type": "purchase",
"goal_value": 149.99
}'
Importação em lote
Importe até 50 eventos de uma vez:
curl -X POST "https://your-instance.com/api/customEvents.import" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workspace_id": "your_workspace",
"events": [
{
"email": "user1@example.com",
"event_name": "order.completed",
"external_id": "order_001",
"goal_type": "purchase",
"goal_value": 99.99
},
{
"email": "user2@example.com",
"event_name": "order.completed",
"external_id": "order_002",
"goal_type": "purchase",
"goal_value": 249.99
}
]
}'
Formato do nome do evento
Os nomes de eventos precisam estar em minúsculas e usar letras, números, pontos, sublinhados, hífens ou barras:
order.completedsubscription/startedform_submituser-signup
Nota
As metas registradas pela Web Analytics chegam à linha do tempo do contato por uma regra mais restrita: só letras ASCII, números, pontos e barras, e todo o resto (incluindo hífens e caracteres acentuados) é substituído por um sublinhado. Uma meta web chamada user-signup chega como user_signup. Se você envia o mesmo evento pelos dois caminhos, escolha um nome que passe pelos dois.
Reembolsos
Use um goal_value negativo para os reembolsos, assim os cálculos de LTV continuam corretos:
{
"email": "customer@example.com",
"event_name": "order.refunded",
"external_id": "refund_12345",
"goal_type": "purchase",
"goal_value": -50.00
}
Permissões
Os eventos personalizados não têm uma permissão própria: eles dependem de Contatos. Registrar ou importar um evento exige escrita de Contatos, e ler um evento exige leitura de Contatos. Conceder leitura de Contatos, portanto, também dá acesso aos eventos registrados nos seus contatos e à linha do tempo que eles alimentam. Veja Administradores e chaves API.
Observações
customEvents.upsertcria o contato quando nenhum contato tem aquele email.customEvents.importnão cria contatos- Os eventos só são atualizados se
occurred_atfor mais recente que o existente - Exclusão lógica definindo
deleted_at(defina comonullpara restaurar) - Só um evento novo (um novo
external_id) inicia as automações acionadas pelo nome dele; desde a versão 44.0, uma atualização, uma exclusão lógica ou uma restauração não iniciam - Veja a Referência da API para a documentação completa dos endpoints
