概述
订阅代表用户可以通过其接收消息的特定渠道——例如电子邮件地址、电话号码或设备。OneSignal 支持四种类型的订阅：
每个用户可以有多个订阅。使用 External ID 来在所有订阅中识别用户。
OneSignal 仪表板受众 > 订阅页面。显示通过 External ID 与单个用户关联的多个订阅。
- 移动（iOS）在安装 iOS 应用后创建。调用
OneSignal.login设置 External ID 并将订阅链接到用户。 - SMS 在 iOS 应用内提供电话号码后创建。详情参见下方 SMS 订阅。
- 网络推送在网站上订阅推送后创建。可以接收推送通知。
- 电子邮件在提供电子邮件地址后创建。用于发送电子邮件消息。
- 移动（Android）在安装 Android 应用后创建。可以接收推送通知、应用内消息和实时活动。
一个用户最多可以有 20 个订阅。如果添加第 21 个，OneSignal 会从最旧的订阅（基于最后一次会话）中移除 External ID 并为其分配一个新的 OneSignal ID——有效地为非活跃订阅创建一个新的匿名用户。但是，OneSignal 确保至少保留 3 个电子邮件订阅和 3 个 SMS 订阅（如果适用）。详情参见 Users。
订阅属性
每个订阅都具有以下属性：订阅状态
通常，订阅可以接收消息（已订阅）或不能接收消息（已取消订阅）。各渠道的具体情况如下：在 API 中，
invalid_identifier: true 表示已取消订阅。查看 notification_types 了解更多详情。notification_types
表示订阅接收消息的能力，包括失败的原因。通过前端 SDK 自动更新或通过 API 手动更新。可通过查看用户 API 或导出 CSV 查看。
通知类型定义。
通知类型定义。
1 或正数 = Subscribed.- 订阅可以通过此渠道接收消息。
- 如果您代表用户启用消息，可以与
enabled属性一起使用。对于推送订阅，仍必须设置有效的token才能接收推送通知。详情请参阅 SDK 设置文档。
0, -99 = Never Subscribed.- 订阅尚未订阅此渠道。
-2 = Unsubscribed.- 订阅无法通过此渠道接收消息。
- 如果您代表用户关闭消息，可以与设置为
false的enabled属性一起使用。关闭消息权限时的推荐值。 - 当用户取消订阅时自动设置。
-3, -5 = Android Support Library Error.添加或更新您应用的 Android Support Library。-4, -8, -11, -12 = Android Google Play Services Library Error.- 检查 logcat。参见获取调试日志。
- 在您的应用中升级 Google Play Services Library，并检查应用的 logcat 中的 Google Play 服务错误。参见获取调试日志。
-6 = Android Invalid Google Project Number.- FCMv1 Sender ID 与此
token所属的原始 ID 不匹配。检查应用的 logcat。参见获取调试日志。
-7, -9 = Android Outdated Google Play Services App- 在设备上更新或启用 Google Play 服务应用。
-10 = Not Subscribed.- 推送订阅已卸载应用或在设备设置中取消订阅。
- 网络推送屏蔽了通知、清除了所有数据和 Service Worker。
-13 = iOS missing_push_capability.- 检查 SDK 设置文档，确保所有步骤均已实施。参见渠道设置。
-14, -16, -17 = iOS APNS Errors.-15 = iOS Simulator Error.- iOS 模拟器需要 iOS 16.4+。使用其他模拟器或设备。
-18 = Never Prompted.- 订阅从未被提示订阅。这只跟踪所需的权限提示，不包括应用内消息。
-19 = Prompted But Never Answered.- 订阅被提示但未提供答案。
-20, -21 = temp_web_record. Web, pushSubscriptionchange permission revoked-22 = Manually Unsubscribed via dashboard.- 权限已被撤销。
-23, -24 = Web Service Worker Error.- 参见 Web SDK 故障排除。
-31 = Disabled via REST API.-98 = SMS 订阅等待双重选择加入。移动订阅
移动订阅代表 iOS、Android、华为或亚马逊设备，并支持：- 推送通知
- 应用内消息
- 实时活动
每个移动订阅都绑定到创建它的设备和推送令牌。如果您的应用在同一设备上被卸载后重新安装，将生成一个新的订阅。每次用户打开应用时调用
OneSignal.login，以确保设置 External ID 并将订阅链接到用户。更新移动订阅
使用 OneSignal 移动 SDK 更新移动订阅属性。 您可以通过 CSV 导入功能更新标签、语言和一些其他属性。 移动订阅也可以通过 Users 和 Subscriptions API 创建和更新，但对于大多数用例，建议使用移动 SDK。处理卸载、取消订阅和无效推送令牌
如果用户出现以下情况，移动订阅将停止接收推送通知：- 卸载应用
- 在设备设置中禁用推送且从未重新打开应用
- 推送令牌过期
- 如果用户在同一设备或新设备上重新安装应用，将创建一个新的订阅，他们需要重新订阅才能接收消息。
- 如果用户在设备设置中重新启用推送，当他们打开应用时，订阅状态将设置为已订阅，推送令牌将被更新。
- 如果推送令牌过期，当用户在同一设备上打开应用时，订阅状态和新的推送令牌将被更新。
网络推送订阅
网络推送订阅绑定到特定的设备、浏览器和浏览器配置文件。在 Chrome 桌面端订阅的用户不会在 Chrome 移动端接收推送，除非他们也从该移动设备订阅您的网站——从而创建一个单独的网络推送订阅。 在以下情况下会创建新的网络推送订阅：- 用户通过在浏览器系统级原生权限提示上点击”允许”来订阅您的网站。这将生成一个唯一的推送令牌和订阅 ID。
- 用户清除浏览器数据（历史记录、缓存、Cookie、本地存储）并重新访问您的网站。这将导致创建一个新的唯一订阅 ID。
网络推送订阅 ID 永远不会更改。但是，如果用户清除浏览器数据并返回网站，或在不同的浏览器/浏览器配置文件上订阅，将创建新的订阅 ID。每次用户打开网站时或在订阅变化监听器中调用
OneSignal.login，以确保设置 External ID 并将订阅链接到用户。更新网络推送订阅
使用 OneSignal 网络 SDK 更新网络推送订阅属性。 您可以通过 CSV 导入功能更新标签、语言和一些其他属性。 网络推送订阅不能通过 REST API 创建。您可以通过 Users 和 Subscriptions API 更新它们，但对于大多数用例，建议使用网络 SDK。处理取消订阅和无效推送令牌
如果用户出现以下情况，网络推送订阅将停止接收推送通知：- 清除浏览器数据（历史记录、缓存、Cookie、本地存储）
- 在浏览器系统设置中禁用推送
- 推送令牌过期
- 如果用户在清除浏览器数据后返回网站，将创建一个新的订阅，如果您启用了自动重新订阅，他们将自动重新订阅以接收消息。
- 如果用户在浏览器设置中重新启用推送，当他们返回网站时，订阅状态将设置为已订阅。
- 如果推送令牌过期，当用户返回网站时，订阅状态和新的推送令牌将被更新。
电子邮件订阅
电子邮件订阅基于电子邮件地址，仅用于电子邮件投递。这与设置标签不同。 通过以下方式创建电子邮件订阅：- SDK
addEmail方法或电子邮件提示 - 在调用OneSignal.login后使用这些方法，以设置 External ID 并将订阅链接到用户。 - 创建用户 API 或创建电子邮件 API
- 仪表板 CSV 导入器或手动添加电子邮件地址
电子邮件在每个应用中是唯一的。删除并重新添加相同的电子邮件会创建一个新的订阅 ID。建议在创建电子邮件订阅时包含
external_id，以将它们链接到用户。管理电子邮件订阅
链接到用户 创建电子邮件订阅时，请确保设置external_id 以将它们链接到用户。
- 使用 SDK 时，在调用
addEmail之前调用login方法，以设置external_id并将电子邮件订阅链接到用户。 - 使用 CSV 导入器或 REST API 时，将
external_id标识符与电子邮件一起设置。
- 发送电子邮件时，用户通过退订链接选择退出
- 通过 API 将
enabled设置为false - 在仪表板中通过选项按钮取消订阅该订阅 电子邮件订阅可以通过以下方式重新订阅：
- 通过 API 将
enabled设置为true - 在仪表板中通过选项按钮订阅该订阅
SMS 订阅
SMS 订阅绑定到 E.164 格式的电话号码（例如+14155551234）。
通过以下方式创建 SMS 订阅：
电话号码在每个应用中是唯一的。删除后重新添加会创建一个新的订阅 ID。创建 SMS 订阅时请包含
external_id，以将它们链接到用户。管理 SMS 订阅
链接到用户 创建 SMS 订阅时设置external_id，以将它们链接到用户。
- 使用 SDK 时，在调用
addSms之前调用login方法，以设置external_id并将 SMS 订阅链接到用户。 - 使用 CSV 导入器或 REST API 时，将
external_id标识符与电话号码一起设置。
- 用户回复”STOP”或其他退出关键字
- 您通过 API 将
enabled设置为false - 您在仪表板中通过选项按钮取消订阅该订阅
- 用户回复”START”或其他加入关键字
- 您通过 API 将
enabled设置为true - 您在仪表板中通过选项按钮重新订阅该订阅
导入或迁移订阅
使用以下方式从其他提供商导入推送令牌、电子邮件地址和电话号码：迁移到 OneSignal
从其他提供商导入推送令牌、电子邮件和电话号码。
删除订阅
订阅可以因以下原因被删除：- 数据隐私
- 清理非活跃记录
删除用户
出于隐私或清理目的删除订阅和用户数据。
在免费套餐上，18 个月或更长时间没有活动的订阅会被自动删除。
常见问题
推送订阅状态何时更新？
推送订阅状态通过两种机制更新： 1. 当用户打开您的应用或网站时 OneSignal SDK 检查推送令牌是否有效以及通知权限是否仍然被授予，然后立即更新订阅状态。 例如，如果用户在设备设置中禁用了推送通知，然后重新打开您的应用，SDK 会检测到该变化并立即将订阅标记为已取消订阅。 您可以使用 SDK 的订阅观察器（移动端 | 网络端）捕获这些变化，并将状态同步到您自己的数据库。 2. 当您发送推送通知时 如果用户卸载了您的应用、清除了浏览器数据或禁用了推送且从未返回，OneSignal 在您发送通知之前无法检测到该变化。推送服务（FCM、APNs、HMS）报告令牌无效，OneSignal 将订阅标记为已取消订阅。 这种检测通常需要 2 条或更多消息，因为推送服务不会立即拒绝无效令牌：
使用事件流在发送消息时实时检测取消订阅。
如果您长时间不向所有用户发送消息，取消订阅会静默累积，并在您恢复发送时以大幅峰值出现。每月至少向所有用户发送一两次消息，以逐步检测取消订阅。更多关于取消订阅峰值的信息，参见 FCM 过期令牌常见问题。
如果用户在设备设置中关闭通知且从不再打开应用，会发生什么？
该订阅在 OneSignal 中保持已订阅状态，直到您向该设备发送通知。在 2 次或更多发送尝试后，推送服务报告令牌无效，OneSignal 将订阅标记为已取消订阅。完整流程参见上方推送订阅状态何时更新？。相关页面
用户
OneSignal 用户模型、别名，以及用户与订阅的关系。
测试订阅
找到您的设备并将其标记为测试订阅，以便更轻松地进行测试。
删除用户
出于隐私或清理目的删除订阅和用户数据。
迁移到 OneSignal
从其他提供商导入推送令牌、电子邮件和电话号码。