推送API

1. 概述

为满足广大客户更灵活创建推送的诉求,GrowingIO 提供了一套创建推送的API。本文档旨在说明一些调用流程,逻辑及相关接口说明。

2. 认证

为保证数据安全,GrowingIO所有的API服务,请求Head中需要携带 Token。
Token 获取详见:“GrowingIO接口认证”

3. 使用注意

  1. 1.
    接口调用频率限制:单个 Token 调用限制 1200次/分钟。
  2. 2.
    推送单条最大目标数限制:单次调用接口 audience 列表长度限制 2000 条。
  3. 3.
    接口地址中的project_uid就是项目UID,指的是访问项目的时候,页面 URL 以 /projects/:project_uid 开头,例如 https://www.growingio.com/admin/projects/nxog09md/dashboard 中的 "nxog09mx"。
  4. 4.
    接口参数中productId的获取方式:访问官网进入到推送的应用配置页面,点击目标推送应用的详细配置,浏览器地址栏的URL类似这样:https://www.growingio.com/projects/nxog09md/marketing-automation/manage/product/configuration/QPDM8loN,最后面的"QPDM8loN"就是productId。

4. 接口说明

地址:POST https://www.growingio.com/api/v1/projects/:project_id/meta/marketing_push
请求头(http header):
字段名
是否必传
说明
示例
Content-Type
固定传json类型
application/json
X-Client-Id
项目公钥,参考上面认证部分的文档
06b3f5ec564f590eb7435a8940c4f431
Authorization
Token+空格+真正的token,获取方式参考上面认证部分的文档
Token J8GL8w3gXUyZGMlEhme3acaCJKAHryzASR1WuHu2DrbUOS89HzaDdHIjCbizdgS8
请求对象:
字段名
字段格式
是否必传
说明
限制
示例
cid
字符串
cid 用于标示同一批推送消息。cid 相同的推送消息会聚合到同一个消息记录里,便于后续查看数据。同一个cid,同样的请求参数推送服务器不会生成新的推送任务,用于防止 api 调用端重试造成服务端的重复推送。建议使用 UUID 。
长度不超过64个字符
61b757af-f877-4e15-84f2-0f0eef69277c
name
字符串
推送名称。建议使用 业务含义名称 + 时间戳 ,不可重复,便于在管理后台查看使用。
长度不超过200个字符
用户召回推送20190716170520
packageName
字符串
推送应用包名。可以在应用管理后台获取,注意 sdk 上传的包名需要和后台配置的一致!
com.growingio.PushTest
productId
字符串
推送应用唯一标示,因为packageName苹果和安卓可能重复,使用productId能唯一标识出一个应用
QPDM8loN
audience
字符串数组
推送目标列表。
登录用户ID。一次推送最多 2000 个。
notification
对象
推送消息体。
-
options
对象
推送配置项。
-
使用建议:
  • 推送目标放在audience字段里,填入接入方系统里的登录用户ID,登录用户ID的含义可以参考这个文档:https://docs.growingio.com/v3/introduction/datamodel/usermodel/loginuser。再重申一下,就是接入SDK时上报的ID,理论上这个ID应该存储于接入方系统的数据库中。
  • 推送目标用户如果小于等于2000个,可以将所有目标设备标识放到一个请求里批量推送,推送完成之后建议更换cid和消息内容再进行下次推送。
  • 推送目标用户如果大于2000个,需要分批推送,每批目标设备标识个数小于等于2000,保证这些批次的cid相同和消息体内容相同,这样才能将这些批次的请求聚合,方便后续在web端查看消息状态
notification:
字段名
字段格式
是否必传
说明
限制
示例
title
字符串
通知标题。
长度不超过20个字符
新消息通知!
alert
字符串
通知内容。
长度不超过50个字符
收到一条新的留言,点击查看。
extras
对象
扩展字段,可以自定义 JSON 格式的 Key / Value 信息。这个字段暂时保留,可以先传空对象。
extras与actionParameters键值对不超过4个
{}
actionType
字符串
点击跳转链接类型。
打开网页:"openH5"
打开APP内具体某个页面:"openUrl"
自定义协议:"custom",自定义协议需要客户通过actionParameters传参数并解析
openUrl
actionTarget
字符串
点击跳转路径。
com.growingio.push
actionParameters
对象
点击跳转携带参数,以键值对形式传递。value不允许为null,不使用参数的情况下请传空对象
extras与actionParameters键值对不超过4个
{"key1": "value1", "key2": "value2"} 或 {}
options
字段名
类型
说明
示例
apnsProduction
字符串
true 表示推送生产环境,false 表示要推送开发环境;如果不指定则为推送生产环境。
ture
示例:
请求示例
成功返回示例
失败返回示例
1
{
2
"cid": "61b757af-f877-4e15-84f2-0f0eef69277c",
3
"name": "用户召回推送20190716170520",
4
"packageName": "com.growingio.PushTest",
5
"productId": "QPDM8loN",
6
"audience": ["d54f5085-a057-4aa0-8463-87a1fe56e9fe", "241131c1-f3ca-4584-99b5-8a5a8c50f9c7"],
7
"notification": {
8
"title": "新消息通知!",
9
"alert": "收到一条新的留言,点击查看。",
10
"extras": {
11
"key1": "value1",
12
"key2": "value2"
13
},
14
"actionType": "openUrl",
15
"actionTarget": "com.growingio.push",
16
"actionParameters": {
17
"key1": "value1",
18
"key2": "value2"
19
}
20
},
21
"options": {
22
"apnsProduction": true
23
}
24
}
Copied!
字段名
字段格式
说明
示例
cid
字符串
请求参数里的 cid
61b757af-f877-4e15-84f2-0f0eef69277c
taskId
字符串
任务ID,智能运营模块API单播功能查询使用
6gzPgHlS
1
HTTP/1.1 200 OK
2
Content-Type: application/json; charset=utf-8
3
4
Response Data
5
6
{
7
"cid" : "61b757af-f877-4e15-84f2-0f0eef69277c"
8
}
Copied!
字段名
字段格式
说明
示例
code
int
错误码
1011
message
string
错误描述
请求速度过快,请稍后再试
1
HTTP/1.1 400 OK
2
Content-Type: application/json; charset=utf-8
3
4
Response Data
5
6
{
7
"code" : 1011
8
"message" : "请求速度过快,请稍后再试"
9
}
Copied!
错误码及原因对照表
错误码
错误描述
备注
1001
请求body json校验不通过
1002
自定义异常,描述可能不同
1010
系统内部异常,请稍后再试
联系技术支持解决
1011
请求速度过快,请稍后再试
API不要请求过快
1012
API token校验不通过
1013
未找到项目
联系技术支持解决
1014
项目已被禁用
联系技术支持解决
1015
未找到对应产品,请检查参数packageName
1016
重复请求,请检查参数
两次请求的参数不能一模一样
1017
目标用户推送必备参数为空
请参考推送FAQ(API推送任务1017)排查
1018
未知异常,请更换cid后重试

5. 推送数据

API创建推送暂不支持用户运营平台推送任务列表页查看,推送数据请使用「产品分析」-> 「事件分析」查看,页面填写参数可参考如下:
触达推送名称(新旧版本可能存在GIO_区别) 对应发送body中的name
通过事件分析查看API推送数据