Pular para o conteúdo principal

​
Visão geral

Eventos Personalizados permitem que você rastreie ações significativas do usuário do seu aplicativo, site ou sistemas externos — e aja sobre elas em tempo real. Envie eventos de usuário para comportamentos que acontecem fora do OneSignal e use-os para entregar mensagens mais direcionadas, relevantes e oportunas. Você pode:
  • Enviar eventos diretamente do seu aplicativo ou site usando os SDKs do OneSignal
  • Importar eventos de suas integrações, CDP ou data warehouse
  • Usá-los para acionar Jornadas, ativar etapas Wait Until e segmentar usuários com base em comportamento em tempo real (opção de segmentação em breve)
Exemplos de casos de uso:
  • Usuário se inscreve → Iniciar Jornada de onboarding
  • Usuário abandona checkout → Enviar lembrete ou oferta
  • Jogador alcança novo nível → Enviar recompensa in-app
  • Usuário tenta cancelar conta → Acionar campanha de reativação

​
O que é um Evento Personalizado?

Um Evento Personalizado é qualquer ação de usuário rastreada — ou inação — que importa para o seu negócio. Exemplos comuns incluem:
  • Fazer uma compra
  • Completar um nível de jogo
  • Iniciar um treino
  • Cancelar uma assinatura
Cada evento pode incluir propriedades para fornecer contexto extra. Estrutura do Evento Personalizado:
  • name (string, obrigatório) — Nome do evento, máximo 128 caracteres
  • properties (objeto, opcional) — Dados de contexto em JSON
  • Identificador de usuário (obrigatório) — Ou external_id ou onesignal_id
Exemplo: 
{
  "events": [
    {
      "external_id": "user_12345",
      "timestamp": "2025-10-21T19:09:32.263Z",
      "name": "purchase",
      "properties": {
        "item": "T-shirt",
        "size": "small",
        "color": "blue",
        "price": 24.99
      }
    }
  ]
}
Eventos Personalizados podem ser:
  • Produzidos em tempo real do seu aplicativo ou site (SDKs móvel/web do OneSignal)
  • Ingeridos de integrações como Segment, Amplitude ou Databricks (em breve)
  • Importados do seu warehouse ou CDP (em breve)

​
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

​
Obtendo Eventos Personalizados no OneSignal

Você pode gerar eventos diretamente com nossas APIs ou ingeri-los de outros sistemas.
Todos os eventos — sejam gerados de um SDK ou ingeridos de um Data Warehouse — são tratados da mesma forma para fins de faturamento.

​
API e SDKs do OneSignal

Envie eventos via: Exemplo: Enviar via API
curl
curl --request POST \
  --url https://api.onesignal.com/apps/{app_id}/custom_events \
  --header 'Content-Type: application/json' \
  --data '{
  "events": [
    {
      "name": "completed_onboarding",
      "external_id": "user_12345",
      "properties": {
        "plan": "Pro",
        "time_to_complete": 600
      }
    }
  ]
}'
​
name
string
required
O identificador ou nome do evento. Máximo 128 caracteres.
​
external_id
string
O ID externo do usuário alvo do evento. O ID Externo do usuário ou o ID do OneSignal é obrigatório.
​
properties
object
Parâmetros opcionais sobre o evento (por exemplo, nome do plano, ID do produto, preço).
Este evento adicionará imediatamente o usuário com external_id user_12345 a uma Jornada com completed_onboarding como o acionador de regra de entrada de evento personalizado ou ação wait until.

​
Integrações

Se os eventos já estão sendo rastreados em outro lugar, importe-os via integrações suportadas.

​
Visualizando e verificando eventos

Depois que os eventos começarem a fluir, você pode visualizá-los e solucioná-los através de várias ferramentas no OneSignal.

​
Aba Event List

Navegar para sua Organização

A aba Event List fornece um painel de alto nível dos seus eventos, organizados por tipo de evento. Para cada tipo de evento, você pode ver o número total de eventos ingeridos, o evento ingerido mais recentemente (exibido em formato JSON com suas propriedades), a origem do evento (SDK, API ou integração) e a última vez que o tipo de evento ocorreu. Dentro da visualização de detalhes de cada evento, você também tem a opção de atualizar seu período de retenção. A visualização de sub-detalhes oferece insights adicionais em três áreas principais:
  • Source Breakdown – Exibe o número de eventos ingeridos por origem, com a opção de expandir e visualizar o esquema mais recente dos eventos junto com o timestamp do último evento visto.
  • Activities – Lista os 10 eventos mais recentes ingeridos, mostrando sua origem e timestamp. Cada entrada pode ser expandida para revelar o payload JSON completo do evento.
  • Usage – Mostra onde um evento específico está sendo usado dentro do OneSignal, como em segmentos ou jornadas. A partir daqui, você pode clicar diretamente no segmento ou jornada relevante para acessar suas configurações.

​
Aba Event Activity

Navegar para sua Organização

A aba Event Activity fornece um feed ao vivo dos eventos mais recentes ingeridos no seu aplicativo OneSignal. Você pode expandir o feed para revisar eventos de até 90 dias atrás e aplicar filtros por origem, propriedades do evento ou ID externo. Esta aba é especialmente útil para depurar problemas ao configurar origens de eventos, pois permite validar se os eventos estão chegando ao seu aplicativo conforme esperado. Observe que o feed não atualiza automaticamente, então você precisará atualizá-lo manualmente após enviar novos eventos para ver a atividade mais recente.

​
Aba Event Storage (Em breve)

Uma visualização dedicada para gerenciar o armazenamento dos eventos para seu Aplicativo OneSignal.

​
Usando Eventos Personalizados no OneSignal

​
Acionar Jornadas com eventos

Jornadas acionadas por eventos permitem que você envie mensagens imediatamente aos usuários com base em atividade em tempo real—sem necessidade de esperar por atualizações de segmento. Você pode iniciar uma Jornada no momento em que um usuário realizar uma ação chave.

​
Wait Until event

Use a etapa Wait Until para pausar usuários em uma Jornada até um evento personalizado específico ou outra ação.
Você também pode definir uma janela de expiração. Se o usuário não atender à condição a tempo, você pode continuar por um caminho alternativo, enviar uma mensagem alternativa ou sair da Jornada.

​
Segmentação por Eventos Personalizados

Segmentação com Eventos Personalizados está atualmente em Acesso Antecipado. Para solicitar acesso, entre em contato com support@onesignal.com com:
  • O nome da sua empresa
  • Seu(s) App ID(s) do OneSignal que você deseja habilitar
Você pode criar um segmento baseado na ocorrência de um evento personalizado. Isso permitirá que você segmente usuários com base no comportamento no seu Aplicativo usando o SDK do OneSignal ou de eventos capturados fora do OneSignal. Mais detalhes sobre Segmentação de Eventos Personalizados estão disponíveis na página de Segmentação. Limitações deste recurso enquanto está em Acesso Antecipado:
  • Não pode ser usado com Email Warm Up e testes A/B.
  • Segmentos de eventos personalizados não podem ser usados para potencializar Jornadas.
  • Você ainda não pode combinar filtros de eventos personalizados com outros filtros de segmentação (como propriedades do usuário ou eventos de mensagem).

​
Disponibilidade do plano e custos de retenção

Eventos Personalizados estão disponíveis em todos os planos pagos. Por favor, veja o FAQ de Faturamento para mais detalhes.