> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Eventos personalizados

> Rastreie o comportamento do usuário com Eventos Personalizados e use-os para acionar Jornadas, controlar o fluxo com etapas Wait Until e personalizar mensagens em tempo real.

## 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)

<Warning>
  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](#tags-vs-custom-events) abaixo para uma comparação detalhada.
</Warning>

### Estrutura do Evento Personalizado

Eventos Personalizados incluem os seguintes campos:

<ParamField body="name" type="string" required>
  O nome do evento. Máximo de `128` caracteres.
</ParamField>

<ParamField body="properties" type="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.
</ParamField>

<ParamField body="external_id" type="string">
  O ID Externo do usuário. Um identificador de usuário é obrigatório ao usar a [API Create Custom Events](/reference/create-custom-events). Deve ser fornecido `external_id` ou `onesignal_id`.
</ParamField>

<ParamField body="timestamp" type="string">
  O horário em que o evento ocorreu (ou ocorrerá), formatado como uma string ISO 8601. Veja [API Create Custom Events](/reference/create-custom-events).
</ParamField>

<ParamField body="idempotency_key" type="string">
  Um UUID único usado para evitar o processamento duplicado de eventos. Veja [API Create Custom Events](/reference/create-custom-events).
</ParamField>

<Warning>
  Limites de tamanho do evento:

  * Payload máximo do evento: 2024 bytes
  * Tamanho máximo da requisição (múltiplos eventos): 1 MB
</Warning>

***

## Enviar Eventos Personalizados para o OneSignal

<Info>
  Todos os eventos são tratados da mesma forma para fins de faturamento, independentemente da origem.
</Info>

### API e SDKs

<Columns cols={2}>
  <Card title="Create Custom Events API" icon="server" href="/reference/create-custom-events">
    Envie eventos a partir do seu backend.
  </Card>

  <Card title="Mobile/Web SDKs" icon="mobile" href="./mobile-sdk-reference#custom-events">
    Rastreie eventos no lado do cliente.
  </Card>
</Columns>

Exemplo de payload de Evento Personalizado:

```json JSON theme={null}
{
  "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"
    }
  ]
}
```

### Integrações

O OneSignal conecta-se a mais de 25 fontes de dados externas para importar eventos personalizados — incluindo data warehouses, bancos de dados e plataformas de streaming — sem necessidade de código personalizado.

<Columns cols={3}>
  <Card title="Twilio Segment" icon="share-nodes" href="./segment-onesignal-integration">
    Roteie eventos e públicos entre Segment e OneSignal.
  </Card>

  <Card title="Amplitude" icon="chart-line" href="./amplitude">
    Sincronize coortes e importe eventos personalizados do Amplitude.
  </Card>

  <Card title="Mixpanel" icon="chart-mixed" href="./mixpanel">
    Sincronize coortes e importe eventos personalizados do Mixpanel.
  </Card>

  <Card title="Snowflake" icon="snowflake" href="./snowflake">
    Importe eventos personalizados do seu warehouse Snowflake.
  </Card>

  <Card title="Google BigQuery" icon="database" href="./bigquery">
    Importe eventos personalizados de datasets BigQuery.
  </Card>

  <Card title="Apache Kafka" icon="bolt" href="./kafka">
    Transmita eventos personalizados de tópicos Kafka.
  </Card>
</Columns>

<Card title="Ver todas as fontes de eventos personalizados" icon="grid-2" href="./integrations#custom-event-sources">
  Veja a lista completa de bancos de dados, warehouses e plataformas de streaming que importam eventos personalizados para o OneSignal.
</Card>

<Tip>
  **Sem recursos de desenvolvimento?** Importe eventos personalizados diretamente de uma planilha do [Google Sheets](./google-sheets) — sem código necessário. Adicione seus dados de evento a uma planilha e o OneSignal os importa automaticamente. Ideal para experimentação inicial ou equipes sem suporte de engenharia.
</Tip>

### 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

<Frame caption="Aba Event List no painel do OneSignal em Data > Custom Events">
  <img src="https://mintcdn.com/onesignal/MWGmj5X1CnFliD-c/images/dashboard/event-list.png?fit=max&auto=format&n=MWGmj5X1CnFliD-c&q=85&s=2b9cae667bed4b54974326ffa0830907" width="3302" height="1888" data-path="images/dashboard/event-list.png" />
</Frame>

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

<Frame caption="Aba Event List no painel do OneSignal em Data > Custom Events">
  <img src="https://mintcdn.com/onesignal/MWGmj5X1CnFliD-c/images/dashboard/event-activity.png?fit=max&auto=format&n=MWGmj5X1CnFliD-c&q=85&s=8e355c907b598f1ac5a446e3536b9eea" width="3302" height="1888" data-path="images/dashboard/event-activity.png" />
</Frame>

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

<Warning> O feed não atualiza automaticamente. Atualize manualmente após enviar novos eventos. </Warning>

***

## 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

<Card title="Configurações de Jornada" icon="gear" href="./journeys-settings#entry-rules">
  Adicione usuários a Jornadas com Eventos Personalizados.
</Card>

### 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`

<Info> 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. </Info>

<Card title="Etapa Wait Until da Jornada" icon="stopwatch" href="./journeys-actions#wait-until">
  Mantenha usuários até que um Evento Personalizado ocorra.
</Card>

### Personalizar Jornadas com propriedades do evento

Referencie propriedades do evento usando Liquid nos seus templates de Jornada.

Exemplo:

```liquid Liquid theme={null}
Thanks for purchasing {{ journey.first_event.properties.item }}!
```

<Card title="Personalização com Eventos Personalizados" icon="bolt" href="./personalization-custom-event">
  Guia completo para usar propriedades de eventos na personalização de Jornadas.
</Card>

### Segmentar usuários com Eventos Personalizados

Crie um segmento baseado na ocorrência de um Evento Personalizado.

<Note>
  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
</Note>

<Warning>
  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
</Warning>

<Card title="Segmentação" icon="filter" href="./segmentation">
  Guia completo de segmentação.
</Card>

***

## Disponibilidade do plano e custos de retenção

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

<Card title="FAQ de Faturamento" icon="receipt" href="./billing-faq#streaming-events">
  Saiba mais sobre retenção de eventos e preços.
</Card>

***

## Tags vs Eventos Personalizados

[Tags](/docs/pt-BR/add-user-data-tags) e [Custom Events](/docs/pt-BR/custom-events) são ambas formas de adicionar dados aos seus usuários. No entanto, existem algumas diferenças principais:

| Recurso           |                     Tags                     |                                            Custom Events                                            |
| ----------------- | :------------------------------------------: | :-------------------------------------------------------------------------------------------------: |
| Uso de dados      |         Segmentação e personalização         | Disparar Jornadas sem um Segmento, passos Wait Until, personalização diretamente dentro de Jornadas |
| Retenção de dados |                   Vitalícia                  |    30+ dias ([armazenamento vitalício está disponível](/docs/pt-BR/billing-faq#streaming-events))   |
| Formato de dados  |        Strings ou números chave-valor        |                                                 JSON                                                |
| Fonte de dados    | OneSignal SDK, API ou integrações (limitado) |                                  OneSignal SDK, API ou integrações                                  |
| Acesso aos dados  |   Segmentação e personalização de mensagem   |            Jornadas 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

***