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

# Aplicativo de exemplo: Journeys

> As sete Journeys do aplicativo de exemplo Clean Beans: onboarding, sequências, reengajamento, promoções e um webhook de Journey que chama o backend.

Esta página faz parte de [Aplicativo de exemplo: uma integração completa do OneSignal](https://documentation.onesignal.com/docs/pt-BR/example-full-integration-overview.md), que acompanha um aplicativo real de ponta a ponta. O aplicativo é o **Clean Beans**, uma escala de limpeza para casas compartilhadas, criado com Expo (React Native) e um backend Supabase.

A maioria das mensagens deste guia é enviada pelo backend, uma solicitação por vez. Uma **Journey** é diferente. É uma sequência criada no painel do OneSignal que decide sozinha para quem enviar mensagens, quando e o que acontece em seguida. O Clean Beans usa Journeys para tudo o que se desenrola ao longo de horas ou dias, e para textos e horários que devem poder mudar sem uma nova versão.

O Clean Beans executa sete Journeys.

| Journey | Começa quando | O que faz |
| - | - | - |
| [Onboarding](#onboarding-a-sequence-with-a-goal) | O aplicativo envia `signed_up` | Email de boas-vindas e tour in-app, depois três pushes ao longo de seis dias, até a primeira sessão de limpeza |
| [Lembrete de sessão](#session-reminder-start-on-one-event-cancel-on-another) | O aplicativo envia `cleaning_session_started` | Um push três horas depois, a menos que a sessão tenha sido concluída |
| [Sessão concluída](#session-completed-personalize-from-the-event) | O aplicativo envia `cleaning_session_completed` | Um push para quem limpou, com o nome do cômodo que acabou de limpar |
| [Promoções por cômodo](#room-based-promos-branch-on-an-event-property) | Um membro ativo recentemente conclui uma sessão | Um push diferente para cozinha, banheiro ou quarto, duas horas depois |
| [Marco de sequência](#streak-milestone-an-event-with-a-number) | O aplicativo envia `streak_milestone` | Um push que comemora 3, 7, 14, 30 dias ou mais |
| [Sequência prestes a acabar](#streak-about-to-break-timing-a-segment-check-and-varied-copy) | O aplicativo envia `cleaning_session_completed` | Um push de aviso na noite seguinte, com um de cinco textos |
| [Reengajamento](#re-engagement-and-the-journey-webhook) | Um membro está inativo há sete dias | Push, push, email, push ao longo de dez dias e, depois, um webhook para o backend |

Nenhuma delas tem código de backend próprio, exceto o webhook no fim da última. O trabalho do aplicativo é dar às Journeys algo com que trabalhar.

## O que o aplicativo dá a uma Journey para trabalhar \\

Uma Journey consegue ver três coisas sobre uma pessoa: os **eventos personalizados** que ela enviou, as **tags** dela e os **segmentos** aos quais pertence. Ela não consegue ler o seu banco de dados. Tudo a que uma Journey precise reagir tem que chegar em uma dessas formas.

| Sinal | Tipo | Enviado quando | Usado por |
| - | - | - | - |
| `signed_up` | Evento personalizado | Uma conta nova faz login pela primeira vez | Onboarding (entrada) |
| `cleaning_session_started` | Evento personalizado | Uma sessão de limpeza começa | Lembrete de sessão (entrada) |
| `cleaning_session_completed` | Evento personalizado, com `room_name` | Uma sessão de limpeza termina | Sessão concluída, Promoções por cômodo, Sequência prestes a acabar (entrada). Onboarding, Lembrete de sessão, Reengajamento (saída) |
| `streak_milestone` | Evento personalizado, com `streak_count` | Uma sessão leva a sequência a um marco | Marco de sequência (entrada) |
| `user_name`, `household_name`, `streak_count` | Tags | Login, fim da sessão, edição do perfil | Personalizar o texto das mensagens |
| `streak_reminders` | Tag | Login e quando as configurações de notificação são salvas | Sequência prestes a acabar (quem pode recebê-la) |

Os eventos de sessão são abordados em [Tags, eventos personalizados e Conversion Metrics](https://documentation.onesignal.com/docs/pt-BR/example-full-integration-tags-events.md). Os outros dois eventos existem apenas para iniciar uma Journey.

`signed_up` é disparado uma vez por conta. A idade da conta é verificada primeiro, para que alguém que instala o aplicativo em um celular novo não passe pelo onboarding uma segunda vez.

```typescript src/lib/onesignalSync.ts theme={null}
const accountAgeMs = Date.now() - new Date(profile.created_at).getTime();
if (accountAgeMs <= NEW_SIGN_UP_WINDOW_MS) {
  const ctx = await getEventContext();
  if (!ctx) return;

  OneSignal.User.trackEvent('signed_up', {
    external_id: ctx.external_id,
    user_name: ctx.user_name,
    household_name: ctx.household_name,
  });
  console.log('[onesignalSync] Custom event: signed_up');
}

await AsyncStorage.setItem(flagKey, '1');
```

`streak_milestone` carrega a duração da sequência como número, para que a mensagem possa exibi-la.

```typescript src/lib/onesignalSync.ts theme={null}
OneSignal.User.trackEvent('streak_milestone', {
  external_id: ctx.external_id,
  user_name: ctx.user_name,
  household_name: ctx.household_name,
  streak_count: streak,
});
```

> [!WARNING]
>
> Envie um evento que inicia uma Journey somente depois de chamar `OneSignal.login()`. Um evento enviado antes do login é registrado para um usuário anônimo, não para a pessoa que está prestes a fazer login. O Clean Beans chama `trackSignedUpOnce()` logo após `login()` no mesmo effect. Consulte [Configuração do SDK e identidade do usuário](https://documentation.onesignal.com/docs/pt-BR/example-full-integration-sdk-setup.md#tie-each-device-to-a-user).

## Onboarding: uma sequência com um objetivo \\

A Journey de onboarding tem um único objetivo: levar um novo membro à primeira sessão de limpeza. Tudo nela para no momento em que isso acontece.

**1. O aplicativo envia signed\_up**

O membro entra na Journey. Cada membro passa por ela uma vez.

**2. Um email de boas-vindas e um tour in-app saem imediatamente**

O email lista três passos para começar. A mensagem in-app aparece na próxima vez que o membro abre o aplicativo.

**3. Três pushes seguem nos dias 1, 3 e 6**

Cada um aguarda uma janela de tempo das 10:00 às 19:00 no fuso horário do próprio membro.

**4. Uma sessão concluída encerra a Journey**

A regra de saída da Journey é o evento `cleaning_session_completed`. Ninguém é incentivado a fazer algo que já fez.

| Etapa | Quando | Mensagem |
| - | - | - |
| Email | Imediatamente | "Welcome to Clean Beans", com três passos para começar |
| Mensagem in-app | Próxima abertura do aplicativo, por até três dias | O tour de boas-vindas |
| Push 1 | Dia 1 | "Ready for your first clean?" |
| Push 2 | Dia 3 | "Cleaning is easier shared" (abre a tela Household) |
| Push 3 | Dia 6 | "Your rota is waiting" |

**Configuração no painel.** Crie a Journey com **Custom Event** como regra de entrada e `signed_up` como evento. Nas regras de saída, escolha sair quando ocorrer um evento personalizado e selecione `cleaning_session_completed`. Coloque uma etapa **Time Window** antes de cada push, para que uma espera que termina às 03:00 não envie às 03:00.

> [!TIP]
>
> Escolha o objetivo primeiro e transforme-o na regra de saída. Uma sequência sem objetivo continua falando com pessoas que já fizeram o que ela pedia.

## Lembrete de sessão: começar com um evento, cancelar com outro \\

Se alguém começa uma sessão de limpeza e nunca a termina, o trabalho não é registrado. Esta Journey começa com `cleaning_session_started`, espera três horas e envia um lembrete. A regra de saída é `cleaning_session_completed`, então concluir a sessão cancela o lembrete.

| Etapa | Configuração |
| - | - |
| Entrada | Evento personalizado `cleaning_session_started` |
| Espera | 3 horas |
| Janela de tempo | Das 08:00 às 21:00, fuso horário do membro |
| Push | "What happened? It looks like you started a cleaning session and didn't finish it." |
| Saída | Evento personalizado `cleaning_session_completed` |

Esse par de início e cancelamento é a Journey útil mais simples que existe. O mesmo formato serve para um carrinho abandonado, um formulário de cadastro não concluído ou um rascunho que nunca foi enviado.

> [!NOTE]
>
> **Verifique o limite da janela de tempo.** Originalmente a janela fechava às 18:00. Uma sessão iniciada às 16:00 chegava ao fim da espera às 19:00, encontrava a janela fechada e recebia "you didn't finish" às 08:00 da manhã seguinte. Agora a janela fecha às 21:00. Quando uma mensagem só faz sentido no mesmo dia, verifique o que acontece com alguém que chega logo depois que a janela fecha.

## Sessão concluída: personalizar a partir do evento \\

Quando uma sessão termina, quem limpou recebe uma breve confirmação com o nome do cômodo. O cômodo não é uma tag. Ele vem do evento que iniciou a Journey.

```text Push template: Cleaning Session Completed theme={null}
{{ journey.first_event.properties.room_name }} cleaned ✅

Great work cleaning the {{ journey.first_event.properties.room_name }} {{ user_name | default: 'cleaner' }}! Keep up the hard work!
```

`journey.first_event.properties` lê uma propriedade do evento de entrada. `user_name` sozinho lê uma tag, e o filtro `default` cobre qualquer pessoa sem essa tag.

Esta Journey tem uma única etapa. Ela poderia ter sido um envio do backend, como o push que avisa os colegas de casa sobre a mesma sessão em [Enviar push a partir do seu backend](https://documentation.onesignal.com/docs/pt-BR/example-full-integration-backend-push.md#session-completed-a-push-triggered-from-the-app). Ela é uma Journey porque assim o texto pode ser alterado, testado ou desativado no painel.

> [!WARNING]
>
> O Event Stream informa uma mensagem de Journey como ela foi escrita, ainda com o Liquid. A caixa de entrada do Clean Beans mostrava `{{ journey.first_event.properties.room_name }} cleaned` até o webhook aprender a renderizá-lo. Consulte [Renderizar o Liquid antes de armazenar](https://documentation.onesignal.com/docs/pt-BR/example-full-integration-inbox.md#render-liquid-before-you-store-it).

## Promoções por cômodo: ramificar com base em uma propriedade do evento \\

Esta Journey envia uma mensagem diferente dependendo do cômodo que foi limpo. Ela mostra duas coisas: manter pessoas em espera até que um evento aconteça e ramificar com base em uma propriedade desse evento.

Os membros entram a partir de um segmento de pessoas ativas nos últimos sete dias. A primeira etapa é um **Wait Until** com três ramificações. Cada ramificação aguarda `cleaning_session_completed` com um `room_name` específico.

| Condição da ramificação | Depois |
| - | - |
| `room_name` é `Kitchen` | Esperar 2 horas, janela de tempo das 08:00 às 20:00, push da cozinha |
| `room_name` é `Bathroom` | Esperar 2 horas, janela de tempo das 08:00 às 20:00, push do banheiro |
| `room_name` é `Bedroom` | Esperar 2 horas, janela de tempo das 08:00 às 20:00, push do quarto |

Uma sessão em qualquer outro cômodo não corresponde a nenhuma ramificação, e o membro continua esperando. A reentrada é permitida após 30 minutos, então a Journey responde a cada nova sessão.

> [!NOTE]
>
> Os pushes desta Journey anunciam produtos de limpeza fictícios. Eles estão aqui para mostrar o padrão. Também são mensagens de marketing que as configurações de notificação do aplicativo não cobrem, algo a considerar no design de um aplicativo real. Consulte [O que as Journeys não conseguem ver](#what-journeys-cannot-see).

## Marco de sequência: um evento com um número \\

O aplicativo decide quando uma sequência atingiu um marco, porque acabou de salvar a nova sequência. Ele envia `streak_milestone` com a duração, e a Journey faz o resto.

```text Push template: Streak - Milestone reached theme={null}
🔥 {{ journey.first_event.properties.streak_count }}-day streak!

Nice work, {{ user_name | default: 'you' }}. That's {{ journey.first_event.properties.streak_count }} days in a row. Keep it going tomorrow.
```

| Etapa | Configuração |
| - | - |
| Entrada | Evento personalizado `streak_milestone` |
| Espera | 1 minuto |
| Push | O template acima |

> [!NOTE]
>
> **Duas Journeys, um mesmo momento.** Um marco sempre acontece no fim de uma sessão, que é também quando a Journey de sessão concluída envia. Sem a espera de um minuto, os dois pushes chegariam juntos. Quando várias Journeys começam a partir da mesma ação do usuário, analise-as lado a lado.

## Sequência prestes a acabar: horário, uma verificação de segmento e textos variados \\

Uma sequência termina à meia-noite de qualquer dia sem sessão. Esta Journey avisa o membro naquela noite. É a mais elaborada das sete, e cada uma de suas etapas resolve um problema diferente.

| Etapa | Configuração | Por quê |
| - | - | - |
| Entrada | Evento personalizado `cleaning_session_completed` | Cada sessão inicia uma nova contagem regressiva |
| Espera | 22 horas | Veja abaixo |
| Janela de tempo | Das 18:00 às 22:00, fuso horário do membro | A noite do dia seguinte à sessão |
| Ramificação Yes/No | No segmento "Streak 2+ Days, Reminders On" | Apenas pessoas com uma sequência que querem o lembrete |
| Split, 5 ramificações de 20% | Um de cinco templates de push | O texto muda de uma noite para outra |
| Saída | Evento personalizado `cleaning_session_completed` | A pessoa limpou de novo, então o aviso deixou de ser verdade |

**Chegar à noite certa.** O aviso pertence à noite seguinte à última sessão, qualquer que tenha sido o horário dela. Uma espera de 22 horas seguida de uma janela das 18:00 às 22:00 sempre cai ali. Uma sessão às 08:00 chega à etapa da janela às 06:00 do dia seguinte e fica retida até as 18:00. Uma sessão às 23:00 chega às 21:00 do dia seguinte e é enviada na hora.

**Respeitar uma configuração que a Journey não vê.** O Clean Beans tem uma chave "Streak reminders" nas configurações de notificação, armazenada no banco de dados. O aplicativo a espelha como uma tag.

```typescript src/lib/onesignalSync.ts theme={null}
// Mirrors the "Streak reminders" setting, so a Journey can respect it.
// Journeys cannot read the app's database, only tags.
streak_reminders:
  profile.notifications_enabled !== false && profile.push_streak_reminders !== false ? 'on' : 'off',
```

O segmento exige `streak_count` maior que 1 e `streak_reminders` igual a `on`. Um membro com uma versão antiga não tem a tag `streak_reminders`, então fica fora do segmento e não recebe o aviso.

**Variar o texto.** A mesma frase toda noite deixa de ser notada com facilidade. A etapa **Split** envia cada pessoa por uma de cinco ramificações aleatoriamente, e cada ramificação tem o próprio template. A ramificação é escolhida de novo toda vez que alguém entra, então um membro vê textos diferentes em noites diferentes.

| Ramificação | Título |
| - | - |
| A | Your streak ends at midnight |
| B | Don't let your streak slip away |
| C | Still time to clean today |
| D | One task saves your streak |
| E | Midnight is coming for your streak ⏰ |

> [!NOTE]
>
> O Clean Beans também mostra um aviso de sequência como Live Activity, descrito em [Live Activities](https://documentation.onesignal.com/docs/pt-BR/example-full-integration-live-activities.md). Um membro com Live Activities ativadas recebe os dois. O push cobre o Android e quem desativou as Live Activities.

## Reengajamento e o webhook de Journey \\

A última Journey cuida dos membros que pararam de abrir o aplicativo. É a única que entra apenas a partir de um segmento e a única que chama o backend.

| Etapa | Quando | Mensagem |
| - | - | - |
| Entrada | O membro entra no segmento "Inactive 7+ Days" | Somente novos participantes |
| Push 1 | Próxima janela das 10:00 às 19:00 | "It's been a while" |
| Push 2 | 2 dias depois | O ranking semanal |
| Email | 3 dias depois | "We saved your spot" |
| Push 3 | 3 dias depois | "A fresh start" |
| Webhook | 2 dias depois | Informa ao backend que o membro ficou inativo |
| Saída | Evento personalizado `cleaning_session_completed` | A pessoa voltou |

A reentrada é permitida após 30 dias. A entrada é limitada a pessoas que entram no segmento depois que a Journey começa. Sem isso, todos que já estão inativos no dia em que ela é ativada recebem o primeiro push imediatamente.

### Avise o seu backend quando a sequência terminar \\

Um membro que chega ao fim sem limpar não respondeu a quatro mensagens. É improvável que uma quinta ajude. Em vez disso, o Clean Beans avisa a casa. Uma etapa **Webhook** chama uma função do backend, que marca o membro como inativo e notifica os donos e administradores da casa.

**Configuração no painel.** Crie um webhook de Journey com estas configurações e selecione-o na última etapa da Journey.

```json Journey webhook theme={null}
{
  "method": "POST",
  "url": "https://YOUR_PROJECT_REF.supabase.co/functions/v1/journey-webhook",
  "headers": {
    "Content-Type": "application/json",
    "X-Webhook-Secret": "YOUR_SHARED_SECRET"
  },
  "body": {
    "event": "member_lapsed",
    "external_id": "{{ user.external_id }}"
  }
}
```

A função verifica o segredo antes de qualquer outra coisa. Ela é implantada sem a verificação de token do Supabase, porque o OneSignal não envia um token do Supabase, então o segredo compartilhado é a única coisa entre o endpoint e a internet pública.

```typescript supabase/functions/journey-webhook/index.ts theme={null}
const secret = req.headers.get('X-Webhook-Secret') ?? '';
if (!JOURNEY_WEBHOOK_SECRET || secret !== JOURNEY_WEBHOOK_SECRET) {
  return new Response('Unauthorized', { status: 401 });
}
```

Em seguida, ela verifica a afirmação por conta própria. A Journey diz que o membro está inativo, mas a Journey só conhece as sessões do aplicativo e os eventos. O banco de dados sabe se a pessoa limpou.

```typescript supabase/functions/journey-webhook/index.ts theme={null}
const since = new Date(Date.now() - RECENT_ACTIVITY_DAYS * 24 * 60 * 60 * 1000).toISOString();
const { count: recentSessions } = await supabase
  .from('cleaning_sessions')
  .select('id', { count: 'exact', head: true })
  .eq('user_id', userId)
  .gte('completed_at', since);

if ((recentSessions ?? 0) > 0) {
  return jsonResponse({ skipped: true, reason: 'recently_active' });
}

// Already flagged: a retried or repeated webhook does nothing more
if (profile.lapsed_at) {
  return jsonResponse({ skipped: true, reason: 'already_lapsed' });
}
```

Só então ela marca o membro e envia um push para as pessoas que podem fazer algo a respeito.

```typescript supabase/functions/journey-webhook/index.ts theme={null}
const onesignalPayload: Record<string, unknown> = {
  app_id: ONESIGNAL_APP_ID,
  include_aliases: { external_id: recipientIds },
  target_channel: 'push',
  ...DELIVERY.member_lapsed,
  headings: { en: `${memberName} has gone quiet` },
  contents: { en: `${memberName} hasn't cleaned in a while. A friendly nudge might help.` },
  url: 'cleaning-rota:///household',
  data: { type: 'member_lapsed', memberId: userId, memberName },
};
```

A marcação se apaga sozinha. Um trigger do banco de dados a remove na próxima vez que o membro conclui uma sessão, então o aplicativo nunca precisa se lembrar de fazer isso.

> [!TIP]
>
> Uma etapa de webhook pode fazer qualquer coisa que uma etapa de mensagem não consegue: atualizar um registro, abrir um ticket de suporte, adicionar alguém a uma lista em outro sistema. Trate a solicitação como qualquer outra chamada externa. Verifique um segredo, verifique os fatos e torne uma repetição inofensiva.

## O que as Journeys não conseguem ver \\

Todo envio do backend neste guia verifica as configurações de notificação do membro antes de enviar. Uma Journey não consegue fazer isso, porque as configurações estão no banco de dados do aplicativo.

| A Journey precisa saber | Como o Clean Beans informa |
| - | - |
| Que algo acabou de acontecer | Um evento personalizado |
| Um fato sobre a pessoa | Uma tag |
| Um grupo de pessoas | Um segmento criado a partir de tags ou atividade |
| Se deve parar | Uma regra de saída baseada em um evento personalizado |
| Uma configuração armazenada no seu banco de dados | Uma tag que espelha a configuração e um segmento que a exige |

Apenas o aviso de sequência tem uma configuração espelhada. Os outros pushes de Journey vão para qualquer pessoa com notificações push ativadas para o aplicativo. Se o seu aplicativo tem configurações de notificação por tipo, espelhe cada uma que uma Journey deva respeitar.

## O que é bom saber \\

* **Procure Journeys que compartilham um público.** O Clean Beans chegou a ter duas Journeys de reengajamento ativas no mesmo segmento, o que colocou cada membro inativo na fila das duas sequências. Uma segunda Journey em um segmento é fácil de ativar e difícil de perceber.
* **Dê aos pushes de Journey uma URL e um `data.type`.** Os templates criados no painel não têm nenhum dos dois por padrão, então um toque só abre o aplicativo. O Clean Beans define os dois em todo template de Journey, para que sejam roteados como os pushes do backend. Consulte [Deep links e cliques em notificações](https://documentation.onesignal.com/docs/pt-BR/example-full-integration-deep-links.md).
* **Uma Journey ativa pode ser editada, e a edição pode afetar quem já está nela.** O Clean Beans mudou uma janela de tempo e adicionou uma espera em Journeys que estavam em execução. Faça mudanças assim de forma deliberada.
* **As mensagens de Journey entram na caixa de entrada.** Elas chegam pelo mesmo Event Stream que qualquer outro push, com o Liquid não renderizado.
* **Desative o rastreamento de cliques em um email cujo botão é um Universal Link.** O rastreamento reescreve os links para passarem por um domínio de rastreamento, e um link reescrito não abre mais o aplicativo. Consulte [Abrir o aplicativo a partir de links web comuns](https://documentation.onesignal.com/docs/pt-BR/example-full-integration-deep-links.md#open-the-app-from-ordinary-web-links).

> [card] [Visão geral de Journeys](https://documentation.onesignal.com/docs/pt-BR/journeys-overview.md)
>
> Regras de entrada, etapas e como uma Journey é executada.

> [card] [Configurações de Journey](https://documentation.onesignal.com/docs/pt-BR/journeys-settings.md)
>
> Quem entra, sai e volta a entrar.

> [card] [Ações de Journey](https://documentation.onesignal.com/docs/pt-BR/journeys-actions.md)
>
> Wait, Wait Until, Yes/No, Split e Time Window.

> [card] [Webhooks de Journey](https://documentation.onesignal.com/docs/pt-BR/journeys-webhook.md)
>
> Chame seu próprio servidor a partir de uma etapa da Journey.

> [card] [Personalizar com eventos personalizados](https://documentation.onesignal.com/docs/pt-BR/personalization-custom-event.md)
>
> Use propriedades de eventos em mensagens de Journey.

> [card] [Journeys orientadas a eventos](https://documentation.onesignal.com/docs/en/event-driven-journeys.md)
>
> Crie Journeys que respondam ao comportamento.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.