消息推送 API

• 概述
• 个性化推送 API
• 推送 API
• 推送结果查询 API
• 推送状态控制 API

概述

本文档为后台对接 TMF 推送服务相关说明，TMF 推送服务按用户范围分个性化推送和全量推送，按到达客户端后的呈现方法分为通知栏推送和透传消息推送，具体各种推送使用方法见下文详细说明。

个性化推送 API

功能介绍

针对指定设备或者用户进行通知栏消息的推送或者消息透传。

请求地址

注意：地址中的IP 和端口是实际环境中的JsonProxy服务使用的IP和端口或URL。

http://172.16.0.34:30016/data/1827/forward

请求方式

POST

请求字段

字段	类型	是否可选	说明
cmdId	int	否	指令 ID，6238 - 通知栏消息推送，6362 - 透传消息
productId	int	否	用户所属产品的 ID，即应用标识 Pid。 请在控制台 > 我的应用里查看
taskId	int	否	业务自定义，唯一标识一批次的个性化推送
expireTime	int	否	过期时间戳，以秒为单位， 从 1970 年 01 月 01 日 00 时 00 分 00 秒起至现在的总秒数。 注意：系统不会推送过期的数据，过期时间戳必须大于当前时间，最大不超过7 天。
cmdData	string[]	否	消息数据，通知栏消息和透传消息内容不同
busiType	int	否	消息推送 23
pushChannel	int	否	推送数据使用的通道， 0 - 系统指定通道，1 - 系统自有通道
guid	string	是	TMF 内部 ID（与 uid 2 选 1，两者非空优先 guid）
uid	string	是	账号 ID（与 guid 2 选 1，两者非空优先 guid），即App调用setUserId接口上报的ID
seqNo	int	是	保留字段，请填 0
prior	int	是	通知栏消息优先级，1 - 服务通知 2 - 运营消息，默认为运营消息
android	Object	是	向Android用户推送通知栏消息时的可选扩展字段，具体字段请参见AndroidPushConfig
ios	Object	是	向iOS用户推送通知栏消息时的可选扩展字段，具体字段请参见IosPushConfig
msgType	string	是	消息类型，当且仅当下发通知栏消息时有效，只用于记录日志和数据统计
taskName	string	是	任务名

AndroidPushConfig参数说明

IosPushConfig参数说明

TMF消息优先级与各厂商的消息类型对应关系

• TMF消息分类

TMF继续保持将消息分类服务通知和运营消息两大类，每一个大类进一步细分二级分类

• TMF消息优先级与各厂商的消息类型对应关系

• 二级分类与国内各Android厂商的分类对应关系如下表：

注意

• 客户根据自己的业务需要和厂商规范，做好消息分类管理：

  • 为每个APP划分类：将消息分为服务通知和运营消息两大类和二级分类；
  • 如果没有特殊要求，建议申请一个通用的服务通知二级分类和一个通用的运营消息二级分类；

• TMF个性化推送API支持业务在调用时填写具体的消息分类(prior、channel和 category)；

• TMF控制台配置的批量消息推送任务只推送TMF运营消息，只使用通用的运营消息分类：

  • 在小米开发平台申请通用的运营消息channel，用来在控制台等入口向小米用户推送运营消息；
  • 在华为开发平台申请消息自分类权益。
  • 在OPPO开发平台为运营消息申请channelID为tmf_push_channel的channel，用来在控制台等入口向OPPO用户推送运营消息，channelID为high_system的channel，用来在控制台等入口向OPPO用户推送系统消息，且需要升级推送SDK。
  • 使用控制台推送运营消息时，其他国内Android厂商可以不用向厂商申请运营消息权限。

• 客户调用个性化推送API时，填写具体的消息分类参数(prior，channel和category字段)。

请求示例

通知栏推送

推送通知栏消息时cmdData数组的元素如下：

跳转参数说明：

{
  "req": {
    "cmdId": 6238,
    "guid": "test",
    "productId": 8903,
    "taskId": 123,
    "expireTime": 1561978029,
    "cmdData": [
      "abcdefg", //标题
      "dadaf", //内容
      "{\"type\":1,\"url\":\"www.test.com\"}", // type :1应用; 2 url; 3自定义
      "{\"youkey\":\"values\"}", //附加参数kv
        "sound", //sound文件名，仅iOS使用
        "badge" //badge，badge取值说明：空 - 服务端不下发badge，0 - 清除App的badge，具体数值 - App的badge将设置成该值 ，仅iOS使用
    ],
    "busiType": 23,
    "uid": "test",
    "seqNo": 0,
    "pushChannel": 0,
    "msgType":"运营消息",
    "taskName":"xx任务"
  }
}

消息透传

推送透传消息时cmdData数组中的元素如下：

{
  "req": {
    "cmdId": 6362,
    "guid": "test",
    "productId": 8903,
    "taskId": 123,
    "expireTime": 1561978029,
    "cmdData": [
      "data" //要透传的数据
    ],
    "busiType": 23,
    "uid": "test",
    "seqNo": 0,
    "pushChannel": 0
  }
}

响应字段

网关返回码 ret

Data

Resp

data.resp.ret

响应示例

{
  "ret": 0,
  "data": {
    "resp": {
      "ret": 0
    }
  }
}

推送 API

功能介绍

针对指定指定用户群体进行通知栏消息的推送或者消息透传。

请求地址

注意： 地址中的IP 和端口是实际环境中的JsonProxy服务使用的IP和端口或URL。

http://172.16.0.34:30016/data/1828/forward

请求方式

POST

请求字段

