> ## 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: una integración completa de OneSignal

> Sigue una app real, Clean Beans, para ver cómo encajan push, in-app, email, SMS, Live Activities y Event Streams en Expo con Supabase.

La mayoría de las guías de OneSignal explican una función a la vez. Esta sigue una sola app de principio a fin y muestra cómo se conectó cada función de mensajería, con el código que se ejecuta en producción.

La app es **Clean Beans**, un turno de limpieza para hogares compartidos. Está creada con Expo (React Native) y usa Supabase para su base de datos, autenticación y funciones de backend. OneSignal gestiona todos los mensajes que envía la app.

![Tres pantallas de Clean Beans: el panel, una sesión de limpieza y el turno semanal](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-dashboard-session-rota.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=f8fc7eac8e69faea6aece66f73c2d820)

Clean Beans: el panel, una sesión de limpieza y el turno semanal.

## Qué hace Clean Beans \\

Un hogar añade sus habitaciones y la app las convierte en una lista de tareas de limpieza con frecuencias razonables. Un generador de turnos reparte esas tareas a lo largo de la semana para ajustarse al tiempo disponible de cada persona. Los miembros realizan sesiones de limpieza, marcan tareas, acumulan rachas diarias, se envían kudos y compiten en una clasificación semanal.

La limpieza es compartida, recurrente y con plazos, lo que la hace ideal para casi cualquier tipo de mensaje: recordatorios, novedades sociales, cuentas atrás, resúmenes y orientación.

## Por qué existe esta guía \\

Úsala para responder tres preguntas:

