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

# サンプルアプリ：信頼性が高く適切に動作するプッシュ

> サンプルアプリClean Beansが、べき等キーでプッシュの重複を防ぎ、プッシュの種類ごとに配信を調整し、アプリアイコンのバッジを設定する方法。

このページは、1つの実在アプリを最初から最後まで追う[サンプルアプリ：OneSignalの完全な統合](https://documentation.onesignal.com/docs/ja/example-full-integration-overview.md)の一部です。アプリは**Clean Beans**という共同生活の家のための掃除当番表アプリで、Expo（React Native）とSupabaseバックエンドで構築されています。

プッシュを届けることは最初の一歩にすぎません。このページでは、プッシュを信頼できるものにする細かな判断を扱います。同じプッシュを二度送らないこと、古くなったプッシュを期限切れにすること、そして種類ごとにふさわしい動作をさせることです。

## 同じリマインダーを二度送らない \\

スケジュールされたジョブは再試行されます。誤って2回実行されることもあります。対策がなければ、繰り返すたびにプッシュがもう1通送られます。

OneSignalの`idempotency_key`がこれを解決します。2つのリクエストが同じキーを持つ場合、2つ目は送信されません。キーはUUIDである必要があり、OneSignalは30日間記憶します。

スケジュールされた関数には、実行間でランダムなキーを保持する場所がありません。そこでClean Beansは、送信の内容、つまり種類、受信者、日付からキーを導き出します。同じ送信からは常に同じキーが生成されます。

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

| プッシュ | キーの構成要素 | 結果 |
| - | - | - |
| デイリーダイジェスト | 種類、ユーザーID、ユーザーのローカル日付 | ユーザーごとに1日1回のダイジェスト |
| 期限切れリマインダー | 種類、ユーザーID、ユーザーのローカル日付 | ユーザーごとに1日1回のリマインダー |
| 掃除リマインダー | 種類、時刻、並べ替えた受信者ID | 1時間ごとの実行につきバッチごとに1回のリマインダー |
| 週次メール | 種類、世帯ID、実行日 | 実行ごとに世帯ごとに1通のメール |
| 参加承認 | 種類、ユーザーID、世帯ID、承認時刻 | 承認ごとに1回のプッシュ |

バッチ送信では、キーはバッチ全体を対象とします。

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

> [!NOTE]
>
> べき等キーはCreate messageとCreate custom eventsのエンドポイントで機能します。Live Activityのリクエストでは受け付けられません。Live Activityは`activity_id`で識別されます。

## プッシュの種類ごとに固有の動作を与える \\

2時間遅れて届く掃除リマインダーは、届かないよりも悪い結果になります。Kudosはうれしいものですが、急ぎではありません。Clean Beansはこうした違いを一連の配信プロファイルとして一度だけ定義し、各リクエストに適切なものを展開します。

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

  // ...
};
```

| プッシュ | オフラインのデバイス向けの保持期間 | グループ | iOSの割り込みレベル | 関連度 |
| - | - | - | - | - |
| デイリーダイジェスト | 6時間 | `tasks` | Active | 0.6 |
| 期限切れリマインダー | 6時間 | `tasks` | Active | 0.8 |
| 掃除リマインダー | 1時間 | `schedule` | Time Sensitive | 0.9 |
| セッション完了 | 24時間 | `household` | Active | 0.4 |
| Kudos | 3日 | `household` | Passive | 0.7 |
| 参加承認 | 3日 | `household` | Active | 0.8 |

種類一覧にある`member_lapsed`プロファイルは、Journey Webhookから送信されるプッシュ用のもので、このガイドでは扱いません。

各設定の役割：

* **`ttl`** は、オフラインのデバイス向けにプッシュを保持する期間です。掃除リマインダーは「1時間後」と伝えるため、1時間後に破棄されます。
* **`thread_id`** と **`android_group`** は、関連するプッシュを通知一覧でまとめます。
* **`ios_interruption_level`** は、プッシュがどれだけ強く知らせるかを制御します。`time_sensitive`は集中モードを突破できます。`passive`は音を鳴らさずに届きます。
* **`ios_relevance_score`** は、iOSの通知要約でのプッシュの順位を決めます。Clean Beansは`1.0`を重大なメッセージ用に取っておき、そうしたメッセージは送信していません。

**アプリの設定。** iOSは、アプリがcapabilityを宣言している場合にのみ`time_sensitive`を適用します。

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

> [!WARNING]
>
> **得られた教訓：`collapse_id`。** Clean Beansは当初、リマインダーがダイジェストを置き換えるように、ダイジェストと期限切れリマインダーに同じ`collapse_id`を設定していました。iOSでは、通知一覧にまだ残っているプッシュを置き換えるプッシュは、バナーも音もなくその場で差し替えられます。リマインダーが気付かれず目的を果たせなかったため、この設定は削除しました。`collapse_id`は、試合のスコアのように静かな更新が必要な場合にだけ使ってください。

## アプリアイコンに件数を表示する \\

2つのタスクのプッシュは、アプリアイコンのバッジをタイトルの数に設定します。

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

![バッジの数字が付いたClean Beansのアプリアイコン](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-badge.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=08c9bc46b557e4e15819cd0ec42488cf)

アプリアイコンのバッジに期限切れのタスク数が表示されます。

バッジは未読通知の数ではなくタスクの数なので、`Increase`ではなく`SetTo`を使っています。午後のリマインダーは朝の数を置き換えます。

> [!NOTE]
>
> OneSignal SDKはアプリが開かれるたびにバッジを自動的に消去するため、アプリ側でリセットするコードは不要です。アプリが開いている間に届いたプッシュのバッジは表示されません。Androidには、APIで設定できる数値バッジはありません。

> [card] [べき等なリクエスト](https://documentation.onesignal.com/reference/idempotent-notification-requests.md)
>
> キーの仕組みと保持期間。

> [card] [割り込みレベル](https://documentation.onesignal.com/docs/ja/ios-focus-modes-and-interruption-levels.md)
>
> 集中モードと4つのレベル。

> [card] [バッジ](https://documentation.onesignal.com/docs/ja/badges.md)
>
> 各プラットフォームでのバッジの動作。


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