推送高级接口。

接口说明

本接口区分Android和iOS平台,对于不同平台的推送调用时需要传入平台对应的AppKey。

调试

您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。

请求参数

名称 类型 是否必选 示例值 描述
Action String Push

系统规定参数。取值:Push

在node.js场景下,取值为PushInner

AppKey Long 23267207

AppKey信息。

Body String hello

Android推送时通知的内容/消息的内容;iOS消息/通知内容,推送的内容大小是有限制的,参见产品限制

DeviceType String ALL

设备类型,取值范围为:

  • iOS:iOS设备
  • ANDROID:Android设备
  • ALL:全部类型设备
说明 该参数仅对旧的不分端App有意义。新的分端App下,该参数填写“ALL”或与App分端类型对应的值均可。
PushType String MESSAGE

推送类型。取值:

  • MESSAGE:表示消息。
  • NOTICE:表示通知。
Target String ALL

推送目标。可取值:

  • DEVICE:根据设备推送。
  • ACCOUNT:根据账号推送。
  • ALIAS:根据别名推送。
  • TAG:根据标签推送。
  • ALL:推送给全部设备(同一种DeviceType的两次全推的间隔至少为1秒)。
  • TBD:初始化持续推送,推送目标由后续的ContinuouslyPush接口指定。
TargetValue String ALL

根据Target来设定,多个值使用逗号分隔,超过限制需要分多次推送。

  • Target=DEVICE,值如deviceid1,deviceid2(最多支持1000个)。
  • Target=ACCOUNT,值如account1,account2(最多支持1000个)。
  • Target=ALIAS,值如alias1,alias2(最多支持1000个)。
  • Target=TAG,支持单Tag和多Tag,格式请参见标签格式
  • Target=ALL,值为ALL
  • Target=TBD,值为TBD
Title String title

Android推送时通知/消息的标题以及iOS消息的标题(必填)。iOS 10+通知显示标题,(iOS 8.2 <= iOS系统 < iOS 10)替换通知应用名称(选填)。

JobKey String 123

JobKey信息。

SendSpeed Integer 0

该参数已废弃。

StoreOffline Boolean false

离线消息/通知是否保存。StoreOffline默认设置为false

若保存,在推送时候用户不在线,在过期时间(ExpireTime)内用户上线时会被再次发送。ExpireTime默认为72小时。iOS通知走Apns链路,不受StoreOffline影响。

PushTime String 2019-02-20T00:00:00Z

用于定时发送。不设置缺省是立即发送。

时间格式按照ISO8601标准表示,并需要使用UTC时间,格式为YYYY-MM-DDThh:mm:ssZ。注:Target为TBD(持续推送)时,不支持定时设置。

ExpireTime String 2019-02-20T00:00:00Z

离线消息/通知的过期时间,和StoreOffline配合使用,过期则不会再被发送,最长保存72小时。默认为72小时。

时间格式按照ISO8601标准表示,并需要使用UTC时间,格式为YYYY-MM-DDThh:mm:ssZ,过期时间不能小于当前时间或者定时发送时间加上3秒(ExpireTime > PushTime+ 3秒),3秒是为了冗余网络和系统延迟造成的误差。

iOSApnsEnv String DEV

iOS的通知是通过APNs中心来发送的,需要填写对应的环境信息。

  • DEV:表示开发环境。
  • PRODUCT:表示生产环境。
iOSRemind Boolean true

消息推送时设备不在线(既与移动推送的服务端的长连接通道不通),则这条推送会做为通知,通过苹果的APNs通道送达一次。

说明 离线消息转通知仅适用于生产环境。
iOSRemindBody String ios通知body

iOS消息转通知时使用的iOS通知内容,仅当iOSApnsEnv=PRODUCT && iOSRemind为true时有效。

iOSBadge Integer 0

iOS应用图标右上角角标。

说明 若iOSBadgeAutoIncrement设置为True,则此项必须为空。
iOSBadgeAutoIncrement Boolean true

