​

概述

订阅代表用户可以通过其接收消息的特定渠道——例如电子邮件地址、电话号码或设备。OneSignal 支持四种类型的订阅：

• 电子邮件 – 用于发送电子邮件消息
• SMS – 用于发送文本消息
• 网络推送 – 用于通过网络浏览器发送推送通知
• 移动 – 用于在移动设备上发送推送通知、应用内消息和实时活动

每个用户可以有多个订阅。使用 External ID 来在所有订阅中识别用户。 在上面的图像中，userA 有 5 个订阅：

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

---

​

订阅属性

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

属性	描述
渠道	订阅类型：Email、SMS 或 Push。Push 可以是移动（iOS、Android 等）或网络。只有移动推送订阅支持应用内消息。
订阅 状态	表示订阅是否可以接收消息。更多详情参见 订阅状态。
最后 会话	OneSignal SDK 跟踪的最后一次会话的时间戳。对于电子邮件/SMS，它基于最新的推送订阅。
使用 持续时间	OneSignal SDK 跟踪的订阅在应用或网站上活跃的总时间（以秒为单位）。只有当会话超过 60 秒时才会跟踪。
会话	应用/网站被打开的次数统计。在失焦超过 30 秒后开始新会话。
首次 会话	用户的第一个订阅创建时的时间戳。
IP 地址	使用 OneSignal SDK 时的网络位置。在欧盟不收集。参见 处理个人数据。
订阅 ID	代表特定订阅的 UUID。用于识别订阅。
OneSignal ID	代表用户的 UUID。参见 用户。
External ID	您的自定义用户 ID。帮助将多个订阅链接到同一用户。
电子邮件	仅为电子邮件订阅设置。
电话 号码	仅为 SMS 订阅设置。必须为 E.164 格式。
应用 版本	来自 SDK：Android versionCode，iOS CFBundleShortVersionString。
SDK 版本	使用的 OneSignal SDK 版本。参见 GitHub > SDKs (选择您的 SDK) > Releases。
时区 ID	来自最后一次交互时的设备。
国家	从 IP 地址派生。
位置 点	如果启用了位置跟踪的纬度/经度。参见 基于位置的通知。
语言 代码	来自订阅创建时的设备。参见 多语言消息。
标签	自定义键值元数据。参见 标签。
推送 Token	用于推送传递的平台令牌（例如 APNS 或 FCM）。仅用于推送订阅。 - iOS 推送 APNS token 格式: 64 个字符，仅十六进制字符 (0-9,a-f)。 - Android 推送 FCM token 格式: 通常 163 个字符，字母数字字符，可能包含连字符、冒号和下划线。
Root 权限	表示 Android 设备是否已获取 root 权限（越狱）。

​

订阅状态

通常，订阅可以接收消息（已订阅）或不能接收消息（已取消订阅）。但是，有一些例外： 移动订阅

• 已订阅：用户已授权接收推送通知。
  • 如果您启用了 iOS 临时推送，那么所有 iOS 移动订阅都是已订阅状态，直到用户禁用。
• 已取消订阅：订阅无法接收推送通知，但可以接收应用内消息。
  • 更多详情参见 处理卸载、取消订阅和无效推送令牌。
• 从未订阅 – 用户从未授权（与已取消订阅相同）。

网页订阅

• 已订阅：用户已授权接收推送通知。
• 已取消订阅：订阅无法接收推送通知。
  • 更多详情参阅处理取消订阅和无效推送令牌。

邮件订阅

• 已订阅：用户应该已同意接收邮件消息且邮件地址有效。
• 已取消订阅：用户选择不接收邮件，但如需要可以覆盖。
  • 更多详情参阅邮件订阅。

短信订阅

• 已订阅：用户应该已同意接收短信消息且电话号码有效。
• 已取消订阅：用户选择不接收短信消息。
  • 更多详情参阅短信订阅。

---

​

notification_types

表示订阅接收消息的能力，包括失败的原因。通过我们的前端 SDK 自动更新或通过 API 手动更新。可通过查看用户 API或导出 CSV查看。

通知类型定义。

1 or positive number = 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.

• Check the logcat. See Getting a Debug Log.
• Upgrade your Google Play Services Library in your app and check the app’s logcat for Google Play Services errors. See Getting a Debug Log.

