Pular para o conteúdo

Recursos

Eventos personalizados e metas

Acompanhe o comportamento dos usuários e as metas de conversão para criar segmentos RFM e enriquecer a linha do tempo dos contatos.

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:

Linha do tempo do contato com eventos personalizados

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:

TipoCaso de usogoal_value
purchasePedidos de e-commerce, pagamentos únicosObrigatório
subscriptionAssinaturas de SaaS, planos de associaçãoObrigatório
leadFormulários de contato, pedidos de demonstraçãoOpcional
signupCadastros de contaOpcional
bookingAgendamentos, consultasOpcional
trialAtivações de teste gratuitoOpcional
otherEventos de conversão personalizadosOpcional

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:

Criador de segmentos com uma meta de eventos personalizados

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çãoDescrição
TotalSoma de todos os valores da meta (gasto ao longo do tempo)
ContagemNúmero de eventos (número de pedidos)
MédiaValor médio da meta (ticket médio)
MínimoMenor valor da meta
MáximoMaior valor da meta

Opções de período

OpçãoDescrição
A qualquer momentoTodo o histórico
Nos últimos X diasJanela móvel
No intervalo de datasPeríodo específico
Antes da dataCorte no histórico
Depois da dataA 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.completed
  • subscription/started
  • form_submit
  • user-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.upsert cria o contato quando nenhum contato tem aquele email. customEvents.import não cria contatos
  • Os eventos só são atualizados se occurred_at for mais recente que o existente
  • Exclusão lógica definindo deleted_at (defina como null para 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