是否开启角标自增功能,默认为false。

当该项为true时,iOSBadge必须为为空。角标自增功能由推送服务端维护每个设备的角标计数,需要用户使用1.9.5以上版本的sdk,并且需要用户主动同步角标数字到服务端。

iOSSilentNotification Boolean true

是否开启iOS静默通知。

iOSMusic String ""

iOS通知声音。指定存放在app bundle或沙盒Library/Sounds目录下的音频文件名,请参见:iOS推送如何设定通知声音

若指定为空串(””),通知为静音;若不设置,默认填充default为系统提示音。

iOSSubtitle String su'b

iOS通知副标题内容(iOS 10+)。

iOSNotificationCategory String ios

指定iOS通知Category(iOS 10+)。

iOSMutableContent Boolean true

是否使能iOS通知扩展处理(iOS 10+)。

iOSExtParameters String {“attachment”: “https://xxxx.xxx/notification_pic.png"}

iOS通知的扩展属性。

iOS10+可以在此指定富媒体推送通知的资源Url:{“attachment”: “https://xxxx.xxx/notification_pic.png"} 。该参数要以Json map的格式传入,否则会解析出错。

AndroidNotifyType String BOTH

通知的提醒方式。可取值:

  • VIBRATE:振动(默认值)
  • SOUND:声音
  • BOTH:声音和振动
  • NONE:静音
AndroidOpenType String APPLICATION

点击通知后动作。可取值:

  • APPLICATION:打开应用(默认值)
  • ACTIVITY:打开应用AndroidActivity
  • URL:打开URL
  • NONE:无跳转
AndroidActivity String com.alibaba.cloudpushdemo.bizactivity

设定通知打开的activity。

仅当AndroidOpenType=”Activity”时传入,如:com.alibaba.cloudpushdemo.bizactivity

AndroidMusic String

Android通知声音(保留参数,当前暂不起作用)。

AndroidOpenUrl String https://xxxx.xxx

Android收到推送后打开对应的url。

仅当AndroidOpenType=”URL”时传入。

AndroidXiaoMiActivity String

该参数已废弃,所有第三方辅助弹窗都由新参数AndroidPopupActivity统一支持。

AndroidXiaoMiNotifyTitle String

该参数已废弃,所有第三方辅助弹窗都由新参数AndroidPopupTitle统一支持。

AndroidXiaoMiNotifyBody String

该参数已废弃,所有第三方辅助弹窗都由新参数AndroidPopupBody统一支持。

AndroidPopupActivity String com.alibaba.cloudpushdemo.bizactivity

指定点击通知后跳转的Activity。

AndroidPopupTitle String hello

辅助弹窗模式下标题内容。AndroidPopupActivity参数不为空时,该参数必填。

标题长度限制:

  • 小米:50个字符,中英文都算一个。
  • 华为:未做明确限制,受payload整体长度限制。
  • 魅族:32个字符,中英文都算一个。
  • oppo:32个字符,中英文都算一个。
  • vivo:20个汉字,40个英文字符。
AndroidPopupBody String hello

辅助弹窗模式下Body内容。AndroidPopupActivity参数不为空时,该参数必填。

长度限制:

  • 小米:128个字符,中英文都算一个。
  • 华为:未做明确限制,受 payload整体长度限制。
  • 魅族:100个字符,中英文都算一个。
  • oppo:200个字符,中英文都算一个。
  • vivo:50个汉字,100个英文字符。
AndroidNotificationBarType Integer 2

Android自定义通知栏样式,取值:1-100。

AndroidNotificationBarPriority Integer 0

Android通知在通知栏展示时排列位置的优先级。可取值: -2,-1,0,1,2。

AndroidExtParameters String {"key1":"value1","api_name":"PushNoticeToAndroidRequest"}

设定通知的扩展属性。当推送类型PushType设置为MESSAGE消息类型时,该属性不生效。

该参数要以Json map的格式传入,否则会解析出错。

AndroidRemind Boolean true

推送类型为消息时设备不在线,则这条推送会使用辅助弹窗功能。默认值为false,仅当PushType=MESSAGE时生效。

如果消息转通知推送成功,收到通知是展示的数据为服务端设置的AndroidPopupTitle和AndroidPopupBody参数值,点击通知在辅助弹窗的onSysNoticeOpened方法中获取到的数据是服务端设置的Title和Body参数值。

AndroidNotificationChannel String 1

设置NotificationChannel参数,具体用途请参见常见问题:Android 8.0以上设备通知接收不到

AndroidNotificationXiaomiChannel String michannel

设置小米通知类型的channelId,需要在小米平台申请,详见:https://dev.mi.com/console/doc/detail?pId=2086

SmsTemplateName String 短信模板名称

补发短信的模板名,可以在短信模板管理界面获取,是系统分配的名称,而非开发者设置的名称。

SmsSignName String 短信签名

补发短信的签名。

SmsParams String key1=value1

短信模板的变量名值对,格式: key1=value1&key2=value2

SmsDelaySecs Integer 15

触发短信的延迟时间,秒。

推荐设置为 15 秒以上,避免短信和推送的重复。

SmsSendPolicy Integer 0

触发短信的条件。可取值:

  • 0:推送未收到时触发。
  • 1:用户未打开时触发。
AndroidNotificationVivoChannel String classification

设置vivo通知类型的classification,需要在vivo平台申请,详见:https://dev.vivo.com.cn/documentCenter/doc/359

返回数据

名称 类型 示例值 描述
MessageId String 501029

标志一次推送的消息ID。

RequestId String 9998B3CC-ED9E-4CB3-A8FB-DCC61296BFBC

请求ID。

示例

请求示例

http(s)://cloudpush.aliyuncs.com/?Action=Push
&AppKey=23267207
&Body=hello
&DeviceType=ALL
&PushType=MESSAGE
&Target=ALL
&TargetValue=ALL
&<公共请求参数>

正常返回示例

XML 格式

<PushResponse>
    <RequestId>9998B3CC-ED9E-4CB3-A8FB-DCC61296BFBC</RequestId>  
    <MessageId>501029</MessageId>
</PushResponse>

JSON 格式

{
  "RequestId": "9998B3CC-ED9E-4CB3-A8FB-DCC61296BFBC",
  "MessageId": "501029"
}

错误码

访问错误中心查看更多错误码。

Java示例代码


PushRequest pushRequest = new PushRequest();
// 推送目标
pushRequest.setAppKey(appKey);
pushRequest.setTarget("ALL"); //推送目标: DEVICE:推送给设备; ACCOUNT:推送给指定帐号,TAG:推送给自定义标签; ALIAS: 按别名推送; ALL: 全推
pushRequest.setTargetValue("all"); //根据Target来设定,如Target=DEVICE, 则对应的值为 设备id1,设备id2. 多个值使用逗号分隔.(帐号与设备有一次最多100个的限制)
pushRequest.setDeviceType("iOS"); // 设备类型deviceType, iOS设备: "iOS"; Android设备: "ANDROID"; 全部: "ALL", 这是默认值.
// 推送配置
pushRequest.setPushType("MESSAGE"); // MESSAGE:表示消息(默认), NOTICE:表示通知
pushRequest.setTitle("Hello"); // 消息的标题
pushRequest.setBody("PushRequest body"); // 消息的内容
// 推送配置: iOS
pushRequest.setIOSBadge(5); // iOS应用图标右上角角标
pushRequest.setIOSMusic("default"); // iOS通知声音
pushRequest.setIOSApnsEnv("PRODUCT");//iOS的通知是通过APNs中心来发送的,需要填写对应的环境信息。'DEV': 表示开发环境 'PRODUCT': 表示生产环境
pushRequest.setIOSRemind(true); //  消息推送时设备不在线(既与移动推送的服务端的长连接通道不通),则这条推送会做为通知,通过苹果的APNs通道送达一次。注意:**离线消息转通知仅适用于`生产环境`**
pushRequest.setIOSRemindBody("PushRequest summary"); // iOS消息转通知时使用的iOS通知内容,仅当iOSApnsEnv=`PRODUCT` && iOSRemind为true时有效
pushRequest.setIOSExtParameters("{\"k1\":\"ios\",\"k2\":\"v2\"}"); //通知的扩展属性(注意 : 该参数要以json map的格式传入,否则会解析出错)
// 推送配置: Android
pushRequest.setAndroidOpenType("ACTIVITY"); // 点击通知后动作 'APPLICATION': 打开应用 'ACTIVITY': 打开应用AndroidActivity 'URL': 打开URL 'NONE': 无跳转
pushRequest.setAndroidNotifyType("SOUND"); // 通知的提醒方式 ‘VIBRATE': 振动  'SOUND': 声音 'DEFAULT': 声音和振动 'NONE': 不做处理,用户自定义
pushRequest.setAndroidOpenUrl("http://www.alibaba.com");
pushRequest.setAndroidMusic("default"); // Android通知声音
pushRequest.setAndroidActivity("com.alibaba.push.PushActivity"); // Android收到推送后打开对应的ACTIVITY,仅当`AndroidOpenType="ACTIVITY"`有效
pushRequest.setAndroidPopupActivity("com.alibaba.push.PopupActivity"); //设置该参数后启动辅助弹窗功能, 此处指定通知点击后跳转的Activity(辅助弹窗的前提条件:1. 集成第三方辅助通道;2. StoreOffline参数设为true)
pushRequest.setAndroidPopupTitle("Popup Title"); //设置辅助弹窗通知的标题
pushRequest.setAndroidPopupBody("Popup Body"); //设置辅助弹窗通知的内容
pushRequest.setAndroidNotificationBarType(50); //Android自定义通知栏样式,取值:1-100
pushRequest.setAndroidNotificationBarPriority(2); //Android通知在通知栏展示时排列位置的优先级 -2 -1 0 1 2
pushRequest.setAndroidExtParameters("{\"k1\":\"android\",\"k2\":\"v2\"}"); //设定通知的扩展属性。(注意 : 该参数要以 json map 的格式传入,否则会解析出错)
// 推送控制
final Date pushDate = new Date(System.currentTimeMillis() + 3600 * 1000); //用于定时发送。不设置缺省是立即发送。时间格式按照ISO8601标准表示,并需要使用UTC时间,格式为`YYYY-MM-DDThh:mm:ssZ`。
final String pushTime = ParameterHelper.getISO8601Time(pushDate);
pushRequest.setPushTime(pushTime); // 延后推送。可选,如果不设置表示立即推送
pushRequest.setStoreOffline(true); // 离线消息是否保存,若保存, 在推送时候,用户即使不在线,下一次上线则会收到
final String expireTime = ParameterHelper.getISO8601Time(new Date(System.currentTimeMillis() + 12 * 3600 * 1000)); // 12小时后消息失效, 不会再发送
pushRequest.setExpireTime(expireTime);
// 短信融合通知
pushRequest.setSmsTemplateName("SMS_1234567"); // 设置短信模板名
pushRequest.setSmsSignName("测试"); //设置短信签名
pushRequest.setSmsParams("name=Bob&code=123"); // 短信模板变量
pushRequest.setSmsSendPolicy(0); // 补发短信的策略,0 表示当设备未收到推送时补发
pushRequest.setSmsDelaySecs(120); // 两分钟未收到触发短信
PushResponse pushResponse = client.getAcsResponse(pushRequest);
System.out.printf("RequestId: %s, MessageId: %s\n",
        pushResponse.getRequestId(), pushResponse.getMessageId());