推送功能接入学习通文档
更新时间: 2019-11-15
1 概述
该文档主要描述第三方服务如何接入学习通消息推送服务,以接收来自学习通业务的推送。
1.1 文档目的
便于第三方服务研发人员了解整个消息推送系统架构和对接消息推送服务 如对文档内容、对接细节有疑问,请直接沟通消息推送服务研发人员即可
1.2 对接效果
比如一个第三方单位有自己的微信公众号,那么学习通用户如果绑定了该单位的微信公众号后,如果有学
习通业务推送,那么该第三方单位自己的微信公众号也会收到学习通的推送
2 业务描述
2.1 推送服务架构
注:1 表示第三方服务需要将绑定关系同步给学习通推送服务(同步方式有三种方案可选,见下文)
2 表示学习通业务调用推送服务,与第三方推送无关
3 是第三方推送服务需要提供给学习通推送服务的接口
2.2 架构详细描述
1,架构分为:业务调用方、推送服务、第三方推送服务
通知服务也是推送服务的一个业务调用方
第三方推送服务包括信鸽服务、学习通微信公众号、其他单位微信公众号、其他支持推送的服务等
2,业务调用方调用推送服务的接口推送,需传如下信息:
学习通用户 id(puid):推送给谁
推送目的类型:手机推送、学习通微信公众号、或者其他推送服务已对接支持的类型推送内容
3,推送服务,需要保存记录学习通用户 id 和第三方推送标识 id(registerId)的对应关系支持第三方将对应关系推送给推送服务,也支持推送服务主动拉取对应关系。
推送服务接到业务方调用后,通过学习通用户 id 查到对应的第三方推送标识 id 调用第三方提供的接口进行推送
4,第三方推送服务需按照推送服务的要求,提供统一格式的推送接口供推送服务调用
3 接入
3.1 绑定关系同步
3.1.1 第三方推送服务调用接口推送
接口地址:http://message.chaoxing.com/apis/cuser/updateOtherUserBind?help
接口使用方式详见上面链接 此种方式为第三方主动推送绑定关系给学习通推送服务,包括新增、修改、删除
特别注意:
如果使用此方式,第三方服务要做失败记录和失败重试逻辑,必须保证最终的绑定关系双方 100%完全 一致
3.1.2 第三方服务提供绑定关系日志接口,学习通推送服务拉取
为保证统一,此第三方服务提供的日志格式拉取接口需要满足学习通推送服务要求,要求如下: 接口采用偏移分页方式增量获取数据
接口地址如:http://xxxx/updateUser?offsetVal=& pushType=
参数:
字段名称 |
值 |
说明 |
pushType |
15 |
绑定类型由消息推送平台指定 |
offsetVal |
1562206210000 |
当前请 |
返回格式为标准 json 格式
参数值说明
result:1 请求成功;0 请求失败或异常
pushType:绑定用户类型(消息服务指定)必填
registerId:第三方绑定用户 id 必填
puid:passport 用户 id 必填
operCode:1 新增/更新;2 删除 必填
如下示例:
请求失败或者异常
{
"result": 0,
"errorMsg": "错误描述"
}
请求成功
{
"msg": "获取数据成功",
"result": 1,
"data": {
"list": [
{
"pushType": "4",
"registerId": "第三方绑定用户 id(string)",
"puid": 21024964,
"operCode": 1
},
{
"pushType": "4",
"registerId": "第三方绑定用户 id(string)2",
"puid": 21024965,
"operCode": 2
}
]
}
}
3.2 第三方推送服务提供推送接口
即是架构图中 3
为保证统一,此第三方服务提供的日志格式拉取接口需要满足学习通推送服务要求,要求如下:
接口地址如:
http://xxxx/pushMsg?touser=& _time=1534494409710&push_enc=
地址由第三方推送服务自定义,但参数名和格式必须按照此格式 示例:
说明 |
||
touser |
s21024964 |
第三方用户 id(registerId) |
_time |
1562206210000 |
当前请求时间戳 |
push_enc |
dde4684e6ba796bf7998303d7549cd11 |
数据有效性标签(第三方服务收 到后需要验签) |
pushData |
Json |
推送数据(json 字符串)(post 提交) |
push_enc 构造规则:
MD5(token=值& _time=值&touser=值)
token(秘钥,学习通消息推送平台分配),_time(当前请求时间戳,long类型),touse(rregisterId)
建议:将可变的标识字段放入 url 地址串中,以供加密解密 token 认证(如 touser 等)
构造示例
String push_enc = MD5("token=PSskDDvU&_time=1562206210000&touser=s21024964")
最终请求地址构造
_time=1562206210000&touser=s21024964&push_enc=dde4684e6ba796bf7998303d7549cd11
接口返回值:
如果 md5 签名校验成功则请求成功,校验失败则非法请求并返回
请求成功
{
"msg":"响应成功描述",
"result":1
}
请求失败或者异常
{
"result": 0,
"errorMsg": "错误描述"
}