个推消息推送新手接入指南

一、业务介绍

1.1 产品简介

个推是商用级的移动应用消息推送云服务供应商，客户端 SDK 支持 Android 和 iOS 两大平台，开发者集成 SDK 后，可以通过个推强大的 web 端及丰富的 API 开放接口，发送推送消息、统计分析推送效果。可有效提高 App 活跃度，增加用户留存率。

1.2 名词解释

名词	解释
通知消息	指定通知标题和内容后，由个推 SDK 自动处理在系统通知栏中展示通知栏消息，同时响铃或震动提醒用户(响铃和震动受手机系统的设置状态影响)。
透传消息	即自定义消息，消息体格式客户可以自己定义，如纯文本、json 串等。透传消息个推只传递数据，不做任何处理，客户端接收到透传消息后需要自己去做后续动作处理，如通知栏展示、弹框等。
ClientId	个推业务层中的对外用户标识，用于标识客户端身份，由第三方客户端获取并保存到第三方服务端，是个推 SDK 的唯一识别号，简称 CID、cid。
在线推送	app 在前台打开运行时，cid 在线，通过个推渠道下发消息。
离线推送	app 在后台、锁屏、进程关闭时，cid 离线，通过厂商渠道下发消息。若 Android 未集成多厂商、 iOS 未配置推送证书，则该系统机型无法使用离线推送。

更多名词解释参考：个推名词解释

1.3 消息推送流程

二、应用创建

• 如果您还没有个推 账号，可在 个推官网 ，完成账号注册。
• 如果您还没有个推 应用，可参考 开发者中心使用说明 中的【新增服务】，完成 消息推送 应用创建。

三、客户端 SDK 集成

若您需要在手机设备上使用个推消息推送服务，必须先完成客户端 SDK 集成。

3.1 Android

• Android 个推主包：个推为 Android 应用提供的安全稳定的推送 SDK，集成主包后仅可以使用 “在线推送”。
• Android 多厂商包：个推与主流安卓厂商合作融合了厂商推送 SDK，在个推开发者中心后台配置多厂商参数、并集成多厂商包后，可以同时使用 “离线推送”，能提高在安卓厂商设备上的消息到达率。
• 厂商消息报表补全：由于个推透传无展示数返回，华为、荣耀、OPPO 、vivo 无完整离线点击数报表返回，为了方便您在个推后台可以看到更加完整的推送数据统计，建议您在客户端埋点上报补全。

3.2 iOS

• iOS 个推主包：个推为 iOS 应用提供的安全稳定的推送 SDK，集成主包后仅可以使用 “在线推送”。
• iOS 推送证书：iOS 支持的推送通知功能，从苹果开发者官网导出证书并配置在个推开发者中心后台后，可以同时使用 “离线推送”，能提高在 iOS 设备上的消息到达率。

3.3 卓信 ID

使用上面最新版 Android 和 iOS 个推主包 SDK 默认集成了卓信 ID 。

个推消息推送全新升级，融入卓信 ID 服务。基于卓信 ID 的设备算法，升级后的消息推送服务可以有效帮助 APP 提升推送的设备覆盖率、设备聚合识别准确率、设备识别稳定性，安全完善推送底层设备 ID 体系。具体优势亮点可以看看：卓信 ID 详细讲解 。

卓信 ID 接口文档：建议您在 Android 和 iOS 客户端加上卓信 ID 初始化和 getZxid 调用。

3.4 其它插件

个推除了提供 Android SDK 与 iOS SDK 之外，也提供主流的开发平台及工具集成 插件和示例 。

四、服务端推送

开发者可通过调用 服务端 RestAPI V2 或者登录 个推开发者中心 从页面下发消息。（若您想对单个 cid 用户进行推送，cid 必须先从客户端获取 ）

4.1 服务端消息下发流程（必读）

