Pular para o conteúdo principal

​
O que são Eventos Personalizados?

Um Evento Personalizado é uma ação (ou inação) nomeada do usuário que você envia para o OneSignal. Você envia eventos do seu aplicativo, site ou sistemas externos para poder acionar automações, controlar o fluxo de Jornadas e personalizar experiências do usuário em tempo real. Exemplos incluem:
  • Completou o onboarding
  • Realizou uma compra
  • Abandonou um carrinho
  • Cancelou uma assinatura
  • Alcançou um novo nível no jogo
Quando o OneSignal recebe um Evento Personalizado, você pode:
  • Iniciar uma Jornada
  • Continuar uma Jornada com uma etapa Wait Until
  • Remover usuários de uma Jornada
  • Personalizar mensagens usando propriedades do evento
  • Segmentar usuários por comportamento (Acesso Antecipado)

​
Quando você deve usar Eventos Personalizados?

Use Eventos Personalizados quando:
  • As mensagens devem responder ao comportamento do usuário em tempo real
  • Os dados representam algo que aconteceu (não um estado permanente)
  • Você precisa de propriedades do evento para personalização ou lógica de Jornada
Não use Eventos Personalizados quando:
  • Você deseja armazenar atributos de longo prazo do usuário (use Tags em vez disso)
Eventos Personalizados representam algo que aconteceu em um momento específico. Diferente das Tags, eles não atualizam permanentemente o perfil do usuário — eles registram comportamento.Veja Tags vs Eventos Personalizados abaixo para uma comparação detalhada.

​
Estrutura do Evento Personalizado

Eventos Personalizados incluem os seguintes campos:
​
name
string
obrigatório
O nome do evento. Máximo de 128 caracteres.
​
properties
object
Parâmetros opcionais que descrevem o evento (por exemplo: nome do plano, ID do produto ou preço). Esses podem ser usados para personalização e controle de fluxo da Jornada.
​
external_id
string
O ID Externo do usuário. Um identificador de usuário é obrigatório ao usar a API Create Custom Events. Deve ser fornecido external_id ou onesignal_id.
​
timestamp
string
O horário em que o evento ocorreu (ou ocorrerá), formatado como uma string ISO 8601. Veja API Create Custom Events.
​
idempotency_key
string
Um UUID único usado para evitar o processamento duplicado de eventos. Veja API Create Custom Events.
Limites de tamanho do evento:
  • Payload máximo do evento: 2024 bytes
  • Tamanho máximo da requisição (múltiplos eventos): 1 MB

​
Enviar Eventos Personalizados para o OneSignal

Envie Eventos Personalizados usando os seguintes métodos:
Todos os eventos são tratados da mesma forma para fins de faturamento, independentemente da origem.
Exemplo de payload de Evento Personalizado:
JSON
{
  "events": [
    {
      "name": "purchase",
      "properties": {
        "item": "T-shirt",
        "size": "small",
        "color": "blue",
        "price": 24.99
      },
      "external_id": "user_12345",
      "timestamp": "2025-10-21T19:09:32.263Z",
      "idempotency_key": "123e4567-e89b-12d3-a456-426614174000"
    }
  ]
}

​
Verificar se os eventos foram recebidos

Após enviar eventos, confirme que eles estão chegando ao OneSignal em Data > Custom Events.

​
Aba Event List

A aba Event List fornece uma visão geral de todos os Eventos Personalizados no seu aplicativo, organizados por nome de evento. Para cada tipo de evento, você pode ver:
  • Total de eventos ingeridos
  • Evento mais recente (com payload JSON completo e propriedades)
  • Origem do evento (SDK, API ou integração)
  • Timestamp da última ocorrência
Selecione um evento para abrir sua visualização detalhada, onde você também pode atualizar seu período de retenção. A visualização detalhada inclui:
  • Detalhamento por Origem: Número de eventos ingeridos por origem. Expanda para visualizar o esquema mais recente do evento e o timestamp do evento mais recente.
  • Atividades: Os 10 eventos mais recentes, incluindo origem e timestamp. Expanda qualquer entrada para inspecionar o payload JSON completo.
  • Uso: Onde o evento está sendo usado atualmente (Jornadas ou segmentos). Clique diretamente na Jornada ou segmento associado para modificar suas configurações.

