# 管理您的推送订阅用户群

在 Pushwoosh 中，每个订阅用户都由一个推送令牌 (push token) 标识，这是一个唯一的标识符，用于将消息投递到特定设备。本文将介绍推送令牌的工作原理以及如何在您的订阅用户群中仅保留有效令牌。

## 理解推送令牌及其工作原理

推送令牌是一个唯一的匿名标识符，由其推送服务提供商分配给设备上的特定应用实例：

*   适用于 iOS 设备的 Apple 推送通知服务 (APNs)
*   适用于 Android 设备的 Firebase 云消息传递 (FCM)

此令牌确保推送通知能够被投递到用户设备上正确的应用。

在 Pushwoosh 中，推送令牌的生命周期包括以下几个关键阶段：

1.  当应用首次启动时，它会向设备的操作系统 (OS) 请求接收推送通知的权限。

2.  应用的推送服务（例如，iOS 的 APNs，Android 的 FCM）会为该应用实例生成一个唯一的推送令牌。默认情况下，即使用户未授予通知显示权限，Pushwoosh SDK 也会收集并存储此令牌。推送消息不会显示给这些用户，但该令牌仍可用于向其应用内收件箱（Pushwoosh 中的另一个消息渠道）发送消息。

    但是，您可以将 SDK 配置为仅从已授予权限的用户那里收集令牌。

