> ## 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: push fiable y bien comportado

> Cómo la app de ejemplo Clean Beans evita push duplicados con claves de idempotencia, ajusta la entrega para cada tipo de push y establece insignias en el icono de la app.

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.

Conseguir que llegue un push es el primer paso. Esta página trata las decisiones más pequeñas que hacen que los push sean de confianza: no enviar nunca el mismo dos veces, dejar que caduquen los que ya no sirven y hacer que cada tipo se comporte de la forma que le corresponde.

## No enviar nunca el mismo recordatorio dos veces \\

Los trabajos programados se reintentan. Un trabajo también puede ejecutarse dos veces por error. Sin protección, cada repetición envía otro push.

El `idempotency_key` de OneSignal resuelve esto. Si dos solicitudes llevan la misma clave, la segunda no se envía. La clave debe ser un UUID, y OneSignal la recuerda durante 30 días.

Una función programada no tiene dónde guardar una clave aleatoria entre ejecuciones, así que Clean Beans deriva la clave de lo que es el envío: su tipo, su destinatario y su fecha. El mismo envío produce siempre la misma clave.

```typescript supabase/functions/_shared/idempotency.ts theme={null}
/** Name-based UUID (version 5) per RFC 9562. */
export async function uuidV5(name: string, namespace: string): Promise<string> {
  const ns = uuidToBytes(namespace);
  const nameBytes = new TextEncoder().encode(name);
  const input = new Uint8Array(ns.length + nameBytes.length);
  input.set(ns);
  input.set(nameBytes, ns.length);

  const digest = new Uint8Array(await crypto.subtle.digest('SHA-1', input));
  const bytes = digest.slice(0, 16);
  bytes[6] = (bytes[6] & 0x0f) | 0x50; // version 5
  bytes[8] = (bytes[8] & 0x3f) | 0x80; // RFC variant

  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
}

export function idempotencyKey(...parts: string[]): Promise<string> {
  return uuidV5(parts.join(':'), CLEAN_BEANS_NAMESPACE);
}
```

| Push | La clave se construye a partir de | Resultado |
| - | - | - |
| Resumen diario | tipo, ID de usuario, fecha local del usuario | Un resumen por usuario y día |
| Recordatorio de tareas vencidas | tipo, ID de usuario, fecha local del usuario | Un recordatorio por usuario y día |
| Recordatorio de limpieza | tipo, la hora, los IDs de destinatarios ordenados | Un recordatorio por lote y ejecución horaria |
| Email semanal | tipo, ID del hogar, fecha de ejecución | Un email por hogar y ejecución |
| Unión aprobada | tipo, ID de usuario, ID del hogar, hora de aprobación | Un push por aprobación |

En un envío por lotes, la clave cubre todo el lote.

```typescript supabase/functions/send-cleaning-reminder/index.ts theme={null}
const batchKey = await idempotencyKey(
  'upcoming_cleaning',
  utcHourSlot(now),
  [...batch].sort().join(','),
);
```

> [!NOTE]
>
> Las claves de idempotencia funcionan en los endpoints Create message y Create custom events. Las solicitudes de Live Activity no las aceptan. Estas se identifican por su `activity_id`.

## Dar a cada tipo de push su propio comportamiento \\

Un recordatorio de limpieza que llega con dos horas de retraso es peor que no recibir ninguno. Los kudos son agradables de recibir, pero nunca urgentes. Clean Beans describe estas diferencias una sola vez, en un conjunto de perfiles de entrega, y aplica el adecuado a cada solicitud.

```typescript supabase/functions/_shared/delivery.ts theme={null}
export const DELIVERY: Record<
  'daily_digest' | 'overdue_reminder' | 'upcoming_cleaning' | 'session_completed' | 'kudos' | 'join_approved' | 'member_lapsed',
  DeliveryProfile
> = {
  // Morning digest. Expires after 6h — by then the overdue nudge has taken
  // over. Grouped with the nudge under the same thread.
  daily_digest: {
    ttl: 6 * HOUR,
    thread_id: 'tasks',
    android_group: 'tasks',
    ios_interruption_level: 'active',
    ios_relevance_score: 0.6,
  },

  // Afternoon nudge. Arrives as its own alert, grouped with the digest.
  overdue_reminder: {
    ttl: 6 * HOUR,
    thread_id: 'tasks',
    android_group: 'tasks',
    ios_interruption_level: 'active',
    ios_relevance_score: 0.8,
  },

  // "Cleaning time in 1 hour". Only meaningful until the window starts,
  // so it expires after 1h. Time-sensitive: it is tied to a time the user
  // scheduled themselves, so it may break through Focus modes.
  upcoming_cleaning: {
    ttl: 1 * HOUR,
    thread_id: 'schedule',
    android_group: 'schedule',
    ios_interruption_level: 'time_sensitive',
    ios_relevance_score: 0.9,
  },

  // ...
};
```

