订阅

​

概述

订阅代表用户可以通过其接收消息的特定渠道——例如电子邮件地址、电话号码或设备。OneSignal 支持四种类型的订阅： 每个用户可以有多个订阅。使用 External ID 来在所有订阅中识别用户。 在上面的图像中，“userA” 有 5 个订阅：

1. 移动（iOS）在安装 iOS 应用后创建。调用 OneSignal.login 设置 External ID 并将订阅链接到用户。
2. SMS 在 iOS 应用内提供电话号码后创建。详情参见下方 SMS 订阅。
3. 网络推送在网站上订阅推送后创建。可以接收推送通知。
4. 电子邮件在提供电子邮件地址后创建。用于发送电子邮件消息。
5. 移动（Android）在安装 Android 应用后创建。可以接收推送通知、应用内消息和实时活动。

---

​

订阅属性

每个订阅都具有以下属性：

​

订阅状态

通常，订阅可以接收消息（已订阅）或不能接收消息（已取消订阅）。各渠道的具体情况如下：

---

​

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.

• 设备连接 APNS 时出现问题。查看 iOS 故障排除指南和获取调试日志。

-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 SDK 安装并打开您的应用时，它们会自动创建。

​

更新移动订阅

使用 OneSignal 移动 SDK 更新移动订阅属性。

• 提示推送权限并观察权限/订阅变化
• 登录用户以设置 External ID 和别名
• 添加标签
• 设置语言

您可以通过 CSV 导入功能更新标签、语言和一些其他属性。 移动订阅也可以通过 Users 和 Subscriptions API 创建和更新，但对于大多数用例，建议使用移动 SDK。

​

处理卸载、取消订阅和无效推送令牌

如果用户出现以下情况，移动订阅将停止接收推送通知：

• 卸载应用
• 在设备设置中禁用推送且从未重新打开应用
• 推送令牌过期

在这些情况下，在发送推送通知时，订阅状态将设置为已取消订阅。请参阅下方推送订阅状态何时更新？了解更多详情。

• 如果用户在同一设备或新设备上重新安装应用，将创建一个新的订阅，他们需要重新订阅才能接收消息。
• 如果用户在设备设置中重新启用推送，当他们打开应用时，订阅状态将设置为已订阅，推送令牌将被更新。
• 如果推送令牌过期，当用户在同一设备上打开应用时，订阅状态和新的推送令牌将被更新。

通过以下方式追踪变化：

• 事件流 - 在发送推送时检测取消订阅
• 推送报告 - 在发送推送时检测取消订阅
• 使用 SDK 的订阅变化监听器 - 当用户在设备设置中禁用推送后打开应用时检测取消订阅

---

​

网络推送订阅

网络推送订阅绑定到特定的设备、浏览器和浏览器配置文件。在 Chrome 桌面端订阅的用户不会在 Chrome 移动端接收推送，除非他们也从该移动设备订阅您的网站——从而创建一个单独的网络推送订阅。 在以下情况下会创建新的网络推送订阅：

• 用户通过在浏览器系统级原生权限提示上点击”允许”来订阅您的网站。这将生成一个唯一的推送令牌和订阅 ID。
• 用户清除浏览器数据（历史记录、缓存、Cookie、本地存储）并重新访问您的网站。这将导致创建一个新的唯一订阅 ID。

​

更新网络推送订阅

使用 OneSignal 网络 SDK 更新网络推送订阅属性。

• 提示推送权限并观察权限/订阅变化
• 登录用户以设置 External ID 和别名
• 添加标签
• 设置语言

您可以通过 CSV 导入功能更新标签、语言和一些其他属性。 网络推送订阅不能通过 REST API 创建。您可以通过 Users 和 Subscriptions API 更新它们，但对于大多数用例，建议使用网络 SDK。

​

处理取消订阅和无效推送令牌

如果用户出现以下情况，网络推送订阅将停止接收推送通知：

• 清除浏览器数据（历史记录、缓存、Cookie、本地存储）
• 在浏览器系统设置中禁用推送
• 推送令牌过期

在这些情况下，在发送推送通知时，订阅状态将设置为已取消订阅。请参阅下方推送订阅状态何时更新？了解更多详情。

• 如果用户在清除浏览器数据后返回网站，将创建一个新的订阅，如果您启用了自动重新订阅，他们将自动重新订阅以接收消息。
• 如果用户在浏览器设置中重新启用推送，当他们返回网站时，订阅状态将设置为已订阅。
• 如果推送令牌过期，当用户返回网站时，订阅状态和新的推送令牌将被更新。

通过以下方式追踪变化：

