iOS APNS 推送消息数据格式详解

iOS 推送通知 (APNs) 是 iOS 系统中不可或缺的功能，用于向用户推送信息，无论用户的应用是否在前台运行。为了正确使用 Apple 推送通知服务 (APNs)，了解推送消息数据格式至关重要。本文将详细解析 APNs 消息的 JSON 数据格式及其各部分的含义与作用。

? APNs 推送消息的基本结构

iOS APNs 推送消息数据采用 JSON 格式，包括两部分内容：

1. 消息体 (payload)：消息内容的实际部分。
2. HTTP/2 请求头部 (headers)：消息发送时的元数据。
   APNs 推送消息的 JSON 格式如下所示：

   {
   "aps": {
   "alert": {
   "title": "新消息",
   "body": "您有一条新的通知"
   },
   "badge": 1,
   "sound": "default",
   "content-available": 1
   },
   "customData": {
   "type": "message",
   "id": "12345"
   }
   }

   ? 主要字段详解

3. aps：这是推送消息的核心部分，包含 APNs 所需的标准属性。
4. alert：描述通知的内容，可以是一个字符串，也可以是一个包含 title 和 body 的对象，详细描述通知的标题和正文。
5. badge：应用程序图标上的角标数字。
6. sound：推送通知时的声音文件。可以使用 default 或自定义声音。
7. content-available：用于静默通知，设置为 1 时，系统会唤醒应用程序以执行后台任务。
8. customData：开发者自定义的额外数据，可以存放推送中需要携带的额外信息。

   ? aps 部分的详细解析

   1. alert 属性

   alert 属性是用户能直接看到的通知部分，负责定义通知的标题和正文。
   使用示例：

   "alert": {
   "title": "更新提示",
   "body": "您的应用程序有重要更新，请尽快下载。"
   }

   解释：

   • title：表示通知的标题。在 iOS 设备上，通知中心或锁屏界面中会显示这一部分。
   • body：通知的内容部分，通常包含详细的提示信息。
     简单形式：
     如果通知只有简单的一段文字，可以用一个字符串来定义 alert，例如：

     "alert": "您有一条新消息。"

     2. badge 属性

     badge 用于显示应用图标右上角的红色角标数字，用于提示用户未读消息的数量。
     示例：

     "badge": 5

     解释：

   • 数字 5 会显示在应用图标的右上角，提醒用户应用中有 5 条未处理的内容。

     3. sound 属性

     sound 属性用于指定通知到达时播放的声音，可以是 default，也可以是自定义的音频文件名。
     示例：

     "sound": "default"

     解释：

   • 设置为 default 时，会使用系统默认通知声音。
   • 如果指定了自定义声音，则需确保该文件已包含在应用的资源中。
     

     4. content-available 属性

     content-available 是一个重要属性，主要用于 静默通知。当值为 1 时，应用程序会在后台被唤醒，以便处理一些非可视化的任务，例如同步数据。
     示例：

     "content-available": 1

     解释：

   • 当值为 1 时，推送将是静默通知，即不会向用户显示弹窗或声音，但应用会在后台运行来执行任务。
     适用场景：
   • 更新数据：例如获取最新的聊天消息或更新数据以保持用户应用内容的同步。

     5. mutable-content 属性

     mutable-content 属性用于 iOS 10 及以上版本的 通知服务扩展，允许在通知到达时对通知内容进行修改，例如在通知中加入图像或视频。
     示例：

     "mutable-content": 1

     解释：

   • 当值为 1 时，表示该通知可以通过扩展进行修改。例如，可以下载一个图像来丰富通知的内容。
     

     ? 自定义数据部分

     customData 是开发者在推送中添加的自定义信息。它可以用来携带应用特定的数据，例如消息的类型、ID 或者其他需要在客户端解析的内容。
     示例：

     "customData": {
     "type": "promotion",
     "id": "7890"
     }

     解释：

   • type 和 id 都是开发者自定义的数据，服务器推送时可以根据需要添加不同的内容，以便客户端处理。
     应用场景：
   • 当应用需要根据推送的类型来决定打开哪个页面时，自定义数据显得尤为重要。
     

     ? APNs 数据格式解析图

     graph TD
     A[APNs 推送消息] --> B[aps 部分]
     A --> C[自定义数据部分]
     B --> D[alert - 标题和内容]
     B --> E[badge - 角标数量]
     B --> F[sound - 提示声音]
     B --> G[content-available - 静默通知]
     B --> H[mutable-content - 通知扩展]
     C --> I[customData - 开发者自定义信息]

     ? APNs 推送消息的几种类型

     APNs 通知可以分为可见通知和静默通知，根据不同场景选择不同的实现方式。

     1. 可见通知

     可见通知包含用户可以看到的内容，通常会有 alert、badge 和 sound。
     示例：

     {
     "aps": {
     "alert": {
     "title": "重要提示",
     "body": "请及时查看最新活动信息。"
     },
     "badge": 3,
     "sound": "default"
     }
     }

     解释：

   • 该通知将显示一个标题为 “重要提示” 的弹窗，同时应用角标会显示 3，并播放默认提示音。
     

     2. 静默通知

     静默通知不会在界面上显示任何内容，而是用来在后台执行任务，例如数据更新。
     示例：

     {
     "aps": {
     "content-available": 1
     },
     "customData": {
     "task": "sync"
     }
     }

     解释：

   • content-available: 1 表示这是一个静默通知。
   • customData 部分的 task 为 “sync”，表示应用应该在后台进行数据同步。

     ? 数据字段间的相互关系

     为了更好地理解推送消息中的各个字段之间的相互关系，我们使用表格进行了详细的说明：	字段名称	类型	必填	描述
     aps	对象	是	推送消息的核心部分，包含系统定义的属性
     aps.alert	对象/字符串	否	通知的标题和正文内容
     aps.badge	整数	否	应用图标角标数字
     aps.sound	字符串	否	通知声音，可以是 default 或自定义
     aps.content-available	整数 (1 或 0)	否	静默通知标志，1 代表静默通知
     aps.mutable-content	整数 (1 或 0)	否	通知服务扩展标志
     customData	对象	否	开发者自定义字段，用于附加额外信息

     ? 推送消息的常见问题与解决方案

     1. 通知无法显示
     

   • 原因：可能是 alert 部分缺失，或 APNs 证书/令牌配置错误。
   • 解决方案：检查推送消息的 alert 属性，确保其包含必要的信息，并检查 APNs 的配置。

     2. 角标数字不正确
     

   • 原因：badge 数字没有同步更新，或者服务器未正确设置 badge 的值。
   • 解决方案：确保服务器在推送时根据用户的实际情况设置正确的 badge 数值。

     3. 静默通知未触发
     

   • 原因：应用可能在后台被系统挂起，或者设备的电量不足。
   • 解决方案：确保 content-available 设置为 1，并检查应用的后台刷新权限。

     总结

     APNs 推送通知的数据格式包含 系统标准属性 (aps 部分) 和 开发者自定义数据。aps 部分定义了推送的标题、内容、声音、角标等用户直接可见的内容，以及静默通知的控制字段。开发者可以根据需求在推送中添加自定义数据，以便客户端进行个性化处理。
     通过合理配置 APNs 消息的各个字段，可以实现对用户的有效通知和后台数据同步，从而大幅提高用户体验。理解各个字段的作用及其相互关系，对于开发者实现精准、实时的推送非常重要。