| Push | Se conserva para un dispositivo sin conexión | Agrupado en | Nivel de interrupción de iOS | Relevancia |
| - | - | - | - | - |
| Resumen diario | 6 horas | `tasks` | Active | 0.6 |
| Recordatorio de tareas vencidas | 6 horas | `tasks` | Active | 0.8 |
| Recordatorio de limpieza | 1 hora | `schedule` | Time Sensitive | 0.9 |
| Sesión completada | 24 horas | `household` | Active | 0.4 |
| Kudos | 3 días | `household` | Passive | 0.7 |
| Unión aprobada | 3 días | `household` | Active | 0.8 |

El perfil `member_lapsed` de la lista de tipos corresponde a un push enviado desde un webhook de Journey, que esta guía no trata.

Qué hace cada ajuste:

* **`ttl`** es el tiempo que se conserva un push para un dispositivo sin conexión. El recordatorio de limpieza dice "en 1 hora", así que se descarta pasada una hora.
* **`thread_id`** y **`android_group`** agrupan los push relacionados en la lista de notificaciones.
* **`ios_interruption_level`** controla lo insistente que es un push. `time_sensitive` puede atravesar los modos de concentración. `passive` llega en silencio.
* **`ios_relevance_score`** ordena los push en el resumen de notificaciones de iOS. Clean Beans reserva `1.0` para los mensajes críticos y no envía ninguno.

**Configuración de la app.** iOS solo respeta `time_sensitive` si la app declara la capacidad.

```json app.json theme={null}
{
  "expo": {
    "ios": {
      "entitlements": {
        "com.apple.developer.usernotifications.time-sensitive": true
      }
    }
  }
}
```

> [!WARNING]
>
> **Una lección aprendida: `collapse_id`.** Al principio, Clean Beans dio al resumen y al recordatorio de tareas vencidas el mismo `collapse_id`, para que el recordatorio sustituyera al resumen. En iOS, un push que sustituye a otro que sigue en la lista de notificaciones se reemplaza en su sitio, sin banner y sin sonido. El recordatorio pasaba desapercibido, lo que anulaba su propósito, así que se eliminó el ajuste. Usa `collapse_id` solo cuando quieras una actualización silenciosa, como un marcador en directo.

## Mostrar un número en el icono de la app \\

Los dos push de tareas establecen la insignia del icono de la app con el número de su título.

```typescript supabase/functions/send-overdue-reminders/index.ts theme={null}
// App icon badge = number of overdue tasks. The OneSignal SDK clears the
// badge automatically the next time the app is opened.
ios_badgeType: 'SetTo',
ios_badgeCount: taskCount,
```

![El icono de la app Clean Beans con un número en la insignia](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-badge.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=08c9bc46b557e4e15819cd0ec42488cf)

La insignia del icono de la app muestra cuántas tareas están vencidas.

Se usa `SetTo`, no `Increase`, porque la insignia es un recuento de tareas y no de notificaciones sin leer. El recordatorio de la tarde sustituye el número de la mañana.

> [!NOTE]
>
> El SDK de OneSignal borra la insignia automáticamente cada vez que se abre la app, así que la app no necesita código para restablecerla. Un push que llega mientras la app está abierta nunca muestra su insignia. Android no tiene una insignia numérica que se pueda establecer mediante la API.

> [card] [Solicitudes idempotentes](https://documentation.onesignal.com/reference/idempotent-notification-requests.md)
>
> Cómo funcionan las claves y cuánto duran.

> [card] [Niveles de interrupción](https://documentation.onesignal.com/docs/es/ios-focus-modes-and-interruption-levels.md)
>
> Los modos de concentración y los cuatro niveles.

> [card] [Insignias](https://documentation.onesignal.com/docs/es/badges.md)
>
> Comportamiento de las insignias en cada plataforma.


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