> ## 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.
# Operadores de Tempo
> Operadores de Tempo permitem que você envie mensagens relativas a um momento específico no tempo—como após uma ação acontecer ou antes de uma data futura.
## Visão geral
Operadores de Tempo permitem que você envie mensagens relativas a um momento específico no tempo—como **após uma ação acontecer** ou **antes de uma data futura**.
Você armazena esse momento como um **timestamp Unix (em segundos)** no usuário usando uma **Tag**. O OneSignal então compara o tempo atual com esse timestamp e permite que você segmente usuários com base em quanto tempo passou (ou quanto tempo resta).
Isso facilita a automatização de mensagens como lembretes, follow-ups e deadlines sem agendar mensagens manualmente.
**Casos de uso comuns:**
* **[Carrinho abandonado](./abandoned-cart)**: Lembrar usuários que não finalizaram a compra após um determinado tempo
* **Lembretes de eventos**: Enviar mensagens para usuários antes de um compromisso agendado ou data de renovação
* **Marcos**: Fazer follow-up quando usuários não completaram uma ação antes de um prazo
* **Aniversários**: Enviar mensagens automáticas no (ou próximo ao) aniversário de um usuário
Operadores de Tempo estão disponíveis apenas em planos pagos. Planos gratuitos ainda podem usar filtros de segmento baseados em tempo padrão como First Session e Last Session.
### Quando devo usar isso?
Use Operadores de Tempo quando você quiser:
* Enviar mensagens **relativas a um evento**, não em um tempo fixo do calendário
* Criar **janelas de tempo móveis** (por exemplo, "24–48 horas depois")
* Reutilizar a mesma lógica para muitos usuários com datas diferentes
* Avaliar continuamente a elegibilidade conforme o tempo passa
Se você precisa disparar mensagens imediatamente quando um evento ocorre, considere usar **[Custom Events](./custom-events)** em vez disso.
### Tags vs Custom Events
Você pode resolver muitos casos de uso de "lembrete" com **Tags** ou **Custom Events**. A melhor opção depende do que você precisa armazenar e como você quer acionar a automação.
* Use **Tags** quando você quer armazenar o **último timestamp conhecido** (por exemplo, `cart_updated_at` ou `subscription_expires_at`) no usuário e segmentar com base nesse valor ao longo do tempo.
* Use **Custom Events** quando você quer registrar **cada ocorrência de evento** (com propriedades) e acionar Journeys com base no comportamento em tempo real.
Na prática, muitas implementações podem usar ambos: Custom Events para rastreamento em tempo real e Tags para estado do usuário que você quer segmentar depois.
[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
***
## Referência rápida
1. Converta a data do evento para um timestamp Unix em **segundos**.
2. Defina uma [Tag](./add-user-data-tags) onde a chave é o nome do evento e o valor é o timestamp como **string** (ex., `'event_date': '1739145600'`).
3. Crie um segmento usando o operador **Time Elapsed Greater Than**:
* Após uma data passada usando o operador **Time Elapsed Greater Than** com um valor positivo
* Antes de uma data futura usando o operador **Time Elapsed Greater Than** com um valor negativo
Um erro comum é definir timestamps em **milissegundos** (13 dígitos) em vez de **segundos** (10 dígitos). Operadores de Tempo requerem **segundos**.
***
## Enviar mensagens após um evento passado
Use esse padrão quando você quiser enviar mensagens para usuários **após um certo tempo ter passado** desde que algo aconteceu.
**Exemplo: Lembrete de carrinho abandonado 24 horas após o usuário atualizar seu carrinho**
Quando o usuário atualizar seu carrinho, salve o tempo atual como um timestamp Unix (em segundos):
```javascript theme={null}
// Exemplo SDK
const timestampSeconds = String(Math.floor(Date.now() / 1000));
OneSignal.User.addTag("cart_updated_at", timestampSeconds);
```
Use segundos (10 dígitos), não milissegundos (13 dígitos).
1. Vá para **Audience** > **Segments**
2. Adicione um filtro **User Tag**
3. Defina **Key** como `cart_updated_at`
4. Escolha **Time Elapsed Greater Than**
5. Defina **Value** como `1` dia (ou `24` horas ou `86400` segundos)
Sem um limite superior, os usuários permanecem no segmento para sempre. Adicione um segundo filtro para criar uma janela:
* **Time Elapsed Greater Than** `24` horas
* **Time Elapsed Less Than** `48` horas
Agora os usuários estão apenas no segmento entre 24-48 horas após o evento.
Crie um [Journey](./journeys-overview) que segmente seu segmento para automatizar as mensagens.
***
## Enviar mensagens antes de um evento futuro
Use esse padrão para enviar mensagens para usuários **antes de uma data futura**, como um compromisso ou renovação.
1. Armazene a data futura como uma tag de timestamp Unix (ex., `'future_date': '1739145600'`)
2. Crie um segmento com **Time Elapsed Greater Than** e seu tempo de entrada desejado como um valor negativo
* Exemplo: `-2` dias (ou `-172800` segundos)
3. Adicione um limite superior usando o mesmo operador **Time Elapsed Greater Than** com um valor negativo de um tempo mais próximo
* Exemplo: `-1` dia (ou `-86400` segundos)
### Exemplo: Mensagens de aniversário
Envie mensagens de aniversário armazenando o **próximo aniversário** de cada usuário como um timestamp.
Calcule e armazene o próximo aniversário do usuário:
```javascript theme={null}
function getNextBirthday(month, day) {
// month: 0-11 (Jan=0), day: 1-31
const now = new Date();
let birthday = new Date(now.getFullYear(), month, day);
if (birthday <= now) {
birthday = new Date(now.getFullYear() + 1, month, day);
}
return String(Math.floor(birthday.getTime() / 1000));
}
// Exemplo: aniversário em 15 de janeiro
OneSignal.User.addTag("birthday", getNextBirthday(0, 15));
```
* **User Tag**: `birthday`
* **Time Elapsed Greater Than**: `0` segundos
Os usuários entram no segmento uma vez que seu timestamp de aniversário passa.
1. Crie um [Journey](./journeys-overview) direcionado ao seu segmento de aniversário
2. Defina a reentrada para **52 semanas** para que os usuários possam reentrar no próximo ano
3. Atualize a tag `birthday` para a data do próximo ano após o envio (no seu backend ou Journey)
Calcule timestamps de aniversário usando o fuso horário local do usuário quando possível. Usar apenas o horário do servidor pode fazer com que as mensagens sejam enviadas mais cedo ou mais tarde do que o esperado.
Se você quiser que as mensagens permaneçam precisas ano após ano, atualize a tag `birthday` do usuário para o próximo aniversário após enviar a mensagem (por exemplo, no seu backend ou em uma etapa do Journey). Tenha em mente que, se você fizer isso, pode ser mais fácil usar [Custom Events](./custom-events) em vez disso.
Mensagens de aniversário serão enviadas para usuários próximo à data da sua tag `birthday`.
***
## FAQ
### Como funciona a matemática? (detalhes técnicos)
Operadores de Tempo existem para permitir que você crie **janelas relativas e móveis** em vez de datas fixas.
O OneSignal calcula o tempo decorrido usando esta fórmula:
```
time_elapsed = current_time - tag_timestamp
```
* **Timestamps passados** → valores positivos
* **Timestamps futuros** → valores negativos
**Operadores:**
* `Time Elapsed Greater Than X`: corresponde quando `elapsed > X`
* `Time Elapsed Less Than X`: corresponde quando `elapsed < X`
**Por que timestamps futuros correspondem imediatamente com `Less Than`:**
Qualquer número negativo é menor que qualquer número positivo. Então `time_elapsed_lt 2 days` (172,800 segundos) corresponderá a um timestamp 30 dias no futuro porque:
```
-2,592,000 < 172,800 → true (corresponde)
```
Como timestamps futuros sempre produzem tempo decorrido negativo, **você deve usar valores negativos** para definir quando os usuários devem entrar e sair de segmentos antes de um evento próximo. Valores positivos não podem representar tempo *antes* de uma data futura.
### Como posso testar?
1. Encontre seu usuário via ID Externo, ID de Assinatura, Email ou número de telefone. Veja [Encontrar e definir assinaturas de teste](./test-users) para detalhes sobre encontrar seu usuário.
2. Obtenha um timestamp em segundos da data atual e uma data futura (5 minutos a partir de agora).
3. Defina duas tags com as chaves 'current\_time' e 'future\_time' e os valores como os timestamps em segundos.
4. Crie um segmento `current_time` com os seguintes filtros:
* **User Tag**: `current_time` **Time Elapsed Greater Than**: `2` minutos
* E **User Tag**: `current_time` **Time Elapsed Less Than**: `5` minutos
5. Crie um segmento `future_time` com os seguintes filtros:
* **User Tag**: `future_time` **Time Elapsed Greater Than**: `-5` minutos
* E **User Tag**: `future_time` **Time Elapsed Less Than**: `-2` minutos
Você deve ver seu usuário:
* Entrar no segmento `current_time` 2 minutos após a data de tempo atual e sair do segmento 5 minutos após a data de tempo atual.
* Entrar no segmento `future_time` 5 minutos antes da data de tempo futuro e sair do segmento 2 minutos antes da data de tempo futuro.
***