​
Aba Event Activity

A aba Event Activity fornece um feed ao vivo dos eventos mais recentes ingeridos no seu aplicativo OneSignal. Use-a para:
  • Filtrar por nome do evento, origem ou ID externo
  • Inspecionar payloads JSON completos
  • Depurar problemas de integração
O feed não atualiza automaticamente. Atualize manualmente após enviar novos eventos.

​
Usar Eventos Personalizados no OneSignal

Depois que os eventos estiverem fluindo para o OneSignal, você pode usá-los das seguintes maneiras:

​
Acionar regras de entrada e saída de Jornadas

Defina um Evento Personalizado como regra de entrada ou saída de uma Jornada para adicionar ou remover usuários imediatamente quando o evento ocorrer. Exemplo:
  • signup_completed → Iniciar onboarding ou remover de uma Jornada de incentivo ao trial
  • purchase → Enviar confirmação e cross-sell ou remover da Jornada de carrinho abandonado

Configurações de Jornada

Adicione usuários a Jornadas com Eventos Personalizados.

​
Controlar o fluxo da Jornada (Wait Until)

Use uma etapa Wait Until para manter usuários até que um Evento Personalizado ocorra. Exemplo:
  • Aguardar até purchase após added_to_cart
Você pode definir uma janela de expiração. Se o usuário não acionar o evento a tempo, você pode enviar uma mensagem alternativa ou sair da Jornada.

Etapa Wait Until da Jornada

Mantenha usuários até que um Evento Personalizado ocorra.

​
Personalizar Jornadas com propriedades do evento

Referencie propriedades do evento usando Liquid nos seus templates de Jornada. Exemplo:
Liquid
Thanks for purchasing {{ journey.first_event.properties.item }}!

Personalização com Eventos Personalizados

Guia completo para usar propriedades de eventos na personalização de Jornadas.

​
Segmentar usuários com Eventos Personalizados

Crie um segmento baseado na ocorrência de um Evento Personalizado.
Segmentação por Eventos Personalizados está em Acesso Antecipado.Para solicitar acesso, envie um e-mail para support@onesignal.com com:
  • O nome da sua empresa
  • Seu(s) App ID(s) do OneSignal
Limitações atuais:
  • Não é compatível com Email Warm Up ou testes A/B
  • Não pode acionar Jornadas
  • Não pode ser combinado com outros filtros de segmento

Segmentação

Guia completo de segmentação.

​
Disponibilidade do plano e custos de retenção

Eventos Personalizados estão disponíveis em todos os planos pagos.

FAQ de Faturamento

Saiba mais sobre retenção de eventos e preços.

​
Tags vs Eventos Personalizados

Tags e Custom Events são ambas formas de adicionar dados aos seus usuários. No entanto, existem algumas diferenças principais:
RecursoTagsCustom Events
Uso de dadosSegmentação e personalizaçãoDisparar Jornadas sem um Segmento, passos Wait Until, personalização diretamente dentro de Jornadas
Retenção de dadosVitalícia30+ dias (armazenamento vitalício está disponível)
Formato de dadosStrings ou números chave-valorJSON
Fonte de dadosOneSignal SDK, API ou integrações (limitado)OneSignal SDK, API ou integrações
Acesso aos dadosSegmentação e personalização de mensagemJornadas e personalização de Journey-message-template, Segmentação (Em breve)
A principal distinção entre Tags e Custom Events está em sua profundidade e casos de uso. Tags são propriedades de um usuário, como Nome, Status de Conta ou Localização. Eventos são coisas que o usuário fez, como Comprar um Item, Completar um Nível ou Convidar um Amigo. Tanto tags quanto eventos podem ser usados para segmentação e personalização. Na prática, você provavelmente usará ambos:
  • Tags para propriedades de usuário que são estáticas e não mudam frequentemente
  • Custom Events para cenários em tempo real, segmentação complexa e fluxos de trabalho de jornada mais sofisticados