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

# 推送消息报告

> 推送消息报告显示投递结果、确认投递、故障诊断、点击率以及每次推送发送的每订阅受众活动。

推送消息报告帮助您跟踪每个推送通知的性能，包括投递结果、用户参与度（CTR）、设备级确认和错误诊断。

<Frame caption="推送消息报告的高级统计数据。">
  <img src="https://mintcdn.com/onesignal/0qspEXXeJ8zJbkJ-/images/docs/7fb7f716c8be4e153110e21fe514e872347188578674781fc75787cbc2f60136-Screenshot_2025-03-11_at_2.48.15_PM.png?fit=max&auto=format&n=0qspEXXeJ8zJbkJ-&q=85&s=3a0aae3f8a7376838920bd16234c6876" alt="Push message report showing delivered, clicked, and CTR metrics" width="2292" height="386" data-path="images/docs/7fb7f716c8be4e153110e21fe514e872347188578674781fc75787cbc2f60136-Screenshot_2025-03-11_at_2.48.15_PM.png" />
</Frame>

***

## 投递统计

OneSignal 将推送通知发送到**推送服务**（Google FCM、Apple APNs、华为 HMS），这些服务将通知投递到您用户的设备（订阅）。已投递、已取消订阅和失败的统计数据来自这些推送服务。[确认投递](./confirmed-delivery)和点击统计数据来自设备上的 OneSignal SDK。

| 统计指标      | 定义                                                                                           |
| --------- | -------------------------------------------------------------------------------------------- |
| **已发送**   | 从 OneSignal 成功发送到推送提供商的消息数量。                                                                 |
| **总尝试次数** | 我们尝试发送的消息数量。包括成功发送到推送提供商的消息和失败的消息。这是一个**衍生**指标，是尝试发送到提供商时的成功、失败和错误的总和。                       |
| **受众**    | 目标分段中的订阅数量。                                                                                  |
| **已投递**   | 推送服务（FCM、APNs、HMS）报告已将通知投递到的推送订阅数量。与[确认投递](./confirmed-delivery)不同，后者由设备上的 OneSignal SDK 验证。 |
| **已取消订阅** | 因卸载应用、清除浏览器数据或退出推送并且之后没有打开应用而未接收消息的推送订阅数量。                                                   |
| **失败**    | 因错误而未接收到通知的推送订阅数量。未来消息仍会尝试发送到这些订阅。                                                           |
| **已点击**   | 通知的点击数量。                                                                                     |
| **频率限制**  | 因[频率限制](./frequency-capping)设置而未发送通知的推送订阅数量。                                                 |

以下统计数据是推送消息报告特有的：

| 统计指标      | 定义                                                    |
| --------- | ----------------------------------------------------- |
| **确认投递**  | 确认接收消息的推送订阅数量。                                        |
| **剩余**    | OneSignal 端仍在队列中等待发送的通知数量。                            |
| **点击率**   | 计算公式为 `(点击数 / 已投递) * 100%`。                           |
| **确认点击率** | 计算公式为 `(点击数 / 确认投递) * 100%`。                          |
| **影响打开**  | 接收通知后发生的应用打开数量，无需点击。基于**设置 > 推送和应用内 > 影响打开**中设置的时间窗口。 |

<Note>
  有关所有渠道的详细统计定义，请参阅[统计术语表](./analytics-metrics-glossary)。
</Note>

### 失败消息故障排除

这些错误阻止了 OneSignal 向推送提供商投递消息：

