OPPO 推送平台服务端 API 修订记录 : 版本号修订人修订日期修订描述 V0.1 宫建涛 初始版本 V0.2 宫建涛 部分 API 修改 V0.3 宫建涛 修改返回码 V0.4 宫建涛 修改推送统计接口 V

Transcription

1 OPPO 推送平台服务端 API 修订记录 : 版本号修订人修订日期修订描述 V0.1 宫建涛 初始版本 V0.2 宫建涛 部分 API 修改 V0.3 宫建涛 修改返回码 V0.4 宫建涛 修改推送统计接口 V0.5 宫建涛 增加批量单推 - 通知栏消息的消息长度限制 V0.6 宫建涛 修改 action_parameters 的示例, 广播推送 返回信息 messageid 改为 message_id V0.7 宫建涛 广播推送参数 registration_ids 设置最小 数量, 返回值增加 task_id 鉴权接口返回值增加 token 创建时间 V0.8 宫建涛 增加到达回执功能 V0.9 宫建涛 修改 notification 类型为 Json Object V1.0 宫建涛 增加别名推送功能与增加返回码

2 V1.1 宫建涛 增加消息回执参数与 app_message_id 字段 V1.2 宫建涛 增加返回码 33 V1.3 宫建涛 暂时屏蔽了别名 / 标签管理 推送统计等接 口 V1.4 宫建涛 修改 click_action_activity 的描述 V1.5 宫建涛 增加 feedback 接口获取失效的 registration_id 列表 V1.6 宫建涛 增加通知栏通道 Id 消息类型...4 通知栏消息...4 API 接口...6 请求地址...6 公共参数...7 公共请求参数...7 返回码...7 公共返回码定义 :...7 业务级错误问题 :...8 服务端接口...8 鉴权 (auth)...8 广播推送...9 单点推送...12 Feedback... 15

3

4 消息类型 通知栏消息 名称 类型 必须 默认 描述 是否支持单推 app_message_id String 否 无 App 开发者自定义消息 Id,OPPO 推送平 是 台根据此 ID 做去重处理, 对于广播推送相同 app_message_id 只会保存一次, 对于单推相同 app_message_id 只会推送一次 title String 是 无 设置在通知栏展示的通知栏标题, 字 是 数限制 1~32, 中英文均以一个计算 sub_title String 否 无 子标题设置在通知栏展示的通知栏标 是 题, 字数限制 1~10, 中英文均以一个计算 content String 是 无 设置在通知栏展示的通知的内容, 必 是 填, 字数限制 200 以内, 中英文均以一个计算 click_action_type Int 否 0 点击动作类型 0, 启动应用 ;1, 打开应 是 用内页 (activity 的 intent action);2, 打开网页 ;4, 打开应用内页 (activity); 非必填, 默认值为 0 ;5,Intent scheme URL click_action_activity String 否 Null 应用内页地址 click_action_type 为 1/4/ 时必填, 长度 500 <activity android:name="com.coloros.push.de mo.component.internalactivity"> <intent-filter> <action android:name="com.coloros.push.de mo.internal" /> <category android:name="android.intent.cate gory.default" /> </intent-filter> </activity> click_action_type 为 1 时这里填写 com.coloros.push.demo.internal click_action_type 为 4 时这里填写 : 是

