如果你想接入极光推送,但对推送服务一知半解,不知道是否可以达到你所需要的效果,看官方文档不知道如何下手,那么本文的手把手教学你有必要了解一下

无论你是客户端开发还是服务端开发,在开发之前先整体了解一下流程,动手做个测试都是很有必要的。

一、测试准备

  1. 注册登陆极光官网账号,创建一个应用,应用信息中获得 Appkey 和 Masersecret(密码可以重置)

  2. 推送设置 → Android → 设置包名并保存 → 扫码下载 demo → 安装 → 首页点击 getregistrationID 值
    (注意:你可能会误触 stoppush 按钮导致无法收到推送,无法设置别名标签等,在不确定的情况下可以点击 resumepush 进行恢复,不会影响功能)

  3. 推送设置 → iOS → 上传证书下载 iOS SDK → 打开 demo 文件夹,运行 PushTest.xcodeproj → 配置 Appkey 和 bundle ID 与证书

    • 为了迅速运行做简单的测试,我们先删除 NotificationServiceTest,这个是为了支持 iOS 10 的新功能,有兴趣可以搜索研究一下,官网文档

    • iOS 的 demo 配置相对比较复杂,证书也需要 Apple 开发者账号申请,需要付费,建议让 iOS 开发人员帮助配置。

    • 若不配置证书,不注册 Apns 还是可以测试极光的自定义消息推送功能,初始化文档

  4. 官网测试比较简单,阅读三分钟 demo 文档

  5. 下载 API 请求工具 Postman,下载地址(需要科学上网),网盘资源分享

  6. 在以下测试中,涉及到的需要从客户端 demo 获取、设置的信息如下,请根据自己的信息进行值替换:

    • registration_id:Android 端 1a0018970a9bea3e776;iOS 端 18171adc032dcd59b77 ,均可在 demo 首页取到。

    • tag:China,Taiwanese,men,39

    • alias:Jay

    • Android 高级功能页面可以设置 tag 和 alias,iOS 在 TagAlias 页面设置。

    • 手上有两台测试机,分别为 Android 系统和 iOS 系统,iOS App 配置为开发环境

二、鉴权方式讲解(每个 API 都必须配)

  • JPush、JMessage、JSMS 的所有 Rest API 都需要进行鉴权,注意不要遗漏,不能直接在浏览器上访问 Rest API 地址。

  • 在 Postman 创建一个新请求,首页展示 Authorization 页面,在 Type 处选择 Basic Auth

  • Username 处填写极光的 Appkey ,Password 处填写极光的 Mastersecret,需要特别注意不要多写空格。

  • Appkey 和 Mastersecret 是在官网创建一个应用后才有的,不是 注册账号后的 DevKey 和 DevSecret

  • 当报错 HTTP code 401 、极光 code 1004 时,就需要检查鉴权是否正确,报错 1008 时检查 Appkey 值。

null

三、开始调 API 推送消息,配合文档

  1. 极光文档中会标注某个 API 是 POST 请求还是 GET 或其他请求,根据情况选择,推送是 POST 请求,URL 地址是https://api.jpush.cn/v3/push,设置好 Authorization 鉴权
    此处建议测试参数是否正确的时候用推送校验的 API 即https://api.jpush.cn/v3/push/validate ,不会实际发出信息,不会影响线上用户。
    null

  2. 选择 Body → 选择 raw → 选择 JSON(application/json),极光的推送内容完全使用 JSON 的格式。先简单测试一下广播推送一条通知给所有人,将如下代码复制到 Postman 中,注意删除我的注释,选择 Send 即可。
    null
    Android 通知栏效果
    null
    iOS 横幅效果
    null

    {
     "platform": "all",//推送平台,还可以指定具体的 Android 、iOS 、winphone 平台
     "audience": "all",//推送目标,广播推送有 10 分钟延迟,在安装 demo 获取到 registrationID 后等待 10 分钟再推送,或者针对 registrationID 值进行推送,还有 tag 、alias 等方式,后续讲解。
     "notification": {//通知对象
             "alert": "Hi, JPush!"//可以快捷定义一个 alert 属性,传通知内容
         }
     "options": {
         "apns_production": false//iOS demo 配的是开发证书,所以推送时需要设置推送给开发环境,只对 iOS 有效。
     }
    }
  3. Send 后返回了 Status 200 OK; sendno:0 和 msg_id:54043195592768656 。

    • HTTP code 为 200 代表请求成功
    • sendno 是随机数,如果推送的时候没有传值,即返回默认值 0
    • msg_id 是该消息的唯一标识,由极光服务器返回,它也会随着消息下发给你的 App
    • 还可观测到 Headers 处 Postman 自动根据我们前面的一些操作配置了 Authorization 和 Content-Type
      null
  4. 可以选择 Save 保存这个请求,下次可以仅修改 body 内容而不需要再配置 Authorization。保存时支持自定义请求的名称并做相关备注,有助于我们的下次使用。我将本次请求命名为「即时推送」。