* **¿Qué función de OneSignal encaja con cada tarea?** Cada página parte de algo que la app necesitaba hacer y luego muestra la función que lo hace.
* **¿Dónde va el código?** Parte del trabajo corresponde a la app, parte a tu backend y parte al panel de OneSignal. Cada ejemplo indica cuál.
* **¿Qué sale mal?** Las advertencias y notas de cada página recogen lo que se aprendió al publicarlo. Un ajuste, `collapse_id`, se probó y luego se eliminó, y [Push fiable y bien comportado](https://documentation.onesignal.com/docs/es/example-full-integration-reliable-push.md) explica por qué.

## Cómo leerla \\

La guía es un conjunto de páginas, una por tema. No necesitas leerlas en orden. [Configuración del SDK e identidad del usuario](https://documentation.onesignal.com/docs/es/example-full-integration-sdk-setup.md) es la base de todo lo demás. Después, cada página es independiente.

La mayoría de las funciones se presentan de la misma manera:

1. **Lo que ve el usuario**, normalmente con una captura de pantalla.
2. **Cómo funciona**, como una breve secuencia de quién hace qué.
3. **El código**, tomado de la app. El título de cada bloque de código es el archivo del que procede.
4. **Configuración del panel**, cuando la función necesita configurarse en OneSignal.

Los límites y las sorpresas se señalan en advertencias y notas junto a la función a la que afectan.

> [!NOTE]
>
> El código es real, pero los identificadores se sustituyen por marcadores de posición como `YOUR_ONESIGNAL_APP_ID` y `YOUR_PROJECT_REF`. Los archivos largos se recortan a las líneas importantes. Una línea que solo contiene `// ...` marca dónde se omitió código.

## Cómo encajan las piezas \\

| Dónde | De qué se encarga | Ejemplos |
| - | - | - |
| **La app de Expo** | Todo lo que necesita el dispositivo o el usuario que ha iniciado sesión | Inicializar el SDK, pedir permiso, identificar al usuario, etiquetas, eventos personalizados, disparadores de mensajes in-app, gestionar toques |
| **El backend de Supabase** | Todo lo que se activa por una programación o por un cambio de datos | Recordatorios, push sociales, el email semanal, códigos SMS e invitaciones, iniciar Live Activities, recibir webhooks de Event Stream |
| **El panel de OneSignal** | Contenido y segmentación que deben cambiar sin una nueva versión | Mensajes in-app, la plantilla de email, segmentos, Conversion Metrics, el Event Stream |

El **External ID** conecta los tres. Clean Beans lo establece con el ID de usuario de Supabase al iniciar sesión, de modo que el backend puede dirigirse a cualquier persona con un ID que ya almacena.

![Diagrama de arquitectura con la app de Expo, el backend de Supabase y el panel de OneSignal](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/clean-beans-architecture.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=b6d5655991cdf5b4de0645b9d7f9cd95)

La app, el backend y el panel se comunican con OneSignal. El External ID los vincula a un mismo usuario.

## Mapa de funciones \\

| Lo que necesitaba la app | Función de OneSignal | Página |
| - | - | - |
| Saber a quién pertenece cada dispositivo | External ID, suscripción de email | [Configuración del SDK e identidad del usuario](https://documentation.onesignal.com/docs/es/example-full-integration-sdk-setup.md) |
| Personalizar y segmentar | Etiquetas, eventos personalizados, Conversion Metrics | [Etiquetas, eventos personalizados y Conversion Metrics](https://documentation.onesignal.com/docs/es/example-full-integration-tags-events.md) |
| Recordar las tareas a las personas | API de creación de mensajes desde funciones programadas | [Enviar push desde tu backend](https://documentation.onesignal.com/docs/es/example-full-integration-backend-push.md) |
| Contar a los compañeros de casa lo que ha pasado | API de creación de mensajes desde eventos de la app y de la base de datos | [Enviar push desde tu backend](https://documentation.onesignal.com/docs/es/example-full-integration-backend-push.md) |
| No enviar nunca un recordatorio dos veces | Claves de idempotencia | [Push fiable y bien comportado](https://documentation.onesignal.com/docs/es/example-full-integration-reliable-push.md) |
| Que cada push se comporte de forma adecuada | Caducidad, agrupación, niveles de interrupción, insignias | [Push fiable y bien comportado](https://documentation.onesignal.com/docs/es/example-full-integration-reliable-push.md) |
| Abrir la pantalla correcta desde un toque o un enlace | Listener de clics, deep links, Universal Links | [Deep links y clics en notificaciones](https://documentation.onesignal.com/docs/es/example-full-integration-deep-links.md) |
| Permitir actuar directamente desde una notificación | Botones de acción, entrega programada | [Deep links y clics en notificaciones](https://documentation.onesignal.com/docs/es/example-full-integration-deep-links.md) |
| Orientar y guiar a las personas dentro de la app | Mensajes in-app con disparadores y HTML personalizado | [Mensajes in-app](https://documentation.onesignal.com/docs/es/example-full-integration-in-app-messages.md) |
| Enviar un resumen semanal | Plantilla de email con `custom_data` | [Email semanal con custom\_data](https://documentation.onesignal.com/docs/es/example-full-integration-weekly-email.md) |
| Demostrar que un número de teléfono pertenece al usuario | SMS a un número de teléfono sin procesar, suscripción SMS | [SMS: códigos de verificación e invitaciones](https://documentation.onesignal.com/docs/es/example-full-integration-sms.md) |
| Invitar a personas que no tienen la app | SMS y email a contactos sin procesar | [SMS: códigos de verificación e invitaciones](https://documentation.onesignal.com/docs/es/example-full-integration-sms.md) |
| Mostrar una cuenta atrás en la pantalla de bloqueo | Live Activities | [Live Activities](https://documentation.onesignal.com/docs/es/example-full-integration-live-activities.md) |
| Guardar un historial de notificaciones en la app | Event Streams | [Bandeja de notificaciones con Event Streams](https://documentation.onesignal.com/docs/es/example-full-integration-inbox.md) |
| Mantener los ajustes de la app al día con las bajas | Event Streams (eventos de email) | [Bandeja de notificaciones con Event Streams](https://documentation.onesignal.com/docs/es/example-full-integration-inbox.md) |

## Qué necesitas \\

* Una app de OneSignal con push configurado para iOS y Android, y con email y SMS configurados. Consulta [Configuración de canales](https://documentation.onesignal.com/docs/es/channel-setup.md).
* Una app de Expo compilada con EAS Build. El SDK de OneSignal necesita código nativo, así que Expo Go no es suficiente. Consulta [Configuración del SDK de Expo](https://documentation.onesignal.com/docs/es/react-native-expo-sdk-setup.md).
* Tu App ID y una App API key. Consulta [Claves e IDs](https://documentation.onesignal.com/docs/es/keys-and-ids.md).
* Un backend que pueda ejecutar código de forma programada y en respuesta a solicitudes. Clean Beans usa Supabase Edge Functions con `pg_cron`. Los mismos patrones se aplican a cualquier backend.

## Principios que funcionaron \\

* **Establece primero el External ID.** Casi todas las funciones de esta guía dependen de él. Usa un ID que tu backend ya almacene.
* **Pon cada tarea donde corresponde.** La app gestiona el dispositivo y el usuario que ha iniciado sesión. El backend gestiona las programaciones y los cambios de datos. El panel contiene todo lo que quieras cambiar sin una nueva versión.
* **Comprueba antes de enviar.** Cada envío del backend comprueba las preferencias del usuario y confirma que hay algo que merezca la pena decir.
* **Haz que los envíos programados sean repetibles.** Una clave de idempotencia construida a partir del tipo, el destinatario y la fecha convierte un reintento en una operación sin efecto.
* **Enruta por tipo, no por URL.** Un campo `data.type` mantiene funcionando las notificaciones antiguas cuando cambian las pantallas.
* **Verifica lo que te dicen quienes llaman.** Una función que envía mensajes debe confirmar primero los datos en tu propia base de datos.

## Todas las funciones de un vistazo \\

| Función | Canal | Disparador | Se ejecuta en | Archivo principal |
| - | - | - | - | - |
| Inicialización del SDK y permiso | Push | Inicio de la app | App | `app/_layout.tsx` |
| Identidad del usuario | Todos | Inicio y cierre de sesión | App | `app/_layout.tsx` |
| Suscripción de email | Email | Inicio de sesión | App | `src/lib/onesignalSync.ts` |
| Opt-in y preferencias | Push, email | Pantalla de ajustes | App y base de datos | `app/notification-settings.tsx` |
| Etiquetas | Todos | Inicio de sesión, sesión, edición de perfil | App | `src/lib/onesignalSync.ts` |
| Eventos personalizados | Todos | Inicio y fin de sesión | App | `src/lib/onesignalSync.ts` |
| Conversion Metrics | Todos | Fin de sesión | Panel | |
| Resumen diario | Push | Programación cada hora | Backend | `supabase/functions/send-daily-digest/` |
| Recordatorio de tareas vencidas | Push | Programación cada hora | Backend | `supabase/functions/send-overdue-reminders/` |
| Recordatorio de limpieza | Push | Programación cada hora | Backend | `supabase/functions/send-cleaning-reminder/` |
| Sesión completada | Push | Llamada desde la app | Backend | `supabase/functions/session-completed/` |
| Kudos | Push | Llamada desde la app | Backend | `supabase/functions/send-kudos/` |
| Unión aprobada | Push | Disparador de base de datos | Backend | `supabase/functions/join-approved/` |
| Envíos idempotentes | Push, email | Cada envío programado | Backend | `supabase/functions/_shared/idempotency.ts` |
| Perfiles de entrega | Push | Cada push | Backend | `supabase/functions/_shared/delivery.ts` |
| Insignias | Push | Push de tareas | Backend | `supabase/functions/send-daily-digest/` |
| Enrutamiento de toques | Push | Toque en un push | App | `app/_layout.tsx` |
| Botones de acción | Push | Toque en un botón de push | Backend y app | `supabase/functions/_shared/buttons.ts`, `src/lib/pushActions.ts` |
| Recordatorio pospuesto | Push | Botón de posponer | Backend | `supabase/functions/snooze-reminder/` |
| Reescritura de enlaces | Enlaces | App abierta desde una URL | App | `app/+native-intent.tsx` |
| Universal Links y App Links | Enlaces | Toque en un enlace web | App y sitio web | `app.json`, `website/.well-known/` |
| Superposiciones de ayuda y recorridos guiados | In-app | Botón de ayuda | App y panel | `src/components/HelpButton.tsx` |
| Aviso previo de permiso de push | In-app | Audiencia del panel | Panel | `docs/iam-html/push-permission-prompt.html` |
| Aviso de actualización de la app | In-app | Versión antigua de la app | Panel | `docs/iam-html/app-update-prompt.html` |
| Solicitud de reseña | In-app | Hito de racha | App y panel | `src/lib/reviewPrompt.ts` |
| Informe semanal | Email | Programación semanal | Backend y panel | `supabase/functions/weekly-report/` |
| Suscripción SMS | SMS | Número de teléfono verificado, inicio de sesión | App | `src/lib/phone.ts` |
| Código de verificación de teléfono | SMS | Llamada desde la app | Backend | `supabase/functions/send-otp/`, `supabase/functions/verify-otp/` |
| Invitación al hogar | SMS, email | Llamada desde la app | Backend | `supabase/functions/send-invite/` |
| Aviso de racha | Live Activity | Programación cada hora | Backend y widget | `supabase/functions/streak-warning/` |
| Recordatorio de limpieza | Live Activity | Programación cada hora | Backend y widget | `supabase/functions/cleaning-activity/` |
| Bandeja de notificaciones | Event Streams | Cada push enviado o pulsado | Backend y app | `supabase/functions/inbox-webhook/` |
| Sincronización de preferencias de email | Event Streams | Email dado de baja, rebotado o marcado como spam | Backend | `supabase/functions/inbox-webhook/` |

## Secretos \\

Las funciones del backend los leen de su entorno. Ninguno se incluye nunca en la app.

```bash theme={null}
supabase secrets set ONESIGNAL_APP_ID=YOUR_ONESIGNAL_APP_ID
supabase secrets set ONESIGNAL_REST_API_KEY=YOUR_APP_API_KEY
supabase secrets set ONESIGNAL_WEEKLY_TEMPLATE_ID=YOUR_EMAIL_TEMPLATE_ID
supabase secrets set INBOX_WEBHOOK_SECRET=YOUR_SHARED_SECRET
supabase secrets set OTP_HASH_SECRET=A_LONG_RANDOM_STRING    # key for hashing SMS verification codes

# Optional
supabase secrets set ONESIGNAL_SMS_FROM=YOUR_SMS_SENDER      # if no default sender is set in the dashboard
```

> [!WARNING]
>
> Tu App API key puede enviar mensajes a todos los usuarios. Mantenla en tu backend. La app solo necesita el App ID.


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