5 com.coloros.push.demo.component.i nternalactivity click_action_url String 否 Null 网页地址或 click_action_type 为 2 是 与 5 时必填, 长度 500 示例 : click_action_type 为 2 时 l2 click_action_type 为 5 时 command://test?key1=val1&key2=val 2 action_parameters String 否 Null 动作参数, 打开应用内页或网页时传递 是 给应用或网页 JSON 格式, 非必填, 字符数不能超过 4K, 示例 : "key1":"value1","key2":"value2" show_time_type Int 否 0 展示类型 (0, 即时 ),(1, 定 否 时 ) show_start_time Long 否 0 定时展示开始时间 ( 根据 time_zone 转 否 换成当地时间 ), 时间的毫秒数 show_end_time Long 否 0 定时展示结束时间 ( 根据 time_zone 转 否 换成当地时间 ), 时间的毫秒数 off_line Boolean 否 true 是否进离线消息, 非必填, 默认为 是 True off_line_ttl Int 否 3600 离线消息的存活时间 (time_to_live) 是 ( 单位 : 秒 ), off_line 值为 true 时, 必填, 最长 3 天 push_time_type Int 否 0 定时推送 (0, 即时 ),(1, 定 否 时 ), 只对全部用户推送生效 push_start_time Long 否 0 定时推送开始时间 ( 根据 time_zone 转 否 换成当地时间 ), push_time_type 为 1 必填, 时间的毫秒数 time_zone String 否 GMT+0 时区, 默认值 :(GMT+08:00) 北京, 香 是 8:00 港, 新加坡 fix_speed Boolean 否 false 是否定速推送, 非必填, 默认值为 否 false fix_speed_rate Long 否 0 定速速率 fixspeed 为 true 时, 必填 否 network_type Int 否 0 0: 不限联网方式, 1: 仅 wifi 推送 ; 否 call_back_url String 否 无 * 仅支持 registrationid 或 aliasname 两种推送方式 * 应用接收消息到达回执的回调 URL, 字数限制 200 以内, 中英文均以一个计算 OPPO Push 服务器 POST 一个 JSON 数据到 call_back_url; Content-Type 为 application/json 的 是

6 方式提交数据 JSON 数据示例 : [ "messageid": "msgid1", "taskid": "taskid1", "registrationids": "regid1, regid2", "param": "call_back_parameter", "eventtype": "push_arrive", "messageid": "msgid1", "taskid": "taskid1", "registrationids": "regid1,regid2", "param": "call_back_parameter", "eventtype": "push_arrive" ] call_back_parameter String 否 无 App 开发者自定义回执参数, 字数限制 50 以内, 中英文均以一个计算 channel_id String 否 无 通知栏通 (NotificationChannel), 从 Android9 开始发送通知消息必须要指 定通道 Id 是 是 API 接口 注意事项 : 任何值字符串都是需要 urlencode 编码的 请求地址 调用 API 的服务 URL 地址, 开放平台目前提供了 2 个环境给开发者使用 : 沙箱测试环境, 正式环境 沙箱测试环境 : OPPO PUSH 的测试环境, 仅提供简化版的 OPPO PUSH, 应用创建后即可使用 沙箱环境的权限和流量均无限制, 可放开使用 正式环境 :OPPO PUSH 的应用创建之后即可使用的环境, 但是有使用权限和流量的限制 环境 HTTPS 请求地址备注 生产环境 推送消息

7 生产环境 反馈信息 沙箱环境 暂无 公共参数 公共请求参数 名称 类型 必须 默认 描述 auth_token String 是 无 权限令牌, 推送消息时, 需要提供 auth_token 有效期默认为 1 天, 过期后无法使用, 通过 HTTP Request Headers 传递 返回码 公共返回码定义 : 返回码范围 (-1-100), 这种返回码一般是由于用户的请求不符合各种基本校验而引起的 用户遇到这些错误的返回首先检查应用的权限 频率等情况, 然后参照文档检验一下传入的 参数是否完整且合法 Code 英文描述 中文描述 -2 Service in Flow Control 服务器流量控制 -1 Service Currently Unavailable 服务不可用, 此时请开发者稍候再试 0 Success 成功, 只表明接口调用成功 11 Invalid AuthToken 不合法的 AuthToken 12 Http Action Not Allowed HTTP 方法不正确 13 App Call Limited 应用调用次数超限, 包含调用频率超限 14 Invalid App Key 无效的 AppKey 参数 15 Missing App Key 缺少 AppKey 参数 16 Invalid Signature sign 校验不通过, 无效签名 17 Missing Signature 缺少签名参数 18 Missing Timestamp 缺少时间戳参数 19 Invalid Timestamp 非法的时间戳参数 20 Invalid Method 不存在的方法名 21 Missing Method 缺少方法名参数 22 Missing Version 缺少版本参数 23 Invalid Version 非法的版本参数, 用户传入的版本号格