-6 = Android Invalid Google Project Number.

• The FCMv1 Sender ID doesn’t match the original in which this token belongs. Check the app’s logcat. See Getting a Debug Log.

-7, -9 = Android Outdated Google Play Services App

• 在设备上更新或启用 Google Play 服务应用。

-10 = Not Subscribed.

• 推送订阅已卸载应用或在设备设置中取消订阅。
• 网页推送屏蔽通知、清除所有数据和工作程序。

-13 = iOS missing_push_capability.

• Review the SDK setup docs to make sure all steps are implemented. See Channel setup.

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

• Permission was revoked.

-23, -24 = Web Service Worker Error.

• See Web SDK troubleshooting.

-31 = Disabled via REST API.-98 = 短信订阅等待双重选择加入。

---

​

移动订阅

移动订阅代表 iOS、Android、华为或亚马逊设备，并支持：

• 推送通知
• 应用内消息
• 实时活动

当用户使用 OneSignal SDK 安装并打开您的应用时，它们会自动创建。

​

更新移动订阅

建议通过 OneSignal 移动 SDK 更新移动订阅属性。

• 提示推送权限并观察权限/订阅变化
• Login users to set External ID and Aliases
• 添加标签
• 设置语言

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

​

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

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

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

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

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

Track changes via:

• Event Streams - detect unsubscribes when sending push
• Push reports - detect unsubscribes when sending push
• Use the SDK’s subscription change listener - detect unsubscribes when user disables push in device settings then opens the app

---

​

网络推送订阅

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

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

​

更新网页推送订阅

建议通过 OneSignal 网页 SDK 更新网页推送订阅属性。

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

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

​

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

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

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

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

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

Track changes via:

• Event Streams - detect unsubscribes when sending push
• Push reports - detect unsubscribes when sending push
• Use the SDK’s subscription change listener - detect unsubscribes when user disables push then returns to the site

---

​

电子邮件订阅

邮件订阅基于邮件地址，仅用于邮件投递。这与设置标签不同。 Create Email subscriptions via:

1. SDK addEmail method or email prompt - use these methods after calling OneSignal.login to set the External ID and link the subscription to the user.
2. Create user API or Create email API
3. Dashboard CSV Importer or manually add email addresses

​

管理邮件订阅

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

• Using the SDK, call the login method before calling addEmail to set the external_id and link the email subscription to the user.
• Using the CSV Importer or REST API, set the external_id identifier with the email.

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

• Sending emails, the user opts-out via the Unsubscribe link
• Setting enabled to false via the API
• 使用仪表板通过选项按钮取消订阅订阅 邮件订阅可以通过以下方式重新订阅：
• Setting enabled to true via the API
• 使用仪表板通过选项按钮订阅订阅

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

---

​

SMS 订阅

SMS subscriptions are tied to E.164 formatted phone numbers. Created via:

1. SDK addSms or SMS prompt - use these methods after calling OneSignal.login to set the External ID and link the subscription to the user.
2. Create user or Create SMS API
3. CSV Importer

​

管理短信订阅

• User replies with “STOP”
• Update Subscription via API

---

​

导入或迁移订阅

Import push tokens, email addresses, and phone numbers from another provider using:

• Create user API
• Create subscription API

---

​

删除订阅

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

• Data privacy
• 清理非活跃记录

See Delete users for details.

---

​

常见问题

​

推送订阅状态何时更新？

推送订阅状态更新时机：

1. 当用户打开应用时，OneSignal SDK 将检查推送令牌是否有效以及是否授予通知权限，然后相应地更新订阅状态。

• 您可以使用我们的 SDK 订阅观察器方法捕获此事件并发送到您的数据库。

2. 在向订阅发送2+ 条通知后。使用事件流在发送消息时检测取消订阅。

Example:

• 消息 1：已投递。用户在设备上接收，然后用户在设备设置中取消订阅。
• 消息 2：已投递（但设备未接收）。
• 消息 3：失败（标记为已取消订阅）
• 消息 4：未发送给订阅。

​

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

当用户在设备设置中关闭通知时，他们在该设备上就不能再接收推送通知了。 在向设备发送通知后，他们将被标记为已取消订阅。请参阅推送订阅状态何时更新？以获取更多详情。

---