| 错误                                                                                                                                                                     | 类型   | 故障排除步骤                                                                                                                            |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------- |
| **401 Unauthorized**                                                                                                                                                   | Web  | 网页推送服务器给出了不明确的 401 错误。谨慎重试——可能导致重复发送。                                                                                             |
| **404 Not Found**                                                                                                                                                      | Web  | 无效的推送订阅端点（令牌损坏）。                                                                                                                  |
| **Authentication Error**                                                                                                                                               | FCM  | 检查您的 [FCM 凭据](./android-firebase-credentials)，重新上传服务账户文件，然后重试。                                                                    |
| **[DeviceTokenNotForTopic](https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CommunicatingwithAPNs.html)** | APNs | 令牌的 Bundle ID 与您的 APNs 密钥或证书不匹配。在 [p8 令牌](./ios-p8-token-based-connection-to-apns)或 [p12 设置](./ios-p12-generate-certificates)中修复。 |
| **Expired Certificate**                                                                                                                                                | APNs | 您的 p12 证书已过期。请参阅[证书设置](./ios-p12-generate-certificates)。                                                                          |
| **FcmV1InvalidToken / Not Found**                                                                                                                                      | FCM  | 无效的推送令牌。检查 [Firebase 凭据](./android-firebase-credentials)。设备必须重新打开应用以刷新令牌。                                                         |
| **None / Missing**                                                                                                                                                     | FCM  | Firebase Cloud Messaging API 可能在您的项目中未启用。在 Firebase 控制台中激活并重试。                                                                    |
| **Permission Denied**                                                                                                                                                  | FCM  | 检查完整错误消息以了解缺少哪个权限。[更新服务账户文件的权限](./android-firebase-credentials)并重新上传至 OneSignal。                                                  |
| **SenderIdMismatch**                                                                                                                                                   | FCM  | FCM v1 发送者 ID 不匹配。验证 [Firebase 凭据](./android-firebase-credentials)。用户必须重新打开应用以获取更新的令牌。                                            |
| **[TopicDisallowed](https://developer.apple.com/documentation/usernotifications/handling-notification-responses-from-apns)**                                           | APNs | APNs 令牌不匹配。在 [p8 配置](./ios-p8-token-based-connection-to-apns)中检查您的 Team ID、Key ID 和 Bundle ID。                                    |

***

## 投递状态

| 状态       | 描述                                                     |
| -------- | ------------------------------------------------------ |
| **已投递**  | 推送服务已报告将消息投递给收件人。                                      |
| **已计划**  | 消息计划在未来投递。                                             |
| **发送中**  | 消息正在发送中。                                               |
| **队列中**  | 消息正在等待发送。                                              |
| **已取消**  | 消息被手动取消。请参阅[取消推送通知](./push#cancel-push-notifications)。 |
| **无收件人** | 发送时没有有效的受众（例如已取消订阅或不在分段中）。                             |
| **失败**   | 由于错误，OneSignal 无法发送消息。                                 |

***

## 转化

<Info>
  **即将推出** — [转化指标](/docs/cn/conversion-metrics)将在消息报告中提供。一旦可用，您将直接在每条消息的报告中看到已归因转化和影响转化。有关归因模型和设置说明，请参阅[转化指标](/docs/cn/conversion-metrics)。
</Info>

## 消息统计

消息统计图表跟踪发送后 30 天内的点击、会话和[自定义结果](./custom-outcomes)（旧版，正在被转化指标取代）。使用它来查看参与度是在投递后立即发生的还是随时间持续发生的。

<Frame caption="显示点击、会话和自定义结果随时间变化的消息统计图表。">
  <img src="https://mintcdn.com/onesignal/4HyuQPBpu-4xjmQC/images/docs/d3e4db9-Screenshot_2023-07-25_at_2.18.57_PM.png?fit=max&auto=format&n=4HyuQPBpu-4xjmQC&q=85&s=03607676051399984b2966a93216b3a7" alt="Message statistics graph showing clicks, sessions, and custom outcomes over a 30-day period" width="1364" height="993" data-path="images/docs/d3e4db9-Screenshot_2023-07-25_at_2.18.57_PM.png" />
</Frame>

<Warning>
  通过 OneSignal API 发送的消息仅保存 30 天。使用[模板分析](./template-analytics)跟踪性能随时间的变化，或[导出您的数据](./exporting-data)进行离线分析。
</Warning>

***

## 受众活动

**受众活动**报告显示每个订阅如何与特定消息互动。结果被分组到类别中，以便您可以诊断投递问题、衡量参与度、识别与特定消息相关的取消订阅，并为重新定位或导出分段受众。

<Frame caption="受众活动选项卡和表格">
  <img src="https://mintcdn.com/onesignal/DAcDCtZEGr7EAIA1/images/push/push-reports-audience-activity.png?fit=max&auto=format&n=DAcDCtZEGr7EAIA1&q=85&s=6ca39ae71008717bc4606b0633369949" alt="受众活动截图" width="2048" height="706" data-path="images/push/push-reports-audience-activity.png" />
</Frame>

<Tabs>
  <Tab title="类别">
    | 类别        | 描述            |
    | --------- | ------------- |
    | **已发送**   | 消息已发送到设备。     |
    | **确认投递**  | 投递已由设备确认。     |
    | **未确认投递** | 未收到投递确认。      |
    | **已点击**   | 用户点击了通知。      |
    | **未点击**   | 用户未点击通知。      |
    | **失败**    | 投递失败。         |
    | **已取消订阅** | 订阅在收到消息后取消订阅。 |

    每个选项卡显示该类别中的收件人数量，并允许您深入查看单个订阅记录。
  </Tab>

  <Tab title="表格列">
    | 列                       | 描述                                |
    | ----------------------- | --------------------------------- |
    | **External ID**         | 您的系统标识符（如果已设置）。                   |
    | **OneSignal ID**        | 唯一的 OneSignal 用户 ID。              |
    | **Subscription ID**     | 唯一的订阅实例（设备 + 应用/浏览器）。             |
    | **Device**              | 浏览器或操作系统类型。如果您看到 `()`，则设备已被删除。    |
    | **Subscription Status** | 当前状态（例如，已订阅、已取消订阅）。               |
    | **Sent**                | 消息发送的时间。                          |
    | **confirmed receipt**   | 设备确认投递的时间，如果没有则为 `-`。             |
    | **Clicked**             | 如果用户点击则为时间戳，否则为 `-`。              |
    | **Failed**              | 指示投递是否失败。                         |
    | **Unsubscribed**        | 指示用户在收到消息后是否取消订阅。                 |
    | **Failure message**     | 如果投递失败则为错误消息（例如，"Invalid token"）。 |
  </Tab>
</Tabs>

<Warning>
  受众活动数据仅在消息发送后的 **30 天**内可用。如果您需要保留更长时间，请导出结果。
</Warning>

### 重新定位受众

从**受众活动**视图中，您可以直接向任何类别（例如，所有未点击的用户）发送**重新定位消息**。

这使得跟进未参与的用户、重新吸引流失的用户或加强确认投递的用户的成功变得容易。

***

### 导出结果

您可以使用**导出**菜单下载受众数据：

* **选定活动** – 仅导出当前查看的选项卡（例如，所有投递失败的用户）。
* **所有活动** – 导出每个类别的完整报告。

导出允许您离线分析结果、与其他团队共享或与您的 CRM 和分析工具合并。

<Card title="导出数据" icon="file-export" href="./exporting-data">
  将消息和用户数据导出为 CSV 以进行离线分析。
</Card>

***

## 消息设置

消息设置面板显示用于发送的配置。

* **受众** - 受众的详细信息，包括：
  * 收件人总数 - 发送消息的订阅数量
  * 消息发送方式：使用的目标过滤器或分段
* **计划** - 消息开始发送的时间以及选择的每用户投递选项（如有）。
* **限流** - 任何限流、频率限制或渠道覆盖
* **消息** - 消息内容。
  * 目标平台（Android、iOS、特定浏览器）
* **高级设置** - 如优先级、生存时间和折叠 ID。
* **附加数据** - 添加到消息中的任何自定义数据。

***

## 常见问题

### 推送订阅状态何时更新？

推送订阅状态通过两种机制更新：

**1. 当用户打开您的应用或网站时**

OneSignal SDK 检查推送令牌是否有效以及是否仍然授予通知权限，然后立即更新订阅状态。

例如，如果用户在设备设置中禁用推送通知，然后重新打开您的应用，SDK 会立即检测到更改并将订阅标记为**已取消订阅**。

您可以使用 SDK 的订阅观察器（[移动端](./mobile-sdk-reference#addobserver-push-subscription-changes) | [Web 端](./web-sdk-reference#addeventlistener-push-subscription-changes)）来捕获这些更改并将状态同步到您自己的数据库。

**2. 当您发送推送通知时**

如果用户卸载了您的应用、清除了浏览器数据或禁用了推送**并且再也没有返回**，OneSignal 在您发送通知之前无法检测到这一变化。推送服务（FCM、APNs、HMS）会将令牌报告为无效，OneSignal 将订阅标记为**已取消订阅**。

这种检测通常需要 2 条或更多消息，因为推送服务不会立即拒绝无效令牌：

| 发送    | 发生情况                                            |
| ----- | ----------------------------------------------- |
| 消息 1  | 投递到设备。用户随后在设备设置中取消订阅或卸载应用。                      |
| 消息 2  | 推送服务接受消息，但设备未收到。OneSignal 报告"已投递"，因为推送服务尚未拒绝令牌。 |
| 消息 3  | 推送服务拒绝令牌。OneSignal 将订阅标记为**已取消订阅**。             |
| 消息 4+ | OneSignal 不会尝试向此订阅投递。                           |

使用 [Event Streams](./event-streams) 在发送消息时实时检测取消订阅。

<Warning>
  如果您长时间不向所有用户发送消息，取消订阅会静默累积，并在您恢复发送时显示为大幅飙升。每月至少向所有用户发送一两次消息以逐步检测取消订阅。有关取消订阅飙升的更多信息，请参阅 [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)以保持受众清洁。
</Warning>

### 为什么我的已投递数量与确认投递不匹配？

已投递反映的是推送服务（FCM、APNs）报告的内容——它接受了消息进行投递。确认投递需要设备上的 OneSignal SDK 回报，这只有在设备在线且应用处理通知时才会发生。离线设备、强制关闭应用的设备或缺少 SDK 的设备将显示为已投递但未确认。

### 受众活动数据可用多长时间？

受众活动数据自消息发送起保留 30 天。如果需要保留更长时间，请在此窗口关闭前导出结果。

***

## 相关页面

<Columns cols={2}>
  <Card title="确认投递" icon="check-double" href="./confirmed-delivery">
    设备级投递确认的工作原理以及影响确认率的因素。
  </Card>

  <Card title="统计术语表" icon="book" href="./analytics-metrics-glossary">
    所有渠道的投递、参与度和转化指标的定义。
  </Card>

  <Card title="模板分析" icon="chart-line" href="./template-analytics">
    使用模板跟踪推送通知跨发送的性能。
  </Card>

  <Card title="推送限流" icon="gauge" href="./throttling">
    控制投递速率以管理高容量发送期间的服务器负载。
  </Card>
</Columns>