8 式错误, 必需为数字格式 24 Unsupported Version 不支持的版本号, 用户传入的版本号没有被提供 25 Invalid Encoding 编码错误, 一般是用户做 http 请求的时候没有用 UTF-8 编码请求造成的 26 IP Black List IP 黑名单 27 Access Denied 没有此功能的权限, 拒绝访问 28 App Disabled 应用不可用 29 Missing Auth Token 缺少 Auth Token 参数 30 Api Permission Denied 该应用没有 API 推送的权限 31 Data Not Exist 数据不存在 32 Data Duplicate 数据重复 33 The number of messages exceeds 消息条数超过日限额 the daily limit 40 Missing Required Arguments 缺少必选参数,API 文档中设置为必选的参数是必传的, 请仔细核对文档 41 Invalid Arguments 参数错误, 一般是用户传入参数非法引起的, 请仔细检查入参格式 范围是否一一对应 业务级错误问题 : 请求后端业务服务器出现的问题, 返回的错误码在 到 之间, 具体业务错误码可 参见 API 文档 每个接口最多 10 个返回码 服务端接口 鉴权 (auth) 开发者身份验证通过获得 auth_token 权限令牌, 后面的请求都需要带上 auth_token 该 auth_token 具有一定的时效性, 以保证安全性 后续请求做为请求参数, 如使用 HTTP 协议 的话, 可以做为 HTTP 头携带, 本文后续接口默认都认为已携带该参数 描述 内容 接口功能 开发者身份鉴权 请求方法 POST 请求编码 UTF-8 Content-Type application/x-www-form-urlencoded

9 请求路径 /server/v1/auth 请求参数 名称 类型 必 默认 描述 须 app_key String 是 NULL OPPO-OPEN 分配给应用的 AppKey, 内部开放 API 是 PUSH 分配给应用的 AppKey sign String 是 Null sha256(appkey+timestamp+mastersecret) mastersecret 为注册应用时生成 timestamp Long 是 Null 时间戳, 时间毫秒数, 时区为 GMT+8 PUSH API 服务端允许客户端请求最大时间误差为 10 分钟 响应参数 (JSON) 名称 类型 必须 描述 code Int 是 返回码, 请参考平台返回码与接口返回码 message String 否 错误详细信息, 不存在则不填 data String 否 返回值,JSON 类型, 包含响应结构体 响应示例 : "code": 0, "message": "sucess", "data": "auth_token": "58ad47319e8d725350a5afd5" // 权限令牌, 推送消息时, 需要提 供 auth_token, 有效期默认为 24 小时, 过期后无法使用 "create_time": " 时间毫秒数 " 广播推送 广播推送主要用于向大批量用户推送同一条消息的场景中, 例如全量用户推送 标签推送 大量 registration_id 推送等推送场景 保存通知栏消息内容体 (message/notification/save_message_content) 描述 内容

10 接口功能请求方法请求编码 Content-Type 请求路径 保存消息内容体, 获取消息 Id POST UTF-8 application/x-www-form-urlencoded /server/v1/message/notification/save_message_content 请求参数 参见通知栏消息 响应参数 (JSON) 名称 类型 必须 描述 code Int 是 返回码, 请参考平台返回码与接口返回码 message String 否 错误详细信息, 不存在则不填 data String 否 返回值,JSON 类型, 包含响应结构体 响应示例 : "code": 0, "message": "sucess", "data": "message_id": "58ad47319e8d725350a5afd5" // 消息 ID 广播推送 - 通知栏消息 (message/notification/broadcast) 描述接口功能请求方法 Content-Type 请求编码请求路径 内容发送通知栏消息 POST application/x-www-form-urlencoded UTF-8 /server/v1/message/notification/broadcast 请求参数 名称 类型 必 默认 描述 须 message_id String 是 无 消息 Id target_type Short 是 无 目标类型,1:ALL;2:

11 registration_id ;5: 别名推送 alias_name;4:tag; registration_ids String 否 无 应用级设备注册唯一标识符 target_type 为 2 必填, 多个以英文分号 (;) 分隔, 最大 1000 个 target_value String 否 无 推送目标用户 多个以英文分号 (;) 分隔, 最大 1000 个, 可以替代 registration_id 响应参数 (JSON) 名称 类型 必须 描述 code Int 是 返回码, 请参考公共返回码与接口返回码 message String 否 错误详细信息, 不存在则不填 data String 否 返回值,JSON 类型 推送请求调用成功响应示例 : code:0, message: "", data : message_id : xxxxxxxxx // 消息 Id task_id : xxxxxxxxx // taskid 推送目标存在问题响应示例 : 推送请求调用成功, 但推送目标存在问题 code:0, message: "", data : message_id : xxxxxxxxx, // 消息 ID task_id:xxxxxxxxxx, // 推送任务 ID "10000": [ "J d625e6c64567f71487e040e7d017f b", "J d625e6c64567f71487e040e7d017f b", "J d625e6sd64567f71487e040e7d017f b" ], "10001": [ "J d625e6c64567f714567e040e7d017f b" ]