• 事件流 - 在发送推送时检测取消订阅
• 推送报告 - 在发送推送时检测取消订阅
• 使用 SDK 的订阅变化监听器 - 当用户禁用推送后返回网站时检测取消订阅

---

​

电子邮件订阅

电子邮件订阅基于电子邮件地址，仅用于电子邮件投递。这与设置标签不同。 通过以下方式创建电子邮件订阅：

1. SDK addEmail 方法或电子邮件提示 - 在调用 OneSignal.login 后使用这些方法，以设置 External ID 并将订阅链接到用户。
2. 创建用户 API 或创建电子邮件 API
3. 仪表板 CSV 导入器或手动添加电子邮件地址

​

管理电子邮件订阅

链接到用户 创建电子邮件订阅时，请确保设置 external_id 以将它们链接到用户。

• 使用 SDK 时，在调用 addEmail 之前调用 login 方法，以设置 external_id 并将电子邮件订阅链接到用户。
• 使用 CSV 导入器或 REST API 时，将 external_id 标识符与电子邮件一起设置。

订阅状态 新创建的电子邮件订阅将自动设置为已订阅，除非另有说明。 电子邮件订阅可能在以下情况下变为已取消订阅：

• 发送电子邮件时，用户通过退订链接选择退出
• 通过 API 将 enabled 设置为 false
• 在仪表板中通过选项按钮取消订阅该订阅 电子邮件订阅可以通过以下方式重新订阅：
• 通过 API 将 enabled 设置为 true
• 在仪表板中通过选项按钮订阅该订阅

如果用户取消订阅电子邮件，您可以将他们保持为已取消订阅状态，但通过向已取消订阅的用户发送邮件来发送重要邮件。

---

​

SMS 订阅

SMS 订阅绑定到 E.164 格式的电话号码（例如 +14155551234）。 通过以下方式创建 SMS 订阅：

1. SDK addSms 方法或 SMS 提示 — 先调用 OneSignal.login 以设置 External ID 并将订阅链接到用户。
2. 创建用户或创建 SMS API
3. 仪表板 CSV 导入器

​

管理 SMS 订阅

链接到用户 创建 SMS 订阅时设置 external_id，以将它们链接到用户。

• 使用 SDK 时，在调用 addSms 之前调用 login 方法，以设置 external_id 并将 SMS 订阅链接到用户。
• 使用 CSV 导入器或 REST API 时，将 external_id 标识符与电话号码一起设置。

订阅状态 新创建的 SMS 订阅自动设置为已订阅，除非另有说明。 SMS 订阅可能在以下情况下变为已取消订阅：

• 用户回复”STOP”或其他退出关键字
• 您通过 API 将 enabled 设置为 false
• 您在仪表板中通过选项按钮取消订阅该订阅

SMS 订阅可以在以下情况下重新订阅：

• 用户回复”START”或其他加入关键字
• 您通过 API 将 enabled 设置为 true
• 您在仪表板中通过选项按钮重新订阅该订阅

---

​

导入或迁移订阅

使用以下方式从其他提供商导入推送令牌、电子邮件地址和电话号码：

• 创建用户 API
• 创建订阅 API

---

​

删除订阅

订阅可以因以下原因被删除：

• 数据隐私
• 清理非活跃记录

---

​

常见问题

​

推送订阅状态何时更新？

推送订阅状态通过两种机制更新： 1. 当用户打开您的应用或网站时 OneSignal SDK 检查推送令牌是否有效以及通知权限是否仍然被授予，然后立即更新订阅状态。 例如，如果用户在设备设置中禁用了推送通知，然后重新打开您的应用，SDK 会检测到该变化并立即将订阅标记为已取消订阅。 您可以使用 SDK 的订阅观察器（移动端 | 网络端）捕获这些变化，并将状态同步到您自己的数据库。 2. 当您发送推送通知时 如果用户卸载了您的应用、清除了浏览器数据或禁用了推送且从未返回，OneSignal 在您发送通知之前无法检测到该变化。推送服务（FCM、APNs、HMS）报告令牌无效，OneSignal 将订阅标记为已取消订阅。 这种检测通常需要 2 条或更多消息，因为推送服务不会立即拒绝无效令牌： 使用事件流在发送消息时实时检测取消订阅。

​

如果用户在设备设置中关闭通知且从不再打开应用，会发生什么？

该订阅在 OneSignal 中保持已订阅状态，直到您向该设备发送通知。在 2 次或更多发送尝试后，推送服务报告令牌无效，OneSignal 将订阅标记为已取消订阅。完整流程参见上方推送订阅状态何时更新？。

---

​

相关页面