新手接入指南

新手接入指南

一、业务介绍

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 消息推送流程

processon

二、应用创建

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

三、客户端 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 种方式【创建推送】。

个推通知 + 厂商通知

notification

个推透传 + 厂商通知

transmission

4.3 服务端 API

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

params

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

注意事项:

  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"
        }
    }
}
名称 类型 描述
$taskid Json 任务编号
$cid String cid: App的用户唯一标识,status: 推送结果
successed_offline: 离线下发(包含厂商通道下发),
successed_online: 在线下发,
successed_ignore: 最近 90 天内不活跃的用户不下发

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

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

五、帮助中心

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

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

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

处理思路:

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

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

开发者中心 SDK 下载

文档中心搜索

技术
咨询

微信扫一扫

随时联系技术支持

在线
咨询