运营平台使用指南

推送API

1. 概述

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

2. 认证

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

3. 使用注意

  1. 1.
    接口调用频率限制：单个 Token 调用限制 1200次/分钟。
  2. 2.
    推送单条最大目标数限制：单次调用接口 audience 列表长度限制 2000 条。
  3. 3.
    接口地址中的project_uid就是项目ＵID，指的是访问项目的时候，页面 URL 以 /projects/:project_uid 开头，例如 https://www.growingio.c​o​m/admin/p​rojects/nxo​g0​9md/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
示例：
请求示例
成功返回示例
失败返回示例
{
"cid": "61b757af-f877-4e15-84f2-0f0eef69277c",
"name": "用户召回推送20190716170520",
"packageName": "com.growingio.PushTest",
"productId": "QPDM8loN",
"audience": ["d54f5085-a057-4aa0-8463-87a1fe56e9fe", "241131c1-f3ca-4584-99b5-8a5a8c50f9c7"],
"notification": {
"title": "新消息通知！",
"alert": "收到一条新的留言，点击查看。",
"extras": {
"key1": "value1",
"key2": "value2"
},
"actionType": "openUrl",
"actionTarget": "com.growingio.push",
"actionParameters": {
"key1": "value1",
"key2": "value2"
}
},
"options": {
"apnsProduction": true
}
}
字段名
字段格式
说明
示例
cid
字符串
请求参数里的 cid
61b757af-f877-4e15-84f2-0f0eef69277c
taskId
字符串
任务ID，智能运营模块API单播功能查询使用
6gzPgHlS
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
​
Response Data
​
{
"cid" : "61b757af-f877-4e15-84f2-0f0eef69277c"
}
字段名
字段格式
说明
示例
code
int
错误码
1011
message
string
错误描述
请求速度过快，请稍后再试
HTTP/1.1 400 OK
Content-Type: application/json; charset=utf-8
​
Response Data
{
"code" : 1011
"message" : "请求速度过快，请稍后再试"
}
错误码及原因对照表
错误码
错误描述
备注
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推送数据
​
​
Previous
弹窗API
Next
产品使用文档
Last modified 2yr ago