四、详细讲解推送 API 所涉及到的常用字段与效果,附示例

推送 API 的高级使用,配合文档

一个推送对象必须要包含 Platform、Audience、Notification 或 Message(二选一),若缺少,推送将报错。

这里先介绍一个用于推送校验的 API:https://api.jpush.cn/v3/push/validate

  • 该 API 只用于验证推送调用是否能够成功,实际不会向用户发送任何消息,字段和推送的 API 完全相同。

  • 可以用来验证下自己所传的参数值和类型是否合法。

1、Platform 推送平台

一般用到的是 iOS 和 Android 平台,winphone 平台受众较少。

  • 如果你只需要用户满足 Audience 推送目标设置的条件即可收到,不需要区分平台,可设置为 all;
    { "platform" : "all" }

  • 如果你这条消息确定只允许 iOS 或 Android 平台的用户收到,那么就具体指定一个平台;

{
    "platform" : ["android"],
    "audience": "all",
    "notification": {
            "alert": "Hi, JPush!"
        }
}
{
    "platform" : ["ios"],
    "audience":  "all",
    "notification": {
            "alert": "Hi, JPush!"
        }
    "options": {
        "apns_production": false
    }
}
  • 如果你不知道要收到消息的用户是 iOS 还是 Android ,但 Android 和 iOS 的内容有所区别,那么请设置为 all ,并在通知内容体里分别对 iOS 和 Android 传值,极光会自行判断推送目标的平台,并对应的将 iOS 或 Android 的消息发给它
    {
      "platform": "all",
      "audience": "all",
      "notification": {
          "android": {
              "alert": "这是给 Android 设备的推送,请点击查看",
              "title": "Send to Android",
              "extras": {
                  "url": "https://community.jiguang.cn/"
              }
          },
          "ios": {
              "alert": "这是给 iOS 设备的推送,请点击查看",
              "sound": "default",
              "badge": "+1",
              "extras": {
                  "url":  "https://www.jiguang.cn/"
              }
          }
      },
      "options": {
          "apns_production": false
      }
    }

null
null

2、Audience 推送目标

支持 all、 tag、tag_and、tag_not、alias、regIstration_id、segment、abtest

  • all 即广播推送给所有 Platform 指定平台的用户,写法即:{"audience" : "all"}

  • tag、tag_and、tag_not 是标签的并集、交集、补集的区别

  • 标签、别名、regIstrationID 可以同于指定用户的推送,详细理解阅读本帖
    写法:{"audience" : {"tag" : [ "深圳" ]}},特别注意{"audience" : "{"tag" : [ "深圳" ]}"}是错误的写法!

  • segment 分群功能的介绍阅读本文;abtest 暂不做介绍

  • 可同时推送指定多类推送目标,多种条件之间取交集

  • 在我们安装好的 demo 上,我们可以轻松的获取到 regIstrationID 值,并动手设置别名和标签

  • 涉及知识详解:如何推送消息给指定用户 点我

3、Notification 通知对象

  • 其下属属性包含 4 种,3 个平台属性(Android、iOS、winphone),以及一个 "alert" 属性:

    • 各平台的 alert 信息如果都一样,则可以直接在 "alert" 属性定义。

    • 如果各平台需要推送的信息不一样,则分别在平台属性下的 alert 字段进行传值。

    • 若两处的 alert 均有传值,以平台属性下的 alert 值为准。

    • alert 必须传值,否则会报错。

  • Android

