> ## 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 中管理移动推送、网络推送、电子邮件和 SMS 的订阅。涵盖属性、状态以及如何更新或迁移订阅。
## 概述
**订阅**代表用户可以通过其接收消息的特定渠道——例如电子邮件地址、电话号码或设备。OneSignal 支持四种类型的订阅：
| 订阅类型 | 可接收 |
| ------------ | ----------------- |
| **Email** | 电子邮件消息 |
| **SMS** | 短信、彩信和 RCS 消息 |
| **Web Push** | 网络推送通知 |
| **Mobile** | 移动推送通知、应用内消息和实时活动 |
每个用户可以有多个订阅。使用 [External ID](./users#external-id) 来在所有订阅中识别用户。
在上面的图像中，"userA" 有 5 个订阅：
1. **移动**（iOS）在安装 iOS 应用后创建。调用 `OneSignal.login` 设置 External ID 并将订阅链接到用户。
2. **SMS** 在 iOS 应用内提供电话号码后创建。详情参见下方 [SMS 订阅](#sms-subscriptions)。
3. **网络推送**在网站上订阅推送后创建。可以接收推送通知。
4. **电子邮件**在提供电子邮件地址后创建。用于发送电子邮件消息。
5. **移动**（Android）在安装 Android 应用后创建。可以接收推送通知、应用内消息和实时活动。
一个用户最多可以有 20 个订阅。如果添加第 21 个，OneSignal 会从最旧的订阅（基于最后一次会话）中移除 External ID 并为其分配一个新的 OneSignal ID——有效地为非活跃订阅创建一个新的匿名用户。
但是，OneSignal 确保至少保留 3 个电子邮件订阅和 3 个 SMS 订阅（如果适用）。
详情参见 [Users](./users)。
***
## 订阅属性
每个订阅都具有以下属性：
| 属性 | 描述 |
| :--------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **渠道** | 订阅类型：`Email`、`SMS` 或 `Push`。Push 可以是移动（iOS、Android 等）或网络。只有移动推送订阅支持应用内消息。 |
| **订阅 状态** | 表示订阅是否可以接收消息。更多详情参见[订阅状态](#subscription-statuses)。 |
| **最后 会话** | OneSignal SDK 跟踪的最后一次会话的时间戳。对于电子邮件/SMS，它基于最新的推送订阅。 |
| **使用 时长** | OneSignal SDK 跟踪的订阅在应用或网站上活跃的总时间（以秒为单位）。只有当会话超过 60 秒时才会跟踪。 |
| **会话** | 应用/网站被打开的次数统计。在失焦超过 30 秒后开始新会话。 |
| **首次 会话** | 用户的第一个订阅创建时的时间戳。 |
| **IP 地址** | 使用 OneSignal SDK 时的网络位置。在欧盟不收集。参见[处理个人数据](./handling-personal-data)。 |
| **订阅 ID** | 代表特定订阅的 UUID。用于识别订阅。 |
| **OneSignal ID** | 代表用户的 UUID。参见 [Users](./users)。 |
| **External ID** | 您的自定义用户 ID。帮助将多个订阅链接到同一用户。 |
| **设备** | 创建订阅时使用的设备型号。例如，网络推送浏览器的 `armv81` 表示 Android 设备。 |
| **电子邮件** | 仅为电子邮件订阅设置。 |
| **电话 号码** | 仅为 SMS 订阅设置。必须为 [E.164 格式](https://en.wikipedia.org/wiki/E.164)。 |
| **应用 版本** | 来自 SDK：Android `versionCode`，iOS `CFBundleShortVersionString`。 |
| **SDK 版本** | 使用的 OneSignal SDK 版本。参见 [GitHub > SDKs（选择您的 SDK）> Releases](https://github.com/OneSignal/sdks)。 |
| **时区 ID** | 来自最后一次交互时的设备。 |
| **国家** | 从 IP 地址派生。 |
| **位置 点** | 如果启用了位置跟踪的经纬度。参见[基于位置触发的通知](./location-triggered-event)。 |
| **语言 代码** | 来自订阅创建时的设备。参见[多语言消息](./multi-language-messaging)。 |
| **标签** | 自定义键值元数据。参见[标签](./add-user-data-tags)。 |
| **推送 Token** | 用于推送传递的平台令牌（例如 APNS 或 FCM）。仅用于推送订阅。
- **iOS 推送 APNS token 格式**：64 个字符，仅十六进制字符 (0-9,a-f)。
- **Android 推送 FCM token 格式**：通常 163 个字符，字母数字字符，可能包含连字符、冒号和下划线。 |
| **已 Root** | 表示 Android 设备是否已获取 root 权限（越狱）。 |
### 订阅状态
通常，订阅可以接收消息（**已订阅**）或不能接收消息（**已取消订阅**）。各渠道的具体情况如下：
| 状态 | 移动 | 网络推送 | 电子邮件 | SMS |
| --------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- |
| **已订阅** | 用户已授予推送权限。使用 [iOS 临时推送](./ios-provisional-push-notifications) 时，所有 iOS 订阅初始状态为已订阅。 | 用户在浏览器权限提示中点击了"允许"。 | 电子邮件地址有效且用户已同意。 | 电话号码有效且用户已同意。 |
| **已取消订阅** | 无法接收推送，但**仍可接收应用内消息**。参见[处理卸载与无效令牌](#handling-uninstalls-unsubscribes--invalid-push-tokens)。 | 无法接收推送。参见[处理取消订阅与无效令牌](#handling-unsubscribes--invalid-push-tokens)。 | 用户通过[退订链接](./unsubscribe-links-email-subscriptions)选择退出。可为事务性邮件[覆盖](./email-messaging#send-to-unsubscribed-users)。 | 用户回复"STOP"或其他[退出关键字](./sms-consent-keyword-management)。 |
| **从未订阅** | 用户从未被提示或从未授予权限。 | 用户从未被提示或屏蔽了提示。 | N/A | N/A |
在 API 中，`invalid_identifier: true` 表示已取消订阅。查看 `notification_types` 了解更多详情。
***
### `notification_types`
表示订阅接收消息的能力，包括失败的原因。通过前端 SDK 自动更新或通过 API 手动更新。可通过[查看用户 API](/reference/view-user) 或[导出 CSV](/reference/csv-export) 查看。
`1` 或正数 = Subscribed.
* 订阅可以通过此渠道接收消息。
* 如果您代表用户启用消息，可以与 `enabled` 属性一起使用。对于推送订阅，仍必须设置有效的 `token` 才能接收推送通知。详情请参阅 SDK 设置文档。
`0`, `-99` = Never Subscribed.
* 订阅尚未订阅此渠道。
`-2` = Unsubscribed.
* 订阅无法通过此渠道接收消息。
* 如果您代表用户关闭消息，可以与设置为 `false` 的 `enabled` 属性一起使用。关闭消息权限时的推荐值。
* 当用户取消订阅时自动设置。
`-3`, `-5` = Android `Support Library Error`.
添加或更新您应用的 [Android Support Library](https://developers.google.com/android/)。
`-4`, `-8`, `-11`, `-12` = Android `Google Play Services Library Error`.
* 检查 logcat。参见[获取调试日志](./capturing-a-debug-log)。
* 在您的应用中升级 [Google Play Services Library](https://developers.google.com/android/)，并检查应用的 logcat 中的 Google Play 服务错误。参见[获取调试日志](./capturing-a-debug-log)。
`-6` = Android `Invalid Google Project Number`.
* FCMv1 Sender ID 与此 `token` 所属的原始 ID 不匹配。检查应用的 logcat。参见[获取调试日志](./capturing-a-debug-log)。
`-7`, `-9` = Android `Outdated Google Play Services App`
* 在设备上更新或启用 Google Play 服务应用。
`-10` = Not Subscribed.
* 推送订阅已卸载应用或在设备设置中取消订阅。
* 网络推送屏蔽了通知、清除了所有数据和 Service Worker。
`-13` = iOS `missing_push_capability`.
* 检查 SDK 设置文档，确保所有步骤均已实施。参见[渠道设置](./channel-setup)。
`-14`, `-16`, `-17` = iOS `APNS Errors`.
* 设备连接 APNS 时出现问题。查看 [iOS 故障排除](./mobile-troubleshooting)指南和[获取调试日志](./capturing-a-debug-log)。
`-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 故障排除](./troubleshooting-web-push)。
`-31` = Disabled via REST API.
`-98` = SMS 订阅等待双重选择加入。
***
## 移动订阅
移动订阅代表 iOS、Android、华为或亚马逊设备，并支持：
* 推送通知
* 应用内消息
* 实时活动
当用户使用 OneSignal SDK 安装并打开您的应用时，它们会自动创建。
每个移动订阅都绑定到创建它的设备和推送令牌。如果您的应用在同一设备上被卸载后重新安装，将生成一个新的订阅。
每次用户打开应用时调用 [`OneSignal.login`](./mobile-sdk-reference#login-external-id)，以确保设置 [External ID](./users#external-id) 并将订阅链接到用户。
### 更新移动订阅
使用 [OneSignal 移动 SDK](./mobile-sdk-reference) 更新移动订阅属性。
* [提示推送权限](./prompt-for-push-permissions)并[观察权限/订阅变化](./mobile-sdk-reference#addobserver-push-subscription-changes)
* [登录用户](./mobile-sdk-reference#login-external-id)以设置 External ID 和别名
* 添加[标签](./add-user-data-tags)
* 设置[语言](./multi-language-messaging)
您可以通过 [CSV 导入](./import)功能更新标签、语言和一些其他属性。
移动订阅也可以通过 [Users](/reference/create-user) 和 [Subscriptions](/reference/create-subscription) API 创建和更新，但对于大多数用例，建议使用移动 SDK。
### 处理卸载、取消订阅和无效推送令牌
如果用户出现以下情况，移动订阅将停止接收推送通知：
* 卸载应用
* 在设备设置中禁用推送且从未重新打开应用
* [推送令牌过期](./fcm-expired-token-faq)
在这些情况下，在发送推送通知时，订阅状态将设置为**已取消订阅**。请参阅下方[推送订阅状态何时更新？](#when-do-push-subscription-statuses-update)了解更多详情。
* 如果用户在同一设备或新设备上重新安装应用，将创建一个新的订阅，他们需要重新订阅才能接收消息。
* 如果用户在设备设置中重新启用推送，当他们打开应用时，订阅状态将设置为**已订阅**，推送令牌将被更新。
* 如果推送令牌过期，当用户在同一设备上打开应用时，订阅状态和新的推送令牌将被更新。
通过以下方式追踪变化：
* [事件流](./event-streams) - 在发送推送时检测取消订阅
* [推送报告](./push-notification-message-reports) - 在发送推送时检测取消订阅
* 使用 SDK 的[订阅变化监听器](./mobile-sdk-reference#addobserver-push-subscription-changes) - 当用户在设备设置中禁用推送后打开应用时检测取消订阅
***
## 网络推送订阅
网络推送订阅绑定到特定的设备、浏览器和浏览器配置文件。在 Chrome 桌面端订阅的用户不会在 Chrome 移动端接收推送，除非他们也从该移动设备订阅您的网站——从而创建一个单独的网络推送订阅。
在以下情况下会创建新的网络推送订阅：
* 用户通过在浏览器系统级[原生权限提示](./permission-requests)上点击"允许"来订阅您的网站。这将生成一个唯一的推送令牌和订阅 ID。
* 用户清除浏览器数据（历史记录、缓存、Cookie、本地存储）并重新访问您的网站。这将导致创建一个新的唯一订阅 ID。
网络推送订阅 ID 永远不会更改。但是，如果用户清除浏览器数据并返回网站，或在不同的浏览器/浏览器配置文件上订阅，将创建新的订阅 ID。
每次用户打开网站时或在[订阅变化监听器](./web-sdk-reference#addeventlistener-push-subscription-changes)中调用 [`OneSignal.login`](./web-sdk-reference#login-external-id)，以确保设置 [External ID](./users#external-id) 并将订阅链接到用户。
### 更新网络推送订阅
使用 [OneSignal 网络 SDK](./web-sdk-reference) 更新网络推送订阅属性。
* [提示推送权限](./permission-requests)并[观察权限/订阅变化](./web-sdk-reference#addeventlistener-push-subscription-changes)
* [登录用户](./web-sdk-reference#login-external-id)以设置 External ID 和别名
* 添加[标签](./add-user-data-tags)
* 设置[语言](./multi-language-messaging)
您可以通过 [CSV 导入](./import)功能更新标签、语言和一些其他属性。
网络推送订阅不能通过 REST API 创建。您可以通过 [Users](/reference/update-user) 和 [Subscriptions](/reference/update-subscription) API 更新它们，但对于大多数用例，建议使用网络 SDK。
### 处理取消订阅和无效推送令牌
如果用户出现以下情况，网络推送订阅将停止接收推送通知：
* 清除浏览器数据（历史记录、缓存、Cookie、本地存储）
* 在浏览器系统设置中禁用推送
* [推送令牌过期](./fcm-expired-token-faq)
在这些情况下，在发送推送通知时，订阅状态将设置为**已取消订阅**。请参阅下方[推送订阅状态何时更新？](#when-do-push-subscription-statuses-update)了解更多详情。
* 如果用户在清除浏览器数据后返回网站，将创建一个新的订阅，如果您启用了[自动重新订阅](./web-push-setup#auto-resubscribe)，他们将自动重新订阅以接收消息。
* 如果用户在浏览器设置中重新启用推送，当他们返回网站时，订阅状态将设置为**已订阅**。
* 如果推送令牌过期，当用户返回网站时，订阅状态和新的推送令牌将被更新。
Chromium 于 2025 年 10 月发布了一篇[博客文章](https://blog.chromium.org/2025/10/automatic-notification-permission.html?m=1)，说明即将推出的变更，该变更将对参与度较低且被发送大量通知的用户**自动撤销推送权限**。用户被认定为[低参与度](https://www.chromium.org/developers/design-documents/site-engagement/)的阈值大约为 30 天不活跃。撤销时，终端用户应会直接收到来自 Chrome 的通知。
通过以下方式追踪变化：
* [事件流](./event-streams) - 在发送推送时检测取消订阅
* [推送报告](./push-notification-message-reports) - 在发送推送时检测取消订阅
* 使用 SDK 的[订阅变化监听器](./web-sdk-reference#addeventlistener-push-subscription-changes) - 当用户禁用推送后返回网站时检测取消订阅
***
## 电子邮件订阅
电子邮件订阅基于电子邮件地址，仅用于电子邮件投递。这与设置[标签](./add-user-data-tags)不同。
通过以下方式创建电子邮件订阅：
1. SDK `addEmail` 方法或[电子邮件提示](./permission-requests) - 在调用 `OneSignal.login` 后使用这些方法，以设置 External ID 并将订阅链接到用户。
2. [创建用户 API](/reference/create-user) 或[创建电子邮件 API](/reference/email)
3. 仪表板 [CSV 导入器](./import)或手动添加电子邮件地址
电子邮件在每个应用中是唯一的。删除并重新添加相同的电子邮件会创建一个新的订阅 ID。
建议在创建电子邮件订阅时包含 `external_id`，以将它们链接到[用户](./users)。
### 管理电子邮件订阅
**链接到用户**
创建电子邮件订阅时，请确保设置 `external_id` 以将它们链接到[用户](./users)。
* 使用 SDK 时，在调用 `addEmail` 之前调用 `login` 方法，以设置 `external_id` 并将电子邮件订阅链接到用户。
* 使用 CSV 导入器或 REST API 时，将 `external_id` 标识符与电子邮件一起设置。
**订阅状态**
新创建的电子邮件订阅将自动设置为**已订阅**，除非另有说明。
电子邮件订阅可能在以下情况下变为已取消订阅：
* 发送电子邮件时，用户通过[退订链接](./unsubscribe-links-email-subscriptions)选择退出
* 通过 API 将 `enabled` 设置为 `false`
* 在仪表板中通过选项按钮取消订阅该订阅
电子邮件订阅可以通过以下方式重新订阅：
* 通过 API 将 `enabled` 设置为 `true`
* 在仪表板中通过选项按钮订阅该订阅
如果用户取消订阅电子邮件，您可以将他们保持为已取消订阅状态，但通过[向已取消订阅的用户发送邮件](./email-messaging#send-to-unsubscribed-users)来发送重要邮件。
***
## SMS 订阅
SMS 订阅绑定到 [E.164 格式的电话号码](https://en.wikipedia.org/wiki/E.164)（例如 `+14155551234`）。
通过以下方式创建 SMS 订阅：
1. SDK `addSms` 方法或 [SMS 提示](./permission-requests) — 先调用 `OneSignal.login` 以设置 External ID 并将订阅链接到用户。
2. [创建用户](/reference/create-user)或[创建 SMS](/reference/sms) API
3. 仪表板 [CSV 导入器](./import)
电话号码在每个应用中是唯一的。删除后重新添加会创建一个新的订阅 ID。
创建 SMS 订阅时请包含 `external_id`，以将它们链接到[用户](./users)。
### 管理 SMS 订阅
**链接到用户**
创建 SMS 订阅时设置 `external_id`，以将它们链接到[用户](./users)。
* 使用 SDK 时，在调用 `addSms` 之前调用 `login` 方法，以设置 `external_id` 并将 SMS 订阅链接到用户。
* 使用 CSV 导入器或 REST API 时，将 `external_id` 标识符与电话号码一起设置。
**订阅状态**
新创建的 SMS 订阅自动设置为**已订阅**，除非另有说明。
SMS 订阅可能在以下情况下变为已取消订阅：
* 用户回复"STOP"或其他[退出关键字](./sms-consent-keyword-management)
* 您通过 API 将 `enabled` 设置为 `false`
* 您在仪表板中通过选项按钮取消订阅该订阅
SMS 订阅可以在以下情况下重新订阅：
* 用户回复"START"或其他[加入关键字](./sms-consent-keyword-management)
* 您通过 API 将 `enabled` 设置为 `true`
* 您在仪表板中通过选项按钮重新订阅该订阅
在未经用户同意的情况下重新订阅 SMS 订阅违反运营商合规规则（TCPA、CTIA），可能导致运营商过滤或账户暂停。
***
## 导入或迁移订阅
使用以下方式从其他提供商导入推送令牌、电子邮件地址和电话号码：
* [创建用户 API](/reference/create-user)
* [创建订阅 API](/reference/create-subscription)
从其他提供商导入推送令牌、电子邮件和电话号码。
***
## 删除订阅
订阅可以因以下原因被删除：
* 数据隐私
* 清理非活跃记录
出于隐私或清理目的删除订阅和用户数据。
在免费套餐上，18 个月或更长时间没有活动的订阅会被自动删除。
***
## 常见问题
### 推送订阅状态何时更新？
推送订阅状态通过两种机制更新：
**1. 当用户打开您的应用或网站时**
OneSignal SDK 检查推送令牌是否有效以及通知权限是否仍然被授予，然后立即更新订阅状态。
例如，如果用户在设备设置中禁用了推送通知，然后重新打开您的应用，SDK 会检测到该变化并立即将订阅标记为**已取消订阅**。
您可以使用 SDK 的订阅观察器（[移动端](./mobile-sdk-reference#addobserver-push-subscription-changes) | [网络端](./web-sdk-reference#addeventlistener-push-subscription-changes)）捕获这些变化，并将状态同步到您自己的数据库。
**2. 当您发送推送通知时**
如果用户卸载了您的应用、清除了浏览器数据或禁用了推送且**从未返回**，OneSignal 在您发送通知之前无法检测到该变化。推送服务（FCM、APNs、HMS）报告令牌无效，OneSignal 将订阅标记为**已取消订阅**。
这种检测通常需要 2 条或更多消息，因为推送服务不会立即拒绝无效令牌：
| 发送 | 发生情况 |
| ----- | ------------------------------------------------ |
| 消息 1 | 已投递到设备。用户随后在设备设置中取消订阅或卸载应用。 |
| 消息 2 | 推送服务接受消息，但设备未收到。OneSignal 报告"已投递"，因为推送服务尚未拒绝该令牌。 |
| 消息 3 | 推送服务拒绝令牌。OneSignal 将订阅标记为**已取消订阅**。 |
| 消息 4+ | OneSignal 不再尝试向此订阅投递。 |
使用[事件流](./event-streams)在发送消息时实时检测取消订阅。
如果您长时间不向所有用户发送消息，取消订阅会静默累积，并在您恢复发送时以大幅峰值出现。每月至少向所有用户发送一两次消息，以逐步检测取消订阅。更多关于取消订阅峰值的信息，参见 [FCM 过期令牌常见问题](./fcm-expired-token-faq)。
Apple 将取消订阅报告延迟 14 天以上。为保护用户隐私，Apple 不会立即报告卸载或权限撤销。如果用户在禁用推送后打开您的应用，OneSignal 会通过 SDK 立即检测到该变化。如果用户再也不打开应用，Apple 可能需要在您发送通知后数周才能报告无效令牌。
详情参见 [Apple 论坛](https://developer.apple.com/forums/thread/670868)和[技术说明](https://developer.apple.com/library/archive/technotes/tn2265/_index.html#//apple_ref/doc/uid/DTS40010376-CH1-TNTAG34)。使用仪表板或 API [删除旧订阅](./delete-users)以保持受众整洁。
### 如果用户在设备设置中关闭通知且从不再打开应用，会发生什么？
该订阅在 OneSignal 中保持**已订阅**状态，直到您向该设备发送通知。在 2 次或更多发送尝试后，推送服务报告令牌无效，OneSignal 将订阅标记为**已取消订阅**。完整流程参见上方[推送订阅状态何时更新？](#when-do-push-subscription-statuses-update)。
***
## 相关页面
OneSignal 用户模型、别名，以及用户与订阅的关系。
找到您的设备并将其标记为测试订阅，以便更轻松地进行测试。
出于隐私或清理目的删除订阅和用户数据。
从其他提供商导入推送令牌、电子邮件和电话号码。