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

# 示例应用：完整的 OneSignal 集成

> 跟随真实应用 Clean Beans，了解推送、应用内消息、邮件、短信、Live Activities 和 Event Streams 如何在 Expo 和 Supabase 中协同工作。

大多数 OneSignal 指南一次只讲解一个功能。本指南从头到尾跟随一个应用，展示每项消息功能是如何接入的，并附上在生产环境中运行的代码。

这个应用是 **Clean Beans**，一款面向合租家庭的打扫值日表应用。它使用 Expo（React Native）构建，并使用 Supabase 作为数据库、身份验证和后端函数。应用发送的每条消息都由 OneSignal 处理。

![Clean Beans 的三个界面：仪表板、打扫会话和每周值日表](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：仪表板、一次打扫会话和每周值日表。

## Clean Beans 的功能 \\

家庭添加房间后，应用会将其转换为一份频率合理的打扫任务清单。值日表生成器会根据每个人的可用时间，把这些任务分配到一周中。成员可以开始打扫会话、勾选任务、积累每日连续记录、互相发送 kudos，并在每周排行榜上竞争。

打扫是共同承担、反复发生且有时限的事情，因此几乎适合所有类型的消息：提醒、社交动态、倒计时、总结和指导。

## 本指南的用途 \\

您可以用它来回答三个问题：

* **哪个 OneSignal 功能适合哪项工作？** 每个页面都从应用需要完成的事情出发，再展示实现它的功能。
* **代码应该放在哪里？** 有些工作属于应用，有些属于您的后端，有些属于 OneSignal 仪表板。每个示例都会说明归属。
* **会出什么问题？** 每个页面的警告和说明记录了上线过程中学到的经验。有一个设置 `collapse_id` 曾经试用后又被移除，[可靠且表现得当的推送](https://documentation.onesignal.com/docs/cn/example-full-integration-reliable-push.md)解释了原因。

## 阅读方式 \\

本指南由一组页面组成，每个页面一个主题。您无需按顺序阅读。[SDK 设置和用户身份](https://documentation.onesignal.com/docs/cn/example-full-integration-sdk-setup.md)是其他所有内容的基础。之后的每个页面都可以独立阅读。

大多数功能都以相同的方式介绍：

1. **用户看到的内容**，通常附有截图。
2. **工作原理**，以简短的步骤说明谁做什么。
3. **代码**，摘自应用。每个代码块的标题就是它所在的文件。
4. **仪表板设置**，适用于需要在 OneSignal 中配置的功能。

限制和意外情况会在相关功能旁边以警告和说明的形式标出。

> [!NOTE]
>
> 代码是真实的，但标识符已替换为 `YOUR_ONESIGNAL_APP_ID` 和 `YOUR_PROJECT_REF` 等占位符。较长的文件已精简为关键代码行。仅包含 `// ...` 的行表示此处省略了代码。

## 各部分如何协同 \\

| 位置 | 负责的内容 | 示例 |
| - | - | - |
| **Expo 应用** | 需要设备或已登录用户的所有事情 | 初始化 SDK、请求权限、识别用户、标签、自定义事件、应用内消息触发器、处理点击 |
| **Supabase 后端** | 由计划任务或数据变化触发的所有事情 | 提醒、社交推送、每周邮件、短信验证码和邀请、启动 Live Activities、接收 Event Stream Webhook |
| **OneSignal 仪表板** | 无需发布新版本即可更改的内容和定向 | 应用内消息、邮件模板、细分、Conversion Metrics、Event Stream |

**External ID** 将三者连接在一起。Clean Beans 在登录时将其设置为 Supabase 用户 ID，因此后端可以用已存储的 ID 联系任何人。

![展示 Expo 应用、Supabase 后端和 OneSignal 仪表板的架构图](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/clean-beans-architecture.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=b6d5655991cdf5b4de0645b9d7f9cd95)

应用、后端和仪表板分别与 OneSignal 通信。External ID 将它们关联到同一个用户。

## 功能地图 \\

| 应用的需求 | OneSignal 功能 | 页面 |
| - | - | - |
| 了解每台设备属于谁 | External ID、邮件订阅 | [SDK 设置和用户身份](https://documentation.onesignal.com/docs/cn/example-full-integration-sdk-setup.md) |
| 个性化和细分 | 标签、自定义事件、Conversion Metrics | [标签、自定义事件和 Conversion Metrics](https://documentation.onesignal.com/docs/cn/example-full-integration-tags-events.md) |
| 提醒用户完成任务 | 从计划函数调用 Create message API | [从后端发送推送](https://documentation.onesignal.com/docs/cn/example-full-integration-backend-push.md) |
| 告诉室友发生了什么 | 从应用和数据库事件调用 Create message API | [从后端发送推送](https://documentation.onesignal.com/docs/cn/example-full-integration-backend-push.md) |
| 绝不重复发送提醒 | 幂等键 | [可靠且表现得当的推送](https://documentation.onesignal.com/docs/cn/example-full-integration-reliable-push.md) |
| 让每条推送表现得当 | 过期、分组、中断级别、角标 | [可靠且表现得当的推送](https://documentation.onesignal.com/docs/cn/example-full-integration-reliable-push.md) |
| 通过点击或链接打开正确的界面 | 点击监听器、深度链接、Universal Links | [深度链接和通知点击](https://documentation.onesignal.com/docs/cn/example-full-integration-deep-links.md) |
| 让用户直接在通知中操作 | 操作按钮、定时发送 | [深度链接和通知点击](https://documentation.onesignal.com/docs/cn/example-full-integration-deep-links.md) |
| 在应用内指导和提示用户 | 带触发器和自定义 HTML 的应用内消息 | [应用内消息](https://documentation.onesignal.com/docs/cn/example-full-integration-in-app-messages.md) |
| 发送每周总结 | 使用 `custom_data` 的邮件模板 | [使用 custom\_data 的每周邮件](https://documentation.onesignal.com/docs/cn/example-full-integration-weekly-email.md) |
| 证明电话号码属于该用户 | 发送到原始电话号码的短信、短信订阅 | [短信：验证码和邀请](https://documentation.onesignal.com/docs/cn/example-full-integration-sms.md) |
| 邀请尚未安装应用的人 | 发送到原始联系方式的短信和邮件 | [短信：验证码和邀请](https://documentation.onesignal.com/docs/cn/example-full-integration-sms.md) |
| 在锁屏上显示倒计时 | Live Activities | [Live Activities](https://documentation.onesignal.com/docs/cn/example-full-integration-live-activities.md) |
| 在应用中保留通知历史 | Event Streams | [使用 Event Streams 的通知收件箱](https://documentation.onesignal.com/docs/cn/example-full-integration-inbox.md) |
| 让应用设置与退订保持一致 | Event Streams（邮件事件） | [使用 Event Streams 的通知收件箱](https://documentation.onesignal.com/docs/cn/example-full-integration-inbox.md) |

## 准备工作 \\

* 一个已为 iOS 和 Android 配置推送、并已设置邮件和短信的 OneSignal 应用。请参阅[渠道设置](https://documentation.onesignal.com/docs/cn/channel-setup.md)。
* 一个使用 EAS Build 构建的 Expo 应用。OneSignal SDK 需要原生代码，因此 Expo Go 不够用。请参阅 [Expo SDK 设置](https://documentation.onesignal.com/docs/cn/react-native-expo-sdk-setup.md)。
* 您的 App ID 和一个 App API key。请参阅[密钥和 ID](https://documentation.onesignal.com/docs/cn/keys-and-ids.md)。
* 一个能按计划运行代码并响应请求的后端。Clean Beans 使用 Supabase Edge Functions 和 `pg_cron`。同样的模式适用于任何后端。

## 经过验证的原则 \\

* **先设置 External ID。** 这里几乎所有功能都依赖它。请使用后端已存储的 ID。
* **把每项工作放在合适的位置。** 应用负责设备和已登录用户。后端负责计划任务和数据变化。仪表板保存所有您希望无需发布新版本即可更改的内容。
* **发送前先检查。** 后端的每次发送都会检查用户偏好，并确认确实有值得发送的内容。
* **让计划发送可以重复执行。** 由类型、接收者和日期构成的幂等键会让重试变成无操作。
* **按类型而不是 URL 路由。** `data.type` 字段可以在界面变动时让旧通知继续正常工作。
* **验证调用方告诉您的内容。** 发送消息的函数应先在您自己的数据库中确认事实。

## 所有功能一览 \\

| 功能 | 渠道 | 触发条件 | 运行位置 | 主要文件 |
| - | - | - | - | - |
| SDK 初始化和权限 | 推送 | 应用启动 | 应用 | `app/_layout.tsx` |
| 用户身份 | 全部 | 登录和退出登录 | 应用 | `app/_layout.tsx` |
| 邮件订阅 | 邮件 | 登录 | 应用 | `src/lib/onesignalSync.ts` |
| 订阅偏好 | 推送、邮件 | 设置界面 | 应用和数据库 | `app/notification-settings.tsx` |
| 标签 | 全部 | 登录、会话、编辑资料 | 应用 | `src/lib/onesignalSync.ts` |
| 自定义事件 | 全部 | 会话开始和结束 | 应用 | `src/lib/onesignalSync.ts` |
| Conversion Metrics | 全部 | 会话结束 | 仪表板 | |
| 每日摘要 | 推送 | 每小时计划任务 | 后端 | `supabase/functions/send-daily-digest/` |
| 逾期提醒 | 推送 | 每小时计划任务 | 后端 | `supabase/functions/send-overdue-reminders/` |
| 打扫提醒 | 推送 | 每小时计划任务 | 后端 | `supabase/functions/send-cleaning-reminder/` |
| 会话完成 | 推送 | 从应用调用 | 后端 | `supabase/functions/session-completed/` |
| Kudos | 推送 | 从应用调用 | 后端 | `supabase/functions/send-kudos/` |
| 加入已批准 | 推送 | 数据库触发器 | 后端 | `supabase/functions/join-approved/` |
| 幂等发送 | 推送、邮件 | 每次计划发送 | 后端 | `supabase/functions/_shared/idempotency.ts` |
| 投递配置 | 推送 | 每条推送 | 后端 | `supabase/functions/_shared/delivery.ts` |
| 角标 | 推送 | 任务推送 | 后端 | `supabase/functions/send-daily-digest/` |
| 点击路由 | 推送 | 点击推送 | 应用 | `app/_layout.tsx` |
| 操作按钮 | 推送 | 点击推送按钮 | 后端和应用 | `supabase/functions/_shared/buttons.ts`、`src/lib/pushActions.ts` |
| 稍后提醒 | 推送 | 稍后提醒按钮 | 后端 | `supabase/functions/snooze-reminder/` |
| 链接重写 | 链接 | 从 URL 打开应用 | 应用 | `app/+native-intent.tsx` |
| Universal Links 和 App Links | 链接 | 点击网页链接 | 应用和网站 | `app.json`、`website/.well-known/` |
| 帮助浮层和引导 | 应用内 | 帮助按钮 | 应用和仪表板 | `src/components/HelpButton.tsx` |
| 推送权限预提示 | 应用内 | 仪表板受众 | 仪表板 | `docs/iam-html/push-permission-prompt.html` |
| 应用更新提示 | 应用内 | 旧版本应用 | 仪表板 | `docs/iam-html/app-update-prompt.html` |
| 评价提示 | 应用内 | 连续记录里程碑 | 应用和仪表板 | `src/lib/reviewPrompt.ts` |
| 每周报告 | 邮件 | 每周计划任务 | 后端和仪表板 | `supabase/functions/weekly-report/` |
| 短信订阅 | 短信 | 电话号码已验证、登录 | 应用 | `src/lib/phone.ts` |
| 电话验证码 | 短信 | 从应用调用 | 后端 | `supabase/functions/send-otp/`、`supabase/functions/verify-otp/` |
| 家庭邀请 | 短信、邮件 | 从应用调用 | 后端 | `supabase/functions/send-invite/` |
| 连续记录警告 | Live Activity | 每小时计划任务 | 后端和小组件 | `supabase/functions/streak-warning/` |
| 打扫提醒 | Live Activity | 每小时计划任务 | 后端和小组件 | `supabase/functions/cleaning-activity/` |
| 通知收件箱 | Event Streams | 每次推送发送或点击 | 后端和应用 | `supabase/functions/inbox-webhook/` |
| 邮件偏好同步 | Event Streams | 邮件退订、退回或被举报为垃圾邮件 | 后端 | `supabase/functions/inbox-webhook/` |

## 密钥 \\

后端函数从环境变量中读取这些值。它们都不会随应用一起发布。

```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]
>
> 您的 App API key 可以向所有用户发送消息。请将其保存在后端。应用本身只需要 App ID。


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