{
    "notification" : {
        "android" : {//在配了 Android 属性后,必须配置 alert 字段,其他均可选。
             "alert" : "这是给 Android 设备的推送,请点击查看", 
             "title" : "这是标题,会替换应用名称", 
             "builder_id" : 3, //先在客户端调 API 设置通知栏样式,推送时指定对应的编号即可
             "style":1  // 通知栏样式类型,如不写该字段则默认为 0 ,可选设置 1,2,3,对应bigText=1,Inbox=2,bigPicture=3。
             "big_text":"big text content",//大文本样式,可以用来实现换行展示,部分定制 ROM 不支持该效果
             "inbox":JSONObject,//文本条目样式,json 的每个 key 对应的 value 会被当作文本条目逐条展示
             "big_pic_path":"picture url",//大图片样式,网络图片 url,或本地图片的 path,目前支持.jpg和.png后缀的图片
             "alert_type":1 // 通知提醒方式,范围 -1 ~ 7
             "priority":0, // 通知栏展示优先级,范围为 -2~2
             "category":"category str",//通知栏条目过滤或排序,依赖 rom 厂商对 category 的处理策略
             "extras" : {
                  "点击" : "跳转到**页面", //可在 extra 里面定义点击跳转到具体某个 activity,客户端取值后实现。
                  "url" : "https://community.jiguang.cn/"//可定义其他的字段来传递自己所需要的信息
             }
        }
    }
}
  • Android Notification 中涉及到的知识详解:

    • 自定义通知栏样式 点我

    • 如何使通知消息换行展示 点我

    • Android 如何实现点击消息跳转 点我

  • iOS

    {
      "notification" : {
           "ios" : {
                   "alert" : {
                       "title" : "这是标题", //iOS 10 及以上的标题将会在应用名称下方展示,iOS 10 以下则替换应用名称
                       "subtitle" : "这是副标题" , //副标题在标题下展示,二者均自动加粗
                       "body" : "这是给 iOS 设备的推送,请点击查看" //必填,否则通知将不展示,在不设置 title 和 subtitle 时直接对 alert 传值即可,不需要特地写 body 字段
                   }, 
                   "sound" : "sound.caf", //如果去掉该字段,则此消息无声音提示,要有默认的声音提醒,传 default 即可
                   "badge" : 1, //如果没有该字段,则不改变角标数字;设置为 0 表示清除客户端角标,设置为 +1 表示在原角标的基础上 +1 后展示;
                   "content-available":true,//携带"content-available":true 说明是 Background Remote Notification
                   "mutable-content" : true,//携带”mutable-content":true 说明是支持iOS10的UNNotificationServiceExtension
                   "category" : "category str",// iOS 8 开始支持的参数,目的是用来注册一组和通知关联起来的 button 的事件。
                   "extras" : {
                    "点击" : "跳转到**页面", //可在 extra 里面定义点击跳转到具体某个 activity,客户端取值后实现。
                    "url" : "https://community.jiguang.cn/"//可定义其他的字段来传递自己所需要的信息
                   }
              }
         }
    }           
  • iOS Notification 中涉及到的知识详解:

    • iOS 如何设置 title 和 subtitle 点我

    • iOS 自定义声音 点我

    • 角标问题(含 iOS、Android)/ 如何实现角标自动 +1 点我

    • iOS 不点击通知栏,怎么获取消息内容? 点我

    • 如何实现「用户点击某条通知栏消息后跳转到具体的页面」 点我

4、Message 自定义消息

  1. 基本知识

    • 自定义消息默认不展示,用于传递不需要展示的消息,或者需要自行展示的消息

    • iOS 的自定义消息只能在前台时接收,可用于前台一些交互信息的下发。

    • 自定义消息不分环境,即推送一条自定义消息,iOS 的开发环境和生产环境均可以收到。

  2. 字段说明

  • Message 中只有 msg_content 是必填项,其他字段均可选,没有什么特别的含义,只是选择了几个比较常用到的场景涉及到的字段作为固定字段,其他未涉及到的可以自己在 extras 里面进行定义。
    "message": {
        "msg_content": "Hi,JPush",//消息内容,必填。
        "content_type": "text",//消息类型,可选
        "title": "msg",//消息标题,可选。
        "extras": {
            "key": "value"
        }//可选参数,可自定义字段和值。
    },

5、sms_message 短信补充,配合文档

  1. 基本知识

    • 短信补充需要在极光官网进行开发者认证,并充值短信条数

    • 在官网短信页面创建通知模板,等待审核成功

    • 用途与详细解释阅读文档

  2. 字段说明

     "sms_message":{
        "temp_id":1250,//短信补充的内容模板 ID。没有填写该字段即表示不使用短信补充功能。模板 ID 在官网创建模板后取到。
        "temp_para":{
             "code":"123456"
        },//短信模板中的参数,如果创建模板的时候设置了参数则需要传,否则不需要。
         "delay_time":3600//设置多长时间内没收到通知时发短信,单位为秒,不能超过 24 小时。设置为 0,表示立即发送短信。该参数仅对 android 和 iOS 平台有效,Winphone 平台则会立即发送短信。
     },

6、options 可选参数,配合文档

    "options": {
        "sendno": 60,//随机数,用来作为 API 调用标识,API 返回时被原样返回,以方便 API 调用方匹配请求与返回,如果请求时去掉该字段,则请求后返回默认值 0
        "time_to_live": 60,//离线保存时长,单位是秒,默认 86400,最长可设置 10 天(即 864000)
        "override_msg_id": 54043195592768656,//Android 要覆盖的消息的 ID,此处我填写的就是上次推送得到的 MessageID
        "apns_production": false,//iOS 通知消息(APNS)的环境,false 代表该消息推送给开发环境。
        "apns_collapse_id":"jiguang_test_201706011100",//iOS 要更新的通知的标识符
        "big_push_duration": 60//定速推送时长,降低推送速度,一般不设置
    }

