全部产品
云市场

推送高级接口

更新时间:2019-10-14 16:54:29

Push

描述

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

调试

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

请求参数

基础参数

名称 类型 是否必须 描述
Action String 操作接口名称,取值:Push
AppKey Long AppKey信息

推送目标(destination)

名称 类型 是否必须 描述
Target String 推送目标:
  • DEVICE:根据设备推送
  • ACCOUNT:根据账号推送
  • ALIAS:根据别名推送
  • TAG:根据标签推送
  • ALL:推送给全部设备(同一种DeviceType的两次全推的间隔至少为1秒)
  • TBD:初始化持续推送,推送目标由后续的ContinuouslyPush接口指定
TargetValue String 根据Target来设定,多个值使用逗号分隔,超过限制需要分多次推送。
  • Target=DEVICE,值如deviceid1,deviceid2(最多支持1000个)
  • Target=ACCOUNT,值如account1,account2(最多支持100个)
  • Target=ALIAS,值如alias1,alias2(最多支持1000个)
  • Target=TAG,支持单Tag和多Tag,格式请参考 标签格式
  • Target=ALL,值为ALL
  • Target=TBD,值为TBD
DeviceType String 设备类型,取值范围为:
  • iOS:iOS设备
  • ANDROID:Android设备
  • ALL:全部类型设备
注:该参数仅对旧的不分端App有意义;新的分端App下,该参数填写”ALL”或与App分端类型对应的值均可。

推送配置(config)

名称 类型 是否必须 描述
PushType String
  • MESSAGE:表示消息,
  • NOTICE:表示通知
Title String Android推送时通知/消息的标题以及iOS消息的标题(必填),iOS 10+通知显示标题,[ iOS 8.2 <= iOS系统 < iOS 10 ]替换通知应用名称(选填)
Body String Android推送时通知的内容/消息的内容;iOS消息/通知内容,推送的内容大小是有限制的,参照 产品限制

Title/Body 展开说明如下:

属性\推送类型 消息 - iOS 消息 - Android 通知 - iOS 通知 - Android
Title 消息标题,对应消息回调中CCPSysMessagetitle字段 CPushMessage.title字段 通知标题(参照上述配置) 通知标题,通知回调方法(onNotificationOpened
Body 消息体,对应消息回调中CCPSysMessagebody字段 消息体,CPushMessage.content字段 通知内容 通知内容,通知回调方法(onNotificationOpened

下述配置仅作用于iOS通知任务

名称 类型 是否必须 描述
iOSMusic String iOS通知声音,指定存放在app bundle或沙盒Library/Sounds目录下的音频文件名,参考:iOS推送如何设定通知声音,(若指定为空串(””),通知为静音;若不设置,默认填充default为系统提示音)
iOSBadge Integer iOS应用图标右上角角标。注意,若iOSBadgeAutoIncrement设置为True,则此项必须为空。
iOSBadgeAutoIncrement Boolean 是否开启角标自增功能,默认为False,当该项为True时,iOSBadge必须为为空。角标自增功能由推送服务端维护每个设备的角标计数,需要用户使用1.9.5以上版本的sdk,并且需要用户主动同步角标数字到服务端。
iOSSilentNotification Boolean 开启iOS静默通知
iOSSubtitle String iOS通知副标题内容(iOS 10+)
iOSNotificationCategory String 指定iOS通知Category(iOS 10+)
iOSMutableContent Boolean 是否使能iOS通知扩展处理(iOS 10+)
iOSExtParameters String iOS通知的扩展属性,iOS 10+ 可以在此指定富媒体推送通知的资源Url: {“attachment”: “https://xxxx.xxx/notification_pic.png"} (注意 : 该参数要以json map的格式传入,否则会解析出错)
iOSApnsEnv String iOS的通知是通过APNs中心来发送的,需要填写对应的环境信息。
  • DEV:表示开发环境
  • PRODUCT:表示生产环境
iOSRemind Boolean 消息推送时设备不在线(既与移动推送的服务端的长连接通道不通),则这条推送会做为通知,通过苹果的APNs通道送达一次。注意:离线消息转通知仅适用于生产环境
iOSRemindBody String iOS消息转通知时使用的iOS通知内容,仅当iOSApnsEnv=PRODUCT && iOSRemind为true时有效

下述配置仅作用于Android通知任务

名称 类型 是否必须 描述
AndroidMusic String Android通知声音(保留参数,当前暂不起作用)
AndroidOpenType String 点击通知后动作
  • APPLICATION:打开应用 默认值
  • ACTIVITY:打开应用AndroidActivity
  • URL:打开URL
  • NONE:无跳转
AndroidNotifyType String 通知的提醒方式
  • VIBRATE:振动 默认值
  • SOUND:声音
  • BOTH:声音和振动
  • NONE:静音
AndroidActivity String 设定通知打开的activity,仅当AndroidOpenType=”Activity”有效,如:com.alibaba.cloudpushdemo.bizactivity
AndroidOpenUrl String Android收到推送后打开对应的url,仅当AndroidOpenType=”URL”有效
AndroidNotificationBarType Integer Android自定义通知栏样式,取值:1-100
AndroidNotificationBarPriority Integer Android通知在通知栏展示时排列位置的优先级 -2 -1 0 1 2
AndroidNotificationChannel String 设置NotificationChannel参数,具体用途请参考常见问题:Android 8.0以上设备通知接收不到
AndroidExtParameters String 设定通知的扩展属性。(注意 : 该参数要以 json map 的格式传入,否则会解析出错)

下述配置仅作用于Android辅助弹窗功能

推送时设备不在线(既与移动推送的服务端的长连接通道不通),则这条推送可以启动辅助弹窗功能,启动辅助弹窗功能参考移动推送辅助通道配置,且需要具备如下条件:

  1. 集成第三方辅助通道;
  2. StoreOffline参数设为true;
  3. 推送通知(无需设置AndroidRemind)或者推送消息并设置AndroidRemind为True
  4. 正确设置AndroidPopupActivity、AndroidPopupTitle、AndroidPopupBody参数。
名称 类型 是否必须 描述
AndroidRemind Boolean 推送类型为消息时设备不在线,则这条推送会使用辅助弹窗功能。默认值为False,仅当PushType=MESSAGE时生效。
AndroidPopupActivity String 此处指定通知点击后跳转的Activity。注:原AndroidXiaoMiActivity参数已废弃,所有第三方辅助弹窗都由新参数统一支持。
AndroidPopupTitle String 辅助弹窗模式下 Title 内容。AndroidPopupActivity 参数不为空时,该参数必填。 标题长度限制:
  • 小米:50个字符,中英文都算一个;
  • 华为:未做明确限制,受payload整体长度限制;
  • 魅族: 32个字符,中英文都算一个;
  • oppo:32个字符,中英文都算一个;
  • vivo: 20个汉字,40个英文字符)注:原AndroidXiaoMiNotifyTitle参数已废弃,所有第三方辅助弹窗都由新参数统一支持。
AndroidPopupBody String 辅助弹窗模式下 Body 内容。AndroidPopupActivity参数不为空时,该参数必填。长度限制:
  • 小米:128个字符,中英文都算一个;
  • 华为:未做明确限制,受 payload整体长度限制;
  • 魅族:100个字符,中英文都算一个;
  • oppo:200个字符,中英文都算一个;
  • vivo:50个汉字,100个英文字符);
注:原AndroidXiaoMiNotifyBody参数已废弃,所有第三方辅助弹窗都由新参数统一支持

推送控制(push control)

名称 类型 是否必须 描述
PushTime String 用于定时发送。不设置缺省是立即发送。时间格式按照ISO8601标准表示,并需要使用UTC时间,格式为YYYY-MM-DDThh:mm:ssZ。注:TargetTBD(持续推送)时,不支持定时设置。
StoreOffline Boolean 离线消息/通知是否保存。若保存,在推送时候用户不在线,在过期时间(ExpireTime)内用户上线时会被再次发送。StoreOffline默认设置为false,ExpireTime默认为72小时。(iOS通知走Apns链路,不受StoreOffline影响)
ExpireTime String 离线消息/通知的过期时间,和StoreOffline配合使用,过期则不会再被发送,最长保存72小时。默认为72小时。时间格式按照ISO8601标准表示,并需要使用UTC时间,格式为YYYY-MM-DDThh:mm:ssZ,过期时间不能小于当前时间或者定时发送时间加上3秒(ExpireTime > PushTime + 3秒),3秒是为了冗余网络和系统延迟造成的误差。

短信融合

参数名 类型 是否必需 描述
SmsTemplateName String 必选 补发短信的模板名,可以在短信模板管理界面获取,是系统分配的名称,而非开发者设置的名字
SmsSignName String 必选 补发短信的签名
SmsParams String 可选 短信模板的变量名值对,格式: key1=value1&key2=value2
SmsDelaySecs int 必选 触发短信的延迟时间,秒。推荐设置为 15 秒以上,避免短信和推送的重复
SmsSendPolicy int 可选,默认 0 触发短信的条件:0 推送未收到时触发,1 用户未打开时触发

响应参数

名称 类型 描述
MessageId String 标志一次推送的消息ID

错误码

错误代码 描述 HTTP 状态码 语义
InvalidDeviceType.NotMatch Specified DeviceType does no match the app. 400 DeviceType和指定app的类型不匹配
AppNotConfigIOS The Certificate of specified ApnsEnv of the app is not configured. 400 没有配置对应环境的证书
AppNotConfigAndroid The PackageName of specified app is not configured. 400 没有配置PackageName
InvalidPayload.BytesExceed Specified Payload exceeds the 1800 bytes limit. 400 消息或者通知内容长度超限
IosBadgeConflict Specified iOSBadge must be null when iOSBadgeAutoIncrement is true. 400 角标自增与角标数不能同时设置
SmsTemplateNameEmpty SmsTemplateName can’t be empty when sending sms. 400 短信融合推送时SmsTemplateName不能为空
SmsSignNameEmpty SmsSignName can’t be empty when sending sms. 400 短信融合推送时SmsSignName不能为空
SendSpeedNotSupported SendSpeed is not supported for specified Target. 400 当前推送条件不支持设置SendSpeed
ContinuousPushNotSupportDelay Continuous push not support delay. 400 持续推送不支持设置定时

示例

请求示例

  1. http://cloudpush.aliyuncs.com/?Action=Push
  2. &AppKey=23267207
  3. &Target=ALL&
  4. &TargetValue=ALL
  5. &Title=hello
  6. &Body=hello
  7. &PushType=MESSAGE
  8. &AndroidOpenType=APPLICATION
  9. &DeviceType=iOS
  10. &iOSRemind=true
  11. &iOSRemindBody="iOS Body"
  12. &StoreOffline=false
  13. &<公共请求参数>

返回示例

XML格式

  1. <?xml version='1.0' encoding='UTF-8'?>
  2. <PushResponse>
  3. <RequestId>9998B3CC-ED9E-4CB3-A8FB-DCC61296BFBC</RequestId>
  4. <MessageId>501029</MessageId>
  5. </PushResponse>

JSON格式

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

Java示例代码

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