字段	类型	是否可选	说明
cmdId	int	否	指令 ID，6238 - 通知栏消息推送，6362 - 透传消息
productId	int	否	用户所属产品的 ID，即应用标识Pid。 请在控制台 > 我的应用里查看
platform	string	否	授受用户所属的手机平台，取值范围：Android/iOS
taskName	string	否	推送任务名
expireTime	int	否	过期时间戳，以秒为单位， 从 1970 年 01 月 01 日 00 时 00 分 00 秒起至现在的总秒数。 注意：系统不会推送过期的数据，过期时间戳必须大于当前时间，最大不超过7 天。
cmdData	string[]	否	消息数据，通知栏消息和透传消息内容不同
busiType	int	是	弃用
audience	Audience[]	是	推送条件
isTest	int	是	是否为测试单，取值范围：1 - 测试，0 - 正式（当 audience 不为空时，则有这个字段；当为测试单时，推送条件只支持 guid/imei/uid）

Audience

请求示例

通知栏推送

推送通知栏消息时cmdData数组的元素如下：

跳转参数说明：

{
  "req": {
    "cmdId": 6238,
    "productId": 8903,
    "platform": "Android",
    "taskName": "taskName",
    "expireTime": 1561978029,
    "cmdData": [
      "abcdefg",
      "dadaf",
      "{\"type\":1,\"url\":\"www.test.com\"}",
      "{\"youkey\":\"values\"}"
    ],
    "isTest": 0,
    "audience": [
      {
        "type": "imei",
        "content": "",
        "fileUrl": "http://172.16.0.34:30010/private/2020031116155929020_1",
        "fileMd5": "c26598d376a2c1261abacb2834cb3cbe"
      },
      {
        "type": "model",
        "content": "华为",
        "fileUrl": "",
        "fileMd5": ""
      },
      {
        "type": "area",
        "content": "gz;sz",
        "fileUrl": "",
        "fileMd5": ""
      },
      {
        "type": "buildno",
        "content": "buildno1",
        "fileUrl": "",
        "fileMd5": ""
      },
      {
        "type": "uid",
        "content": "qianghou",
        "fileUrl": "",
        "fileMd5": ""
      },
      {
        "type": "all",
        "content": "999999",
        "fileUrl": "",
        "fileMd5": ""
      },
      {
        "type": "customTag",
        "relation": "1",
        "content": "[{\"table\":\"tag\",\"column\":\"12002\",\"operation\":\"==\",\"value\":\"1\"}, {\"table\":\"tag\",\"column\":\"12005\",\"operation\":\"!=\",\"value\":\"tag2_value1\"}]",
        "fileUrl": "",
        "fileMd5": ""
      }
    ]
  }
}

消息透传

推送透传消息时cmdData数组中的元素如下：

{
  "req": {
    "cmdId": 6362,
    "productId": 8903,
    "platform": "Android",
    "taskName": "taskName",
    "expireTime": 1561978029,
    "cmdData": ["data"],
    "isTest": 0,
    "audience": [
      {
        "type": "imei",
        "content": "",
        "fileUrl": "http://172.16.0.34:30010/private/2020031116155929020_1",
        "fileMd5": "c26598d376a2c1261abacb2834cb3cbe"
      },
      {
        "type": "model",
        "content": "华为",
        "fileUrl": "",
        "fileMd5": ""
      },
      {
        "type": "area",
        "content": "gz;sz",
        "fileUrl": "",
        "fileMd5": ""
      },
      {
        "type": "buildno",
        "content": "buildno1",
        "fileUrl": "",
        "fileMd5": ""
      },
      {
        "type": "uid",
        "content": "qianghou",
        "fileUrl": "",
        "fileMd5": ""
      },
      {
        "type": "all",
        "content": "999999",
        "fileUrl": "",
        "fileMd5": ""
      },
      {
        "type": "customTag",
        "relation": "1",
        "content": "[{\"table\":\"tag\",\"column\":\"12002\",\"operation\":\"==\",\"value\":\"1\"}, {\"table\":\"tag\",\"column\":\"12005\",\"operation\":\"!=\",\"value\":\"tag2_value1\"}]",
        "fileUrl": "",
        "fileMd5": ""
      }
    ]
  }
}

响应字段

网关返回码 ret

Data

Resp

data.resp.ret

响应示例

{
  "ret": 0,
  "data": {
    "resp": {
      "ret": 0,
      "taskId": 1234567890,
      "msg": "推送成功。可登录控制台在“消息推送 > 历史明细“查看推送记录"
    }
  }
}

推送结果查询 API

功能介绍

对推送单进行状态控制

请求地址

注意：地址中的IP 和端口是实际环境中的JsonProxy服务使用的IP和端口或URL。

http://172.16.0.34:30016/data/1960/forward

请求方式

POST

请求字段

请求示例

{
    "req":{
        "taskId":"2020033113075669466"
    }
}

响应字段

网关返回码 ret

Data

Resp

data.resp.ret

响应示例

{
    "ret":0,
    "data":{
        "resp":{
            "ret":0,
            "msg":"查询成功。可登录控制台在 “消息推送 > 历史明细 > 实时统计“ 查看详细。 ",
            "taskStatus":{
                "publishAmount":0,
                "reportAmount":0
            }
        }
    }
}

推送状态控制 API

功能介绍

查询指定推送单号的简要推送结果。

请求地址

注意： 地址中的IP 和端口是实际环境中的JsonProxy服务使用的IP和端口或URL。

http://172.16.0.34:30016/data/1961/forward

请求方式

POST

请求字段

请求示例

{
    "req":{
        "taskId":"2020011715420835906",
        "user":"system",
        "action":"Submit",
        "remark":"test"
    }
}

响应字段

网关返回码 ret

Data

Resp

data.resp.ret

响应示例

{
    "ret":0,
    "data":{
        "resp":{
            "ret":10101,
            "msg":"系统错误，2020011715420835906任务状态为投放结束不能提交"
        }
    }
}