调用Push推送高级接口。

# 接口说明

本接口区分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秒)。
    说明 对iOS设备全推,会推送给24个月内活跃过但未卸载的设备,一旦APNs(苹果推送服务)接收到推送请求且未返回错误信息即为送达,导致活跃设备数暴增,从而产生大量费用,请您酌情使用。
  • 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:替换通知应用名称(选填)。长度限制:200字节。

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

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

设置定时发送最迟不能晚于7天发送。

时间格式按照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秒是为了冗余网络和系统延迟造成的误差。建议单推不小于1分钟,全推、批量推送不少于10分钟。

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参数不为空时,该参数必填。

长度限制:30字符。

如使用厂商通道,则需同时符合厂商通道的限制,具体内容参见:Android端辅助通道推送限制

AndroidPopupBody String hello

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

长度限制:128字符。

如使用厂商通道,则需同时符合厂商通道的限制,具体内容参见:Android端辅助通道推送限制

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,需要在小米平台申请,详见:申请链接

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通知消息分类,取值为:

  • 0:运营类消息(默认)
  • 1:系统类消息

需要在vivo平台申请,详见:申请链接

AndroidNotificationHuaweiChannel String classification

设置Huawei通知消息分类importance参数,决定用户设备消息通知行为,取值如下:

  • LOW:资讯营销类消息
  • NORMAL:服务与通讯类消息

需要在Huawei平台申请,申请链接

AndroidNotificationNotifyId Integer 100001

标识每条消息在通知显示时的唯一标识,不同的通知栏消息可以相同的NotifyId,实现新的通知栏消息覆盖老的,当前支持除vivo通道外的其他厂商通道。

iOSNotificationCollapseId String ZD2011

设备收到有相同CollapseId的消息,会合并成一条。设备不在线,连续发相同CollapseId的消息,通知栏只会显示一条,iOS 10+支持设置此参数。

AndroidRenderStyle Integer 1

通知样式,取值为:

  • 0:标准模式(默认)
  • 1:长文本模式
  • 2:大图模式(仅支持小米)
说明 若使用长文本模式、大图模式,此参数必须提供。

当前支持:

  •  华为:EMUI 9及以上
  •  小米:MIUI10及以上
  •  OPPO:ColorOS5.0以上
  •  魅族:Flyme
  •  自有通道:安卓SDK3.6.0及以上
AndroidBigTitle String 示例长标题

长文本模式下的标题,长度限制:200个字节(1个汉字算作3字节)。

  • 当前仅支持华为通道EMUI11及以上版本。
  • 若长文本模式下未提供此参数,则从Title、AndroidPopupTitle里取第一个非空值。
AndroidBigBody String 示例长文本

长文本模式下的body,长度限制:1000字节(1个汉字算作3字节),发送时受具体厂商通道的限制。

当前支持:

  •  华为:EMUI10及以上
  •  小米:MIUI10及以上
  •  OPPO:ColorOS 5.0以上
  •  魅族:Flyme
  •  自有通道:安卓SDK3.6.0及以上
说明 若长文本模式下未提供此参数,则从Body、AndroidPopupBody里取第一个非空值。
AndroidXiaomiBigPictureUrl String https://f6.market.xiaomi.com/download/MiPass/aaa/bbb.png

大图模式下的大图URL。大图模式下图片上传至小米推送后会返回一个图片URL,本参数内填写这个URL。

iOSNotificationThreadId String abc

通过该属性对iOS的远程通知进行分组,标记折叠的组别识别名。

仅支持iOS 12.0+版本。

AndroidBigPictureUrl String https://imag.example.com/image.png

大图模式下的图片URL,当前支持:自有通道:安卓SDK3.6.0及以上。

AndroidInboxBody String ["第一行","第二行"]

Inbox模式下的正文,内容为合法的JSON Array,且元素不超过5个。

当前支持:

  • 华为:EMUI9及以上
  • 安卓SDK3.6.0及以上
AndroidImageUrl String https://imag.example.com/image.png

大图标URL。

当前支持:

  • 华为EMUI(仅长文本模式、Inbox模式下适用)
  • 自有通道:安卓SDK3.5.0及以上
AndroidXiaomiImageUrl String https://imag.example.com/image.png

大图URL。当前支持:小米MIUI12及以上(仅长文本模式下适用)。

说明 上传到小米服务器上,返回的图标URL。具体请参考:链接
AndroidMessageHuaweiUrgency String HIGH

华为通道透传消息投递优先级,取值如下:

  • HIGH
  • NORMAL

需要申请权限,具体请参见:申请链接

AndroidMessageHuaweiCategory String VOIP

华为通道标识高优先级透传消息的特殊场景,取值如下:

  • PLAY_VOICE:语音播报
  • VOIP:VoIP电话

需申请特殊权限,详见:链接

SendChannels String accs,huawei,xiaomi

指定发送通道(测试中功能,仅可用于纯安卓应用),取值如下:

  • accs:阿里自有通道
  • huawei:华为通道
  • xiaomi:小米通道
  • meizu:魅族通道
  • vivo:vivo通道
  • oppo:OPPO通道

返回数据

名称 类型 示例值 描述
RequestId String 9998B3CC-ED9E-4CB3-A8FB-DCC61296BFBC

请求ID。

MessageId String 501029

标志一次推送的消息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"
}

错误码

HttpCode 错误码 错误信息 描述
400 InvalidPeriod.ExceedDays The period between specified EndTime and StartTime exceeds %s days. 开始时间和结束时间超过%s天。
400 Invalid%s.Format The specified %s format is invalid. 参数格式错误。
400 AccountDisabled Your account is not enabled. 功能未启用。
400 FileNotExist The specified file does not exist. 指定的文件不存在。
400 IncorrectPassword The password is incorrect. 密码错误。
400 NotApnsCertificate The Certificate is not an APNs certificate. 不是APNs证书。
400 PermissionDenied The specified AppKey is not authorized. 您没有访问该app的权限,请您检查Appkey参数是否属于该账户。
400 SendSpeedNotSupported SendSpeed is not supported for specified Target. 制定目标不支持SendSpeed参数。
400 SmsProfileConfigFailed Failed to configure SMS profile. SMS配置失败。
400 SmsProfileGetFailed Failed to get SMS profile. SMS配置获取失败。
400 SmsRoleAuthorizeFailed Failed to authorize SMS role. SMS角色授权失败。
400 SmsRoleUnauthorized The SMS role is unauthorized. SMS角色没有授权。
400 TagsNumberBeyondLimit The number of tags bound to this app exceeds the limit. 当前app绑定的tag数量超过限制。
400 TargetNotSupported Target is not supported for file push. 文件推送不支持的Target。
400 Invalid%s.LengthExceed The specified %s length cannot be greater than %s. 参数长度超限。
400 Invalid%s.BytesExceed The specified %s exceeds the %s bytes limit. 参数的字节数超限。
400 Invalid%s.Empty The specified %s cannot be empty. 参数不能为空。
400 Invalid.Parameter The specified parameter is invalid: %s. 参数%s无效。
500 InternalError The request processing has failed due to some unknown error. Please try again. If the error still exists, submit a ticket. 服务端错误,建议重试,仍然失败则提工单

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

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());