• 当 CID 在线(即 app 在前台打开运行)时：消息通过个推通道下发到客户端。具体到服务端 RestAPI-V2 代码中，即 push_message 中的 notification（通知） 或 transmission（透传） 内容传递给客户端。注意：iOS 系统不展示个推在线通知消息，所以推送用户是 iOS 时，push_message 内只能使用 transmission，iOS 客户端在线接收时自己做通知栏展示。
• 当 CID 离线(即 app 在后台、锁屏、进程关闭)时：有开启对应厂商离线功能的，消息将通过个推侧请求对应厂商侧的服务端。具体到服务端 RestAPI-V2 代码中，即 push_channel 中的通知内容传递给厂商，实际的消息是经由厂商服务器下发至客户端；对于没有开启对应厂商功能的，消息将存在个推的离线库中，等待 CID 在线，再通过个推通道下发到客户端。注意：若服务端 push_channel 不传值，则无法接收离线消息。

4.2 开发者中心后台

登录 个推开发者中心，进入个推消息推送 dos 页面，可通过以下 2 种方式【创建推送】。

个推通知 + 厂商通知

个推透传 + 厂商通知

4.3 服务端 API

服务端 API 使用时首先需要获取 AppId、AppKey、MasterSecret 参数，获取来源如下图所示：

个推服务端提供了 SDK 帮助开发者提升集成推送服务端的效率， 开发者不需要进行复杂编程即可使用个推推送服务的各项常用功能，SDK 可以自动帮您满足调用过程中所需的鉴权、组装参数、发送 HTTP 请求等非功能性要求。

• 服务端 RestAPI-V2 SDK
• 服务端 RestAPI V2 文档

注意事项：

1. SDK 目前仅支持 Java 和 PHP 语言，若服务端是其它语言可以参考 服务端 RestAPI V2 文档 通过 Https 请求调用。
2. 当您在使用过程中对接口字段有疑问时，可以通过 服务端 RestAPI V2 文档 查看具体字段描述。

单推基础代码示例：为方便您测试，提供以下单推代码示例，更多接口及参数描述可查看 服务端 RestAPI V2 文档 。

{
    "request_id":"开发者自定义填写10到32位的id",
     "audience":{
         "cid":[
             "请填写cid"
         ]
     },
    "settings":{
        "ttl":3600000
    },
    //push_message是在线个推通道消息，若要发ios在线，此处须使用transmission透传消息。
    "push_message":{
        "notification":{
            "title":"请填写安卓在线展示的通知标题",
            "body":"请填写安卓在线展示的通知内容",
            "click_type":"url",
            "url":"https://www.getui.com"
        }
    },
    //push_channel是离线厂商通道消息
    "push_channel":{
        "android":{
            "ups":{
                "notification":{
                    "title":"请填写安卓离线展示的通知标题",
                    "body":"请填写安卓离线展示的通知内容",
                    "click_type":"url",
                    "url":"https://www.getui.com"
                }
            }
        },
        "ios":{
            "type":"notify",
            "payload":"附加自定义消息",
            "aps":{
                "alert":{
                    "title":"请填写ios离线展示的通知标题",
                    "body":"请填写ios离线展示的通知内容"
                },
                "content-available":0
            },
            "auto_badge":"+1"
        }
    }
}

成功响应数据格式:

• content-type: application/json;charset=utf-8
• http code: 200 (http code码说明)
• 返回值示例

{
    "code": 0,
    "msg": "",
    "data": {
        "$taskid": {
            "$cid":"$status"
        }
    }
}

• 返回结构说明请参考 公共返回结构
• 返回参数data说明

注意：服务端 api 返回成功仅表示接口请求调用成功，不能说明客户端是否收到了消息。

例如推送返回 successed_offline 则说明推送时客户端不在线，走离线推送。若安卓客户端未收到消息，即【安卓离线收不到通知】，可以按下方 五、帮助中心 排查。

五、帮助中心

当您在集成推送服务遇到问题时：

1. 先仔细阅读此接入指南及对应的集成文档，查看是否有遗漏。
2. 阅读常见问题（Android 常见问题、iOS 常见问题、服务端常见问题），查看是否能解决。

示例：开发者在推送消息后，发现 Android 客户端并没有收到通知栏消息展示。

处理思路：

1. 先仔细阅读此接入指南以及 Android 客户端的集成文档，能够区分在线、离线推送，并确认集成是否成功。
2. 查看 Android 常见问题 中的 【安卓在线收不到通知】或【安卓离线收不到通知】，根据常见问题中提供的解答进行处理。

当官网文档无法解决您的问题时，可点击右侧的【技术咨询】扫码联系个推技术支持。