推送API

1. 概述

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

2. 认证

为保证数据安全，GrowingIO所有的API服务，请求Head中需要携带 Token。

Token 获取详见：“GrowingIO接口认证”

3. 使用注意

1. 接口调用频率限制：单个 Token 调用限制 1200次/分钟。

2. 推送单条最大目标数限制：单次调用接口 audience 列表长度限制 2000 条。

3. 接口地址中的project_uid就是项目ＵID，指的是访问项目的时候，页面 URL 以 /projects/:project_uid 开头，例如 https://www.growingio.com/admin/projects/nxog09md/dashboard 中的 "nxog09mx"。

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推送数据