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

# Example app: reliable, well-behaved push

> How the Clean Beans example app prevents duplicate pushes with idempotency keys, tunes delivery for each push type, and sets app icon badges.

This page is part of [Example app: a full OneSignal integration](https://documentation.onesignal.com/docs/en/example-full-integration-overview.md), which follows one real app from end to end. The app is **Clean Beans**, a cleaning rota for shared homes, built with Expo (React Native) and a Supabase backend.

Getting a push to arrive is the first step. This page covers the smaller decisions that make pushes trustworthy: never sending the same one twice, letting stale ones expire, and making each type behave in a way that suits it.

## Never send the same reminder twice

Scheduled jobs get retried. A job can also be run twice by mistake. Without protection, each repeat sends another push.

OneSignal's `idempotency_key` solves this. If two requests carry the same key, the second is not sent. The key must be a UUID, and OneSignal remembers it for 30 days.

A scheduled function has nowhere to keep a random key between runs, so Clean Beans derives the key from what the send is: its type, its recipient, and its date. The same send always produces the same key.

```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 | Key is built from | Result |
| - | - | - |
| Daily digest | type, user ID, the user's local date | One digest per user per day |
| Overdue reminder | type, user ID, the user's local date | One reminder per user per day |
| Cleaning reminder | type, the hour, the sorted recipient IDs | One reminder per batch per hourly run |
| Weekly email | type, household ID, the run date | One email per household per run |
| Join approved | type, user ID, household ID, approval time | One push per approval |

For a batched send, the key covers the whole batch.

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

> [!NOTE]
>
> Idempotency keys work on the Create message and Create custom events endpoints. Live Activity requests do not accept them. Those are identified by their `activity_id` instead.

## Give each type of push its own behavior

A cleaning reminder that arrives two hours late is worse than no reminder. Kudos are nice to receive but never urgent. Clean Beans describes these differences once, in a set of delivery profiles, and spreads the right one into each request.

```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 | Kept for an offline device | Grouped under | iOS interruption level | Relevance |
| - | - | - | - | - |
| Daily digest | 6 hours | `tasks` | Active | 0.6 |
| Overdue reminder | 6 hours | `tasks` | Active | 0.8 |
| Cleaning reminder | 1 hour | `schedule` | Time Sensitive | 0.9 |
| Session completed | 24 hours | `household` | Active | 0.4 |
| Kudos | 3 days | `household` | Passive | 0.7 |
| Join approved | 3 days | `household` | Active | 0.8 |

The `member_lapsed` profile in the type list belongs to a push sent from a Journey webhook, which this guide does not cover.

What each setting does:

* **`ttl`** is how long a push is held for a device that is offline. The cleaning reminder says "in 1 hour", so it is dropped after an hour.
* **`thread_id`** and **`android_group`** group related pushes together in the notification list.
* **`ios_interruption_level`** controls how insistent a push is. `time_sensitive` can break through Focus modes. `passive` arrives silently.
* **`ios_relevance_score`** ranks pushes in the iOS notification summary. Clean Beans keeps `1.0` for critical messages, and sends none.

**App setup.** iOS only honors `time_sensitive` if the app declares the capability.

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

> [!WARNING]
>
> **A lesson learned: `collapse_id`.** Clean Beans first gave the digest and the overdue reminder the same `collapse_id`, so the reminder would replace the digest. On iOS, a push that replaces one still in the notification list is swapped in place, with no banner and no sound. The reminder went unnoticed, which defeated its purpose, so the setting was removed. Use `collapse_id` only when a silent update is what you want, such as a live score.

## Show a count on the app icon

The two task pushes set the app icon badge to the number in their heading.

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

![The Clean Beans app icon with a badge count](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-badge.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=08c9bc46b557e4e15819cd0ec42488cf)

The app icon badge shows how many tasks are overdue.

`SetTo` is used, not `Increase`, because the badge is a count of tasks and not a count of unread notifications. The afternoon reminder replaces the morning number.

> [!NOTE]
>
> The OneSignal SDK clears the badge automatically whenever the app is opened, so the app needs no code to reset it. A push that arrives while the app is open never shows its badge. Android has no numeric badge to set through the API.

> [card] [Idempotent requests](https://documentation.onesignal.com/reference/idempotent-notification-requests.md)
>
> How keys work and how long they last.

> [card] [Interruption levels](https://documentation.onesignal.com/docs/en/ios-focus-modes-and-interruption-levels.md)
>
> Focus modes and the four levels.

> [card] [Badges](https://documentation.onesignal.com/docs/en/badges.md)
>
> Badge behavior on each platform.


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