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

# App de ejemplo: Journeys

> Los siete Journeys de la app de ejemplo Clean Beans: onboarding, rachas, reenganche, promociones y un webhook de Journey que llama al backend.

Esta página forma parte de [App de ejemplo: una integración completa de OneSignal](https://documentation.onesignal.com/docs/es/example-full-integration-overview.md), que sigue una app real de principio a fin. La app es **Clean Beans**, un turno de limpieza para hogares compartidos, creada con Expo (React Native) y un backend de Supabase.

La mayoría de los mensajes de esta guía los envía el backend, una solicitud cada vez. Un **Journey** es diferente. Es una secuencia creada en el panel de OneSignal que decide por sí misma a quién enviar mensajes, cuándo y qué ocurre después. Clean Beans usa Journeys para todo lo que se desarrolla a lo largo de horas o días, y para los textos y los tiempos que deben poder cambiarse sin una nueva versión.

Clean Beans ejecuta siete Journeys.

| Journey | Empieza cuando | Qué hace |
| - | - | - |
| [Onboarding](#onboarding-a-sequence-with-a-goal) | La app envía `signed_up` | Email de bienvenida y recorrido in-app, luego tres push a lo largo de seis días, hasta la primera sesión de limpieza |
| [Recordatorio de sesión](#session-reminder-start-on-one-event-cancel-on-another) | La app envía `cleaning_session_started` | Un push tres horas después, salvo que la sesión se haya terminado |
| [Sesión completada](#session-completed-personalize-from-the-event) | La app envía `cleaning_session_completed` | Un push a quien ha limpiado con el nombre de la habitación que acaba de limpiar |
| [Promociones por habitación](#room-based-promos-branch-on-an-event-property) | Un miembro activo recientemente completa una sesión | Un push distinto para una cocina, un baño o un dormitorio, dos horas después |
| [Hito de racha](#streak-milestone-an-event-with-a-number) | La app envía `streak_milestone` | Un push que celebra 3, 7, 14, 30 días y más |
| [Racha a punto de romperse](#streak-about-to-break-timing-a-segment-check-and-varied-copy) | La app envía `cleaning_session_completed` | Un push de aviso la noche siguiente, con una de cinco redacciones |
| [Reenganche](#re-engagement-and-the-journey-webhook) | Un miembro lleva siete días inactivo | Push, push, email, push a lo largo de diez días y luego un webhook al backend |

Ninguno tiene código de backend propio, salvo el webhook al final del último. La tarea de la app es dar a los Journeys algo con lo que trabajar.

## Lo que la app da a un Journey para trabajar \\

Un Journey puede ver tres cosas de una persona: los **eventos personalizados** que ha enviado, sus **etiquetas** y los **segmentos** a los que pertenece. No puede leer tu base de datos. Todo aquello a lo que un Journey deba reaccionar tiene que llegar de una de esas formas.

| Señal | Tipo | Se envía cuando | La usa |
| - | - | - | - |
| `signed_up` | Evento personalizado | Una cuenta nueva inicia sesión por primera vez | Onboarding (entrada) |
| `cleaning_session_started` | Evento personalizado | Empieza una sesión de limpieza | Recordatorio de sesión (entrada) |
| `cleaning_session_completed` | Evento personalizado, con `room_name` | Termina una sesión de limpieza | Sesión completada, Promociones por habitación, Racha a punto de romperse (entrada). Onboarding, Recordatorio de sesión, Reenganche (salida) |
| `streak_milestone` | Evento personalizado, con `streak_count` | Una sesión lleva la racha a un hito | Hito de racha (entrada) |
| `user_name`, `household_name`, `streak_count` | Etiquetas | Inicio de sesión, fin de sesión, edición del perfil | Personalizar el texto de los mensajes |
| `streak_reminders` | Etiqueta | Inicio de sesión y al guardar los ajustes de notificaciones | Racha a punto de romperse (a quién se le puede enviar) |

Los eventos de sesión se tratan en [Etiquetas, eventos personalizados y Conversion Metrics](https://documentation.onesignal.com/docs/es/example-full-integration-tags-events.md). Los otros dos eventos existen solo para iniciar un Journey.

`signed_up` se dispara una vez por cuenta. Primero se comprueba la antigüedad de la cuenta, para que alguien que instala la app en un teléfono nuevo no pase por el onboarding una 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` lleva la longitud de la racha como número, para que el mensaje pueda mostrarla.

```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]
>
> Envía un evento que inicia un Journey solo después de llamar a `OneSignal.login()`. Un evento enviado antes del inicio de sesión se registra para un usuario anónimo, no para la persona que está a punto de iniciar sesión. Clean Beans llama a `trackSignedUpOnce()` justo después de `login()` en el mismo efecto. Consulta [Configuración del SDK e identidad del usuario](https://documentation.onesignal.com/docs/es/example-full-integration-sdk-setup.md#tie-each-device-to-a-user).

## Onboarding: una secuencia con un objetivo \\

El Journey de onboarding tiene un solo objetivo: llevar a un miembro nuevo a su primera sesión de limpieza. Todo se detiene en cuanto eso ocurre.

**1. La app envía signed\_up**

El miembro entra en el Journey. Cada miembro pasa por él una vez.

**2. Un email de bienvenida y un recorrido in-app salen de inmediato**

El email enumera tres pasos para empezar. El mensaje in-app se muestra la próxima vez que el miembro abre la app.

**3. Siguen tres push los días 1, 3 y 6**

Cada uno espera a una ventana de tiempo de 10:00 a 19:00 en la zona horaria del propio miembro.

**4. Una sesión completada lo termina**

La regla de salida del Journey es el evento `cleaning_session_completed`. Nadie recibe un empujón para hacer algo que ya ha hecho.

| Paso | Cuándo | Mensaje |
| - | - | - |
| Email | De inmediato | "Welcome to Clean Beans", con tres pasos para empezar |
| Mensaje in-app | Siguiente apertura de la app, durante un máximo de tres días | El recorrido de bienvenida |
| Push 1 | Día 1 | "Ready for your first clean?" |
| Push 2 | Día 3 | "Cleaning is easier shared" (abre la pantalla Household) |
| Push 3 | Día 6 | "Your rota is waiting" |

**Configuración en el panel.** Crea el Journey con **Custom Event** como regla de entrada y `signed_up` como evento. En las reglas de salida, elige salir cuando ocurra un evento personalizado y selecciona `cleaning_session_completed`. Coloca un paso **Time Window** antes de cada push para que una espera que termina a las 03:00 no envíe a las 03:00.

> [!TIP]
>
> Elige primero el objetivo y conviértelo en la regla de salida. Una secuencia sin objetivo sigue hablando a personas que ya han hecho lo que pedía.

## Recordatorio de sesión: empezar con un evento, cancelar con otro \\

Si alguien empieza una sesión de limpieza y nunca la termina, su trabajo no se registra. Este Journey empieza con `cleaning_session_started`, espera tres horas y envía un recordatorio. Su regla de salida es `cleaning_session_completed`, así que terminar la sesión cancela el recordatorio.

| Paso | Ajuste |
| - | - |
| Entrada | Evento personalizado `cleaning_session_started` |
| Espera | 3 horas |
| Ventana de tiempo | De 08:00 a 21:00, zona horaria del miembro |
| Push | "What happened? It looks like you started a cleaning session and didn't finish it." |
| Salida | Evento personalizado `cleaning_session_completed` |

Este par de inicio y cancelación es el Journey útil más sencillo que existe. La misma forma sirve para una cesta abandonada, un formulario de registro sin terminar o un borrador que nunca se envió.

> [!NOTE]
>
> **Comprueba el límite de la ventana de tiempo.** Al principio la ventana cerraba a las 18:00. Una sesión iniciada a las 16:00 llegaba al final de su espera a las 19:00, encontraba la ventana cerrada y recibía "you didn't finish" a las 08:00 de la mañana siguiente. Ahora la ventana cierra a las 21:00. Cuando un mensaje solo tiene sentido el mismo día, comprueba qué le pasa a alguien que llega justo después de que cierre la ventana.

## Sesión completada: personalizar a partir del evento \\

Cuando termina una sesión, quien ha limpiado recibe una breve confirmación con el nombre de la habitación. La habitación no es una etiqueta. Procede del evento que inició el 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` lee una propiedad del evento de entrada. `user_name` por sí solo lee una etiqueta, y el filtro `default` cubre a cualquiera que no tenga la etiqueta.

Este Journey tiene un solo paso. Podría haber sido un envío del backend, como el push que avisa a los compañeros de casa de la misma sesión en [Enviar push desde tu backend](https://documentation.onesignal.com/docs/es/example-full-integration-backend-push.md#session-completed-a-push-triggered-from-the-app). Es un Journey porque así el texto puede cambiarse, probarse o desactivarse en el panel.

> [!WARNING]
>
> El Event Stream informa de un mensaje de Journey tal como se escribió, con el Liquid todavía dentro. La bandeja de Clean Beans mostraba `{{ journey.first_event.properties.room_name }} cleaned` hasta que el webhook aprendió a representarlo. Consulta [Representar Liquid antes de guardarlo](https://documentation.onesignal.com/docs/es/example-full-integration-inbox.md#render-liquid-before-you-store-it).

## Promociones por habitación: ramificar según una propiedad del evento \\

Este Journey envía un mensaje distinto según la habitación que se haya limpiado. Muestra dos cosas: retener a las personas hasta que ocurre un evento y ramificar según una propiedad de ese evento.

Los miembros entran desde un segmento de personas activas en los últimos siete días. El primer paso es un **Wait Until** con tres ramas. Cada rama espera `cleaning_session_completed` con un `room_name` concreto.

| Condición de la rama | Después |
| - | - |
| `room_name` es `Kitchen` | Esperar 2 horas, ventana de tiempo de 08:00 a 20:00, push de cocina |
| `room_name` es `Bathroom` | Esperar 2 horas, ventana de tiempo de 08:00 a 20:00, push de baño |
| `room_name` es `Bedroom` | Esperar 2 horas, ventana de tiempo de 08:00 a 20:00, push de dormitorio |

Una sesión en cualquier otra habitación no coincide con ninguna rama, y el miembro sigue esperando. Se permite volver a entrar después de 30 minutos, así que el Journey responde a cada nueva sesión.

> [!NOTE]
>
> Los push de este Journey anuncian productos de limpieza inventados. Están ahí para mostrar el patrón. También son mensajes de marketing que los ajustes de notificaciones de la app no cubren, algo que hay que tener en cuenta en el diseño de una app real. Consulta [Lo que los Journeys no pueden ver](#what-journeys-cannot-see).

## Hito de racha: un evento con un número \\

La app decide cuándo una racha ha alcanzado un hito, porque acaba de guardar la nueva racha. Envía `streak_milestone` con la longitud, y el Journey hace el 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.
```

| Paso | Ajuste |
| - | - |
| Entrada | Evento personalizado `streak_milestone` |
| Espera | 1 minuto |
| Push | La plantilla de arriba |

> [!NOTE]
>
> **Dos Journeys, un mismo momento.** Un hito siempre ocurre al final de una sesión, que es también cuando envía el Journey de sesión completada. Sin la espera de un minuto, los dos push llegarían a la vez. Cuando varios Journeys empiezan con la misma acción del usuario, revísalos juntos.

## Racha a punto de romperse: el momento, una comprobación de segmento y textos variados \\

Una racha termina a medianoche de cualquier día sin sesión. Este Journey avisa al miembro esa noche. Es el más complejo de los siete, y cada uno de sus pasos resuelve un problema distinto.

| Paso | Ajuste | Por qué |
| - | - | - |
| Entrada | Evento personalizado `cleaning_session_completed` | Cada sesión inicia una nueva cuenta atrás |
| Espera | 22 horas | Ver más abajo |
| Ventana de tiempo | De 18:00 a 22:00, zona horaria del miembro | La noche del día siguiente a la sesión |
| Rama Yes/No | En el segmento "Streak 2+ Days, Reminders On" | Solo personas con una racha que quieren el recordatorio |
| Split, 5 ramas al 20 % | Una de cinco plantillas de push | El texto cambia de una noche a otra |
| Salida | Evento personalizado `cleaning_session_completed` | Han vuelto a limpiar, así que el aviso ya no es cierto |

**Llegar a la noche correcta.** El aviso corresponde a la noche siguiente a la última sesión, sea cual sea la hora de esa sesión. Una espera de 22 horas seguida de una ventana de 18:00 a 22:00 siempre cae ahí. Una sesión a las 08:00 llega al paso de la ventana a las 06:00 del día siguiente y se retiene hasta las 18:00. Una sesión a las 23:00 llega a las 21:00 del día siguiente y se envía de inmediato.

**Respetar un ajuste que el Journey no puede ver.** Clean Beans tiene un interruptor "Streak reminders" en sus ajustes de notificaciones, guardado en la base de datos. La app lo replica como etiqueta.

```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',
```

El segmento exige `streak_count` mayor que 1 y `streak_reminders` igual a `on`. Un miembro con una versión antigua no tiene ninguna etiqueta `streak_reminders`, así que queda fuera del segmento y no recibe el aviso.

**Variar el texto.** La misma frase cada noche deja de verse fácilmente. El paso **Split** envía a cada persona por una de cinco ramas al azar, y cada rama tiene su propia plantilla. La rama se vuelve a elegir cada vez que alguien entra, así que un miembro ve textos distintos en noches distintas.

| Rama | 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]
>
> Clean Beans también muestra un aviso de racha como Live Activity, descrito en [Live Activities](https://documentation.onesignal.com/docs/es/example-full-integration-live-activities.md). Un miembro con las Live Activities activadas recibe ambos. El push cubre Android y a quien haya desactivado las Live Activities.

## Reenganche y el webhook de Journey \\

El último Journey se ocupa de los miembros que han dejado de abrir la app. Es el único que entra solo desde un segmento y el único que llama al backend.

| Paso | Cuándo | Mensaje |
| - | - | - |
| Entrada | El miembro se une al segmento "Inactive 7+ Days" | Solo nuevas entradas |
| Push 1 | Siguiente ventana de 10:00 a 19:00 | "It's been a while" |
| Push 2 | 2 días después | La clasificación semanal |
| Email | 3 días después | "We saved your spot" |
| Push 3 | 3 días después | "A fresh start" |
| Webhook | 2 días después | Avisa al backend de que el miembro ha dejado de participar |
| Salida | Evento personalizado `cleaning_session_completed` | Ha vuelto |

Se permite volver a entrar después de 30 días. La entrada se limita a las personas que se unen al segmento después de que empiece el Journey. Sin eso, todos los que ya están inactivos el día en que se activa reciben el primer push de inmediato.

### Avisa a tu backend cuando la secuencia se agota \\

Un miembro que llega al final sin limpiar no ha respondido a cuatro mensajes. Es poco probable que un quinto ayude. En su lugar, Clean Beans avisa al hogar. Un paso **Webhook** llama a una función del backend, que marca al miembro como inactivo y notifica a los propietarios y administradores del hogar.

**Configuración en el panel.** Crea un webhook de Journey con estos ajustes y selecciónalo en el último paso del 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 }}"
  }
}
```

La función comprueba el secreto antes que nada. Se despliega sin la comprobación de token de Supabase, porque OneSignal no envía un token de Supabase, así que el secreto compartido es lo único que separa el endpoint de la 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 });
}
```

Después comprueba la afirmación por sí misma. El Journey dice que el miembro está inactivo, pero el Journey solo conoce las sesiones de la app y los eventos. La base de datos sabe si ha limpiado.

```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' });
}
```

Solo entonces marca al miembro y envía un push a las personas que pueden hacer algo al respecto.

```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 },
};
```

La marca se borra sola. Un trigger de la base de datos la elimina la próxima vez que el miembro completa una sesión, así que la app nunca tiene que acordarse de hacerlo.

> [!TIP]
>
> Un paso de webhook puede hacer cualquier cosa que un paso de mensaje no puede: actualizar un registro, abrir un ticket de soporte, añadir a alguien a una lista en otro sistema. Trata la solicitud como cualquier otra llamada externa. Comprueba un secreto, comprueba los hechos y haz que una repetición sea inofensiva.

## Lo que los Journeys no pueden ver \\

Cada envío del backend en esta guía comprueba los ajustes de notificaciones del miembro antes de enviar. Un Journey no puede hacerlo, porque los ajustes están en la base de datos de la app.

| El Journey necesita saber | Cómo se lo dice Clean Beans |
| - | - |
| Que algo acaba de ocurrir | Un evento personalizado |
| Un dato sobre la persona | Una etiqueta |
| Un grupo de personas | Un segmento creado a partir de etiquetas o actividad |
| Si debe detenerse | Una regla de salida basada en un evento personalizado |
| Un ajuste guardado en tu base de datos | Una etiqueta que replica el ajuste y un segmento que lo exige |

Solo el aviso de racha tiene un ajuste replicado. Los demás push de Journey van a cualquiera que tenga activadas las notificaciones push de la app. Si tu app tiene ajustes de notificaciones por tipo, replica cada uno que un Journey deba respetar.

## Cosas que conviene saber \\

* **Busca Journeys que compartan audiencia.** Clean Beans tuvo durante un tiempo dos Journeys de reenganche activos sobre el mismo segmento, lo que ponía a cada miembro inactivo en cola para ambas secuencias. Un segundo Journey sobre un segmento es fácil de activar y difícil de notar.
* **Da a los push de Journey una URL y un `data.type`.** Las plantillas creadas en el panel no tienen ninguno de los dos por defecto, así que un toque solo abre la app. Clean Beans establece ambos en cada plantilla de Journey, para que se enruten como los push del backend. Consulta [Deep links y clics en notificaciones](https://documentation.onesignal.com/docs/es/example-full-integration-deep-links.md).
* **Un Journey activo se puede editar, y el cambio puede afectar a quienes ya están en él.** Clean Beans cambió una ventana de tiempo y añadió una espera en Journeys que estaban en marcha. Haz cambios así de forma deliberada.
* **Los mensajes de Journey cuentan en la bandeja.** Llegan por el mismo Event Stream que cualquier otro push, con su Liquid sin representar.
* **Desactiva el seguimiento de clics en un email cuyo botón sea un Universal Link.** El seguimiento reescribe los enlaces para que pasen por un dominio de seguimiento, y un enlace reescrito ya no abre la app. Consulta [Abrir la app desde enlaces web normales](https://documentation.onesignal.com/docs/es/example-full-integration-deep-links.md#open-the-app-from-ordinary-web-links).

> [card] [Descripción general de Journeys](https://documentation.onesignal.com/docs/es/journeys-overview.md)
>
> Reglas de entrada, pasos y cómo se ejecuta un Journey.

> [card] [Ajustes de Journey](https://documentation.onesignal.com/docs/es/journeys-settings.md)
>
> Quién entra, sale y vuelve a entrar.

> [card] [Acciones de Journey](https://documentation.onesignal.com/docs/es/journeys-actions.md)
>
> Wait, Wait Until, Yes/No, Split y Time Window.

> [card] [Webhooks de Journey](https://documentation.onesignal.com/docs/es/journeys-webhook.md)
>
> Llama a tu propio servidor desde un paso de Journey.

> [card] [Personalizar con eventos personalizados](https://documentation.onesignal.com/docs/es/personalization-custom-event.md)
>
> Usa propiedades de eventos en los mensajes de Journey.

> [card] [Journeys basados en eventos](https://documentation.onesignal.com/docs/en/event-driven-journeys.md)
>
> Diseña Journeys que respondan al comportamiento.


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