12 返回码 (code) Code 英文描述中文描述 Invalid Registration_id registration_id 格式不正确 单点推送 单推 - 通知栏消息推送 (message/notification/unicast) 描述接口功能请求方法 Content-Type 请求编码请求路径 内容发送通知栏消息 POST application/x-www-form-urlencoded UTF-8 /server/v1/message/notification/unicast 请求参数 参数定义 : 名称 类型 必 默认 描述 须 message String 是 无 通知栏消息 JSON String message: 名称 类型 必 默认 描述 须 target_type Short 是 无 目标类型 2: registration_id ;3: 别名推送 alias_name;4:tag; registration_id String 否 无 应用级设备注册唯一标识符 target_type 为 2 必填 target_value String 是 无 推送目标用户, 可以替代 registration_id notification JSON 是 无 请参见通知栏消息 Object

13 响应参数 (JSON) 名称 类型 必须 描述 code Int 是 返回码, 请参考平台返回码与接口返回码 message String 否 错误详细信息, 不存在则不填 value String 否 返回值,JSON 类型 推送请求调用成功响应示例 : code:0, message: "", data : messageid : xxxxxxxxx, // 消息 Id 推送目标存在问题响应示例 : 推送请求调用失败, 但推送目标存在问题 code:1000, message: "registration_id 格式不正确 返回码 (code) Code 英文描述中文描述 Invalid Registration_id registration_id 格式不正确 批量单推 - 通知栏消息推送 (message/notification/unicast_batch) 描述接口功能请求方法 Content-Type 请求编码请求路径 内容批量发送单推通知栏消息 POST application/x-www-form-urlencoded UTF-8 /server/v1/message/notification/unicast_batch 请求参数 参数定义 : 名称类型必默认描述

14 须 messages String 是 无 通知栏消息 JSON 数组字符串, 示例 :[message,message] 最多 1000 个 message: 名称 类型 必 默认 描述 须 target_type Short 是 无 目标类型 2: registration_id ;3: 别名推送 alias_name;4:tag; registration_id String 否 无 应用级设备注册唯一标识符 target_type 为 2 必填 target_value String 是 无 推送目标用户, 可以替代 registration_id notification JSON 是 无 请参见通知栏消息 Object 响应参数 (JSON) 名称 类型 必须 描述 code Int 是 返回码, 请参考平台返回码与接口返回码 message String 否 错误详细信息, 不存在则不填 data String 否 返回值,JSON 类型 推送请求调用成功响应示例 : code:0, message: "", data : [ messageid : xxxxxxxxx, // 消息 Id registrationid:xxxxxxxxx, messageid : xxxxxxxxx, // 消息 Id registrationid:xxxxxxxxx, messageid : xxxxxxxxx, // 消息 Id registrationid:xxxxxxxxx, // 消息 Id errorcode:10000, // 失败码 errormessage:xxxx // 失败说明

15 ] 返回码 (code) Code 英文描述中文描述 Invalid Registration_id registration_id 格式不正确 Feedback 请求地址 环境 HTTPS 请求地址 备注 生产环境 反馈信息 沙箱环境 暂无 获取失效的 registration_id 列表 (feedback/fetch_invalid_regidlist) 描述接口功能请求方法请求编码请求路径 内容获取失效的 registration_id 列表不需要传递任何 HTTP 参数 每次请求最多返回 500 个 registration_id 每次请求之后, 成功返回的失效的 registration_id 将会从数据库删除 GET UTF-8 /server/v1/feedback/fetch_invalid_regidlist 请求参数 请参见公共请求参数 响应参数 (JSON) 名称类型必须描述 code Int 是返回码, 请参考平台返回码与接口返回码 message String 否错误详细信息, 不存在则不填

16 data String 否 返回值,JSON 类型, 包含响应结构体 响应示例 : "code": 0, "message": "sucess", "data": "registration_ids": [regid1, regid2, regid3] //regid list "totalcount":100000