3.  应用使用 Pushwoosh SDK 通过 [`/registerDevice`](/zh/developer/api-reference/device-api/#registerdevice) API 端点将此令牌连同设备数据（包括硬件 ID 或 HWID）发送到 Pushwoosh 数据库。

4.  Pushwoosh 会安全地存储该令牌，以备将来发送消息时使用。

5.  当触发通知时，Pushwoosh 使用存储的令牌通过适当的投递网关路由消息。

6.  所选网关将消息投递到设备，操作系统会根据系统和应用通知设置显示该消息。

7.  如果推送令牌失效（例如，由于应用卸载），Pushwoosh 会在下一次发送通知后检测到投递失败，此时网关会返回发送错误列表，包括过期/无效/等的令牌。然后 Pushwoosh 会将该令牌标记为不活跃，并从数据库中删除。如果应用在同一设备上重新安装，则会颁发一个新的令牌。

### 推送令牌失效的常见原因

虽然 Apple 推送通知服务 (APNs) 和 Firebase 云消息传递 (FCM) 并未完全透明地公开令牌生命周期策略，也不允许主动验证令牌，但在一些已知场景下，推送令牌可能会失效或过期。

| 原因 | APNs (iOS) | FCM (Android) |
| :---- | ----- | ----- |
| **应用卸载** | 应用卸载后令牌失效。APNs 最终会返回一个 `410 Unregistered` 错误。Apple 没有具体说明失效发生的时间；可能需要几分钟到几天不等。[了解更多](https://developer.apple.com/forums/thread/670868) | 卸载后令牌立即失效。后续发送会返回一个 `Unregistered` 错误。[了解更多](https://help.pushwoosh.com/hc/en-us/articles/19861855131805-Sudden-increasing-of-unregistered-errors-on-the-Android-platform) |
| **令牌刷新** | 在操作系统升级、设备备份/恢复、应用重装或操作系统更新后，APNs 会颁发新令牌。[了解更多](https://developer.apple.com/documentation/usernotifications/registering-your-app-with-apns#:~:text=Never%20cache%20device%20tokens%20in%20local%20storage.%20APNs%20issues%20a%20new%20token%20when%20the%20user%20restores%20a%20device%20from%20a%20backup%2C%20when%20the%20user%20installs%20your%20app%20on%20a%20new%20device%2C%20and%20when%20the%20user%20reinstalls%20the%20operating%20system.%20You%20get%20an%20up%2Dto%2Ddate%20token%20each%20time%20you%20ask%20the%20system%20to%20provide%20the%20token.) | 与 APNs 行为相同。清除应用数据或恢复设备也会触发。[了解更多](https://firebase.google.com/docs/cloud-messaging/manage-tokens?utm_source=chatgpt.com#retrieve-and-store-registration-tokens) |
| **令牌不活跃** | 没有因不活跃而过期的文档记录。[了解更多](https://developer.apple.com/forums/thread/671310) | 超过 270 天不活跃的令牌被视为陈旧/过期。FCM 会将其标记为无效。[了解更多](https://firebase.google.com/docs/cloud-messaging/manage-tokens#stale-and-expired-tokens) |
<Aside type="caution" title="重要提示">

Pushwoosh 仅在推送通知投递失败时确定令牌的有效性。它不会主动检查令牌状态。

</Aside>


## 如何通过移除无效推送令牌来保持订阅用户列表的清洁

为了保持您的推送订阅用户列表的清洁，请定期检查投递统计数据，移除无效令牌，并确保您的应用和后端始终拥有最新的令牌数据。

Pushwoosh 提供了几种方法来帮助您实现这一目标：

### 定期向您的整个订阅用户群发送推送通知

定期向您的整个订阅用户群发送推送消息。这有助于 Pushwoosh 识别无效令牌。当消息因无效令牌而投递失败时，推送网关会返回一个错误。SDK 会捕获此响应并自动移除无效令牌，确保其在未来的发送中被排除。

> **重要提示：** 仅在发送推送时才会检查令牌的有效性。Pushwoosh 不会执行后台令牌有效性检查。

### 使用 API 注销设备
<Aside type="caution" icon="setting" title="需要开发人员协助">
通过 API 注销设备需要您的开发团队协助。请与他们分享本指南以实施该过程。
</Aside>


您可以使用 [`/bulkUnregisterDevice`](/zh/developer/api-reference/audience-api/#bulkunregisterdevice) 设备 API 方法从您的订阅用户群中移除推送令牌，例如，当用户选择退出或不再活跃时。

操作步骤如下：

1.  构建一个符合您标准的用户分群（例如，已选择退出、免费套餐用户或 X 天内不活跃的用户）。
2.  使用控制面板或 [`exportSegment`](/zh/developer/api-reference/segmentation-filters-api/#exportsegment) API 方法导出该分群。
3.  调用 [`/bulkUnregisterDevice`](/zh/developer/api-reference/audience-api/#bulkunregisterdevice) 来删除该分群中设备的推送令牌。

### 使用自动验证功能在 90 天后自动移除不活跃令牌

Pushwoosh 中的自动不活跃清理算法通过移除 90 天内未活跃用户的推送令牌，帮助您保持订阅用户列表的清洁。

它通过使用默认的 **Last Application Open** (上次应用打开) 标签来跟踪用户上次打开应用的时间。如果用户 90 天或更长时间未打开应用，他们的推送令牌将被标记为不活跃并从您的订阅用户群中移除。
<Aside type="caution" title="重要提示">
此功能默认对 2024 年 1 月 1 日或之后创建的所有账户启用。要检查您的账户是否已激活此功能或请求激活，请[联系 Pushwoosh 支持团队](https://help.pushwoosh.com/hc/en-us/requests/new/)。
</Aside>

### 使用卸载跟踪

卸载跟踪通过检测用户何时卸载您的应用，来保持您的推送订阅用户列表的准确性。这使得 Pushwoosh 能够自动移除无效令牌。
> **注意：** 卸载跟踪仅在 **iOS** 和 **Android** 上受支持。

其工作原理如下：

1.  Pushwoosh 每天向所有订阅的设备发送一次静默推送通知。这些静默通知对用户不可见，没有警报、声音或角标。
2.  每个设备都有一个由通知网关提供的唯一推送令牌。如果应用已被卸载，该令牌将失效。当静默推送失败时，网关会返回一个错误。
3.  Pushwoosh 检测到该错误并从您的订阅用户列表中移除无效令牌。



<Aside type="caution" title="重要提示">
卸载跟踪每天向所有订阅用户发送静默推送通知，这可能会增加系统负载。请确保您的基础设施能够支持此流量。该功能在支持的平台上默认启用。要禁用它，请[联系 Pushwoosh 支持团队](https://help.pushwoosh.com/hc/en-us/requests/new/)或您的客户成功经理。
</Aside>


#### 卸载跟踪的局限性

通知网关不保证静默推送的投递。这些消息可能会被网关降级处理或丢弃，这可能导致卸载检测的延迟或准确性受限。[了解更多](https://help.pushwoosh.com/hc/en-us/articles/26713265335581-Understanding-Silent-Push-Notification-Behavior-and-Limits-on-iOS)

#### 查看卸载数据

要监控卸载活动，请在您的 Pushwoosh 控制面板中导航至 **统计 > 仪表板 > 应用仪表板**。**应用卸载**图表提供了您应用卸载趋势的时间线视图。

## 删除推送令牌后可以恢复用户吗？

使用任何支持的方法删除推送令牌都是可以轻松逆转的。

当用户重新打开您的应用时：

1.  Pushwoosh SDK 会自动请求一个新的推送令牌。
2.  然后它会重新注册设备（通过 [`registerDevice`](/zh/developer/api-reference/device-api/#registerdevice)）。
3.  用户再次成为活跃订阅用户，并将在此后接收推送通知。