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

# Application d'exemple : push fiable et bien maîtrisé

> Comment l'application d'exemple Clean Beans évite les push en double avec des clés d'idempotence, adapte la livraison à chaque type de push et définit les badges de l'icône.

Cette page fait partie de [Application d'exemple : une intégration OneSignal complète](https://documentation.onesignal.com/docs/fr/example-full-integration-overview.md), qui suit une application réelle de bout en bout. L'application s'appelle **Clean Beans**, un planning de ménage pour les logements partagés, construite avec Expo (React Native) et un backend Supabase.

Faire arriver un push n'est que la première étape. Cette page couvre les décisions plus fines qui rendent les push dignes de confiance : ne jamais envoyer deux fois le même, laisser expirer ceux qui ne sont plus pertinents et donner à chaque type le comportement qui lui convient.

## Ne jamais envoyer deux fois le même rappel \\

Les tâches planifiées sont relancées. Une tâche peut aussi être exécutée deux fois par erreur. Sans protection, chaque répétition envoie un push de plus.

L'`idempotency_key` de OneSignal résout ce problème. Si deux requêtes portent la même clé, la seconde n'est pas envoyée. La clé doit être un UUID, et OneSignal la conserve pendant 30 jours.

Une fonction planifiée n'a nulle part où conserver une clé aléatoire entre deux exécutions. Clean Beans dérive donc la clé de ce qu'est l'envoi : son type, son destinataire et sa date. Le même envoi produit toujours la même clé.

```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 clé est construite à partir de | Résultat |
| - | - | - |
| Résumé quotidien | type, ID utilisateur, date locale de l'utilisateur | Un résumé par utilisateur et par jour |
| Rappel de tâches en retard | type, ID utilisateur, date locale de l'utilisateur | Un rappel par utilisateur et par jour |
| Rappel de ménage | type, l'heure, les ID des destinataires triés | Un rappel par lot et par exécution horaire |
| E-mail hebdomadaire | type, ID du foyer, date d'exécution | Un e-mail par foyer et par exécution |
| Adhésion approuvée | type, ID utilisateur, ID du foyer, heure d'approbation | Un push par approbation |

Pour un envoi par lots, la clé couvre l'ensemble du lot.

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

> [!NOTE]
>
> Les clés d'idempotence fonctionnent sur les endpoints Create message et Create custom events. Les requêtes Live Activity ne les acceptent pas. Celles-ci sont identifiées par leur `activity_id`.

## Donner à chaque type de push son propre comportement \\

Un rappel de ménage qui arrive avec deux heures de retard est pire que pas de rappel du tout. Les kudos sont agréables à recevoir mais jamais urgents. Clean Beans décrit ces différences une seule fois, dans un ensemble de profils de livraison, et applique le bon profil à chaque requête.

```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 | Conservé pour un appareil hors ligne | Regroupé sous | Niveau d'interruption iOS | Pertinence |
| - | - | - | - | - |
| Résumé quotidien | 6 heures | `tasks` | Active | 0.6 |
| Rappel de tâches en retard | 6 heures | `tasks` | Active | 0.8 |
| Rappel de ménage | 1 heure | `schedule` | Time Sensitive | 0.9 |
| Session terminée | 24 heures | `household` | Active | 0.4 |
| Kudos | 3 jours | `household` | Passive | 0.7 |
| Adhésion approuvée | 3 jours | `household` | Active | 0.8 |

Le profil `member_lapsed` de la liste des types correspond à un push envoyé depuis un webhook de Journey, que ce guide ne couvre pas.

Ce que fait chaque paramètre :

* **`ttl`** est la durée pendant laquelle un push est conservé pour un appareil hors ligne. Le rappel de ménage annonce « dans 1 heure », il est donc abandonné au bout d'une heure.
* **`thread_id`** et **`android_group`** regroupent les push liés dans la liste des notifications.
* **`ios_interruption_level`** contrôle l'insistance d'un push. `time_sensitive` peut passer outre les modes Concentration. `passive` arrive sans bruit.
* **`ios_relevance_score`** classe les push dans le résumé des notifications iOS. Clean Beans réserve `1.0` aux messages critiques et n'en envoie aucun.

**Configuration de l'application.** iOS ne respecte `time_sensitive` que si l'application déclare cette capacité.

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

> [!WARNING]
>
> **Une leçon apprise : `collapse_id`.** Clean Beans a d'abord donné au résumé et au rappel de tâches en retard le même `collapse_id`, pour que le rappel remplace le résumé. Sur iOS, un push qui en remplace un autre encore présent dans la liste des notifications est substitué sur place, sans bannière ni son. Le rappel passait inaperçu, ce qui allait à l'encontre de son objectif, et le paramètre a donc été retiré. N'utilisez `collapse_id` que lorsque vous voulez une mise à jour silencieuse, comme un score en direct.

## Afficher un nombre sur l'icône de l'application \\

Les deux push de tâches définissent le badge de l'icône de l'application sur le nombre indiqué dans leur titre.

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

![L'icône de l'application Clean Beans avec un badge numérique](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-badge.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=08c9bc46b557e4e15819cd0ec42488cf)

Le badge de l'icône de l'application indique le nombre de tâches en retard.

`SetTo` est utilisé, et non `Increase`, car le badge compte des tâches et non des notifications non lues. Le rappel de l'après-midi remplace le nombre du matin.

> [!NOTE]
>
> Le SDK OneSignal efface automatiquement le badge à chaque ouverture de l'application, l'application n'a donc besoin d'aucun code pour le réinitialiser. Un push qui arrive pendant que l'application est ouverte n'affiche jamais son badge. Android n'a pas de badge numérique que l'API puisse définir.

> [card] [Requêtes idempotentes](https://documentation.onesignal.com/reference/idempotent-notification-requests.md)
>
> Fonctionnement des clés et durée de conservation.

> [card] [Niveaux d'interruption](https://documentation.onesignal.com/docs/fr/ios-focus-modes-and-interruption-levels.md)
>
> Les modes Concentration et les quatre niveaux.

> [card] [Badges](https://documentation.onesignal.com/docs/fr/badges.md)
>
> Comportement des badges sur chaque plateforme.


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