五、调 Report API 进行统计查询,配合文档

1. 送达统计:GET 请求

API 地址:https://report.jpush.cn/v3/received?msg_ids=
msg_ids 后传我们所需查询的消息的 ID 值,做多可以传 100 个,以上述推送得到的 msg_id:54043195592768656 为例,返回字段相关含义参考文档说明
null

2. 送达状态查询:POST 请求

API 地址:https://report.jpush.cn/v3/status/message

  • 返回 status 为 0 表示已送达到设备
    null

六、对别名和标签进行操作的 Device API 的讲解

调 Device API 查询、设置、更新、删除设备的 tag、alias 信息,配合文档

客户端和服务端均提供了 API 可以对 tag、alias 进行操作,如何选择是在客户端操作还是服务端操作请阅读本文

1、查询设备的别名与标签,GET 请求

API 地址:https://device.jpush.cn/v3/devices/{registration_id}

  • 使用实际需要查询的设备的 registrationID 值替换{registration_id}

  • 先在 Android demo 高级设置中设置了 tag 和 alias,然后调 API 查询设置情况,查到结果与我设置的一致
    null

2、设置设备的别名与标签,POST 请求

API 地址:https://device.jpush.cn/v3/devices/{registration_id}

  • 这次我们直接调 API 给 iOS demo 设置 tag 、alias,得到结果成功

  • 然后可以再使用 GET 请求查询该设备的 tag 和 alias,你会发现结果与你设置的一致。
    null

3、查询别名,GET 请求

API 地址:https://device.jpush.cn/v3/aliases/{alias_value}

  • 使用实际需要查询的别名值替换{alias_value}

  • 获取指定alias下的设备,最多输出 10 个,也就是说如果别名下绑定了超过 10 个设备,那么你也只能查到 10 个,所以一般我们是在自己的服务端去保存别名与设备的 ID 信息
    null

4、删除别名,DELETE 请求

API 地址:https://device.jpush.cn/v3/aliases/{alias_value}

  • 删除该别名与设备的绑定关系,只需要修改查询别名的 API 请求为 DELETE 即可。

  • 删除后再调查询别名的 API ,你就会发现结果为空。
    null
    null

5、查询标签列表,GET 请求

API 地址:https://device.jpush.cn/v3/tags/

  • 获取当前应用的所有标签列表,每个平台最多返回 100 个,超过 100 个的标签,将无法完全取到。
    null

6、判断设备与标签绑定关系,GET 请求

API 地址:https://device.jpush.cn/v3/tags/{tag_value}/registration_ids/{registration_id}

  • 该 API 返回值只有 true 和 false 两种情况。
    null

7、更新标签,POST 请求

API 地址:https://device.jpush.cn/v3/tags/{tag_value}

  • 由于我们之前已经给设备设置过一些标签了,我们现在尝试使用 remove 方法更新标签绑定关系

  • 请求成功后,我们就将 Android demo 从 tag:men 绑定的设备中移除了。
    null

{
        "registration_ids":{
            "remove": [
                "1a0018970a9bea3e776"
            ]
        }
}

8、删除标签,DELETE 请求

API 地址:https://device.jpush.cn/v3/tags/{tag_value}
null

七、定时任务讲解

创建远程定时、定期任务,配合文档

1、Schedule 任务对象定义

  • 每一个 schedule 任务,都由 name、enabled、trigger、push 四个小节组成。

  • push 中的字段与即时推送的完全一致,可以根据上述 push 的讲解,自行更换 push 中的内容。

  • name 任务的名字,与代码注释的作用相同,由你自己设定,要求不得超过 255 字节,由汉字、字母、数字、下划线组成。

  • enabled 任务当前的状态,布尔值, true 或false,创建任务时必须为 true。可用于开启或关闭此定时任务

  • trigger 任务的触发条件,当前只支持定时任务(single)与定期任务(periodical)。

    • single 定时,仅含字段 time ,格式为 "YYYY-mm-dd HH:MM:SS“,日期时间格式必须完整。

2、创建 Schedule 任务,POST 请求

API 地址:https://api.jpush.cn/v3/schedules

  • 定时
    null
{
   "name": "测试时创建的定时任务",
   "enabled": true,
   "trigger": {
        "single":{ 
            "time": "2018-08-03 14:53:00"//设置一个当前往后几分钟的时间点,以便于迅速查看定时任务推送出去后的效果
         }
   },
   "push": {
     "platform": "all",
     "audience": "all",
     "notification": {
          "alert" : "Hello, JPush!"
     },
     "options": {
          "apns_production": false
     }
  } 
}
  • 定期