Push - 高级推送

高级推送接口,提供丰富的推送定制参数。

接口说明

请确保在使用该接口前,以充分了解 EMAS 移动推送产品的收费方式和价格

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

调试

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

授权信息

下表是API对应的授权信息,可以在RAM权限策略语句的Action元素中使用,用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下:

  • 操作:是指具体的权限点。
  • 访问级别:是指每个操作的访问级别,取值为写入(Write)、读取(Read)或列出(List)。
  • 资源类型:是指操作中支持授权的资源类型。具体说明如下:
    • 对于必选的资源类型,用背景高亮的方式表示。
    • 对于不支持资源级授权的操作,用全部资源表示。
  • 条件关键字:是指云产品自身定义的条件关键字。
  • 关联操作:是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限,操作才能成功。
操作访问级别资源类型条件关键字关联操作
mpush:Pushnone
*全部资源
*

请求参数

名称类型必填描述示例值
AppKeylong

AppKey 信息。

23267207
PushTypestring

推送类型。取值:

  • MESSAGE:表示消息。
  • NOTICE:表示通知。
MESSAGE
DeviceTypestring

设备类型,取值范围为:

  • HARMONY:鸿蒙设备
  • iOS:iOS 设备
  • ANDROID:Android 设备
  • ALL:当 AppKey 为旧版本双端应用时,代表同时推送 Android 和 iOS 设备;当 AppKey 为新版本单端应用时,效果和指定该应用类型对应的设备类型一样。
HARMONY
Targetstring

推送目标。可取值:

  • DEVICE:根据设备推送。
  • ACCOUNT:根据账号推送。
  • ALIAS:根据别名推送。
  • TAG:根据标签推送。
  • ALL:推送给全部设备(同一种 DeviceType 的两次全推的间隔至少为 1 秒)。
说明 对 iOS 设备全推,会推送给 24 个月内活跃过但未卸载的设备,一旦 APNs(苹果推送服务)接收到推送请求且未返回错误信息即为送达,导致活跃设备数暴增,从而产生大量费用,请您酌情使用。
  • TBD:初始化持续推送,推送目标由后续的 ContinuouslyPush 接口指定。
ALL
TargetValuestring

根据 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
ALL
StoreOfflineboolean

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

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

false
SendChannelsstring

指定发送通道,取值如下:

  • accs:阿里云自有通道
  • huawei:华为通道
  • honor:荣耀通道
  • xiaomi:小米通道
  • oppo:OPPO 通道
  • vivo:vivo 通道
  • meizu:魅族通道
  • gcm:谷歌 GCM 通道(旧版 HTTP)
  • fcm: 谷歌 Firebase 通道(HTTP v1 API)
  • apns:APNs 通道
  • harmony: 鸿蒙通道
说明
  • 如果未配置此参数,则代表所有通道均可使用。
  • 如果配置了此参数,则严格使用参数中的通道。
  • 如果配置的通道和发送策略冲突(如 iOS 通知仅走 APNs 通道,但本参数中不包含 apns),则不实施发送。
  • 若配置 gcm,则可以走谷歌 GCM 和 FCM 通道,若配置 fcm,则只能走谷歌 FCM 通道。
  • accs,huawei,xiaomi
    PushTimestring

    用于定时发送。不设置缺省是立即发送。 设置定时发送最迟不能晚于 7 天发送。

    时间格式按照 ISO8601 标准表示,并需要使用 UTC 时间,格式为 YYYY-MM-DDThh:mm:ssZ。

    说明 Target 为 TBD(持续推送)时,不支持定时设置。
    2019-02-20T00:00:00Z
    ExpireTimestring

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

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

    2019-02-20T00:00:00Z
    JobKeystring

    推送任务自定义标识,当 JobKey 不为空时,回执日志中会附带该字段。查看回执日志参见回执日志

    说明 格式要求:只能使用字母或数字或符号‘_’、‘-’任意一项或组合 ,且长度不超过 32 个字符
    123
    Titlestring

    推送时通知/消息的标题,长度限制:200 字节。

    在 Android 和 Harmony 推送时必填;在 iOS 通知时非必填,如果填写,则:

    • iOS 10+通知显示标题。

    • iOS 8.2 <= iOS 系统 < iOS 10:替换通知应用名称。

    title
    Bodystring

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

    hello
    Trimboolean

    是否自动对过长标题、内容进行截断。

    说明 仅支持明确限制标题、内容的厂商通道,对 APNs、华为、荣耀通道等不限制标题、内容,只限制总请求体大小的不适用。
    false
    iOSApnsEnvstring

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

    • DEV:表示开发环境。
    • PRODUCT:表示生产环境。
    DEV
    iOSRemindboolean

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

    说明 离线消息转通知仅适用于生产环境。
    true
    iOSSubtitlestring

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

    su'b
    iOSRemindBodystring

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

    ios通知body
    iOSMusicstring

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

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

    ""
    iOSBadgeinteger

    iOS 应用图标右上角角标。

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

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

    说明 当该项为 true 时,iOSBadge 必须为空。

    角标自增功能由推送服务端维护每个设备的角标计数,需要用户使用 1.9.5 以上版本的 SDK,并且需要用户主动同步角标数字到服务端。

    true
    iOSSilentNotificationboolean

    是否开启 iOS 静默通知。

    true
    iOSMutableContentboolean

    iOS 通知处理扩展标记(iOS 10+)。如果设为 true,则 APNs 推送的通知在弹出前,可先到达 Extension 进行处理。静默通知时,必须设为 true。

    true
    iOSNotificationCategorystring

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

    ios
    iOSNotificationCollapseIdstring

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

    ZD2011
    iOSNotificationThreadIdstring

    通过该属性对 iOS 的远程通知进行分组,标记折叠的组别识别名。 仅支持 iOS 12.0+版本。

    abc
    iOSInterruptionLevelstring

    中断级别,取值:

    • passive:系统在不点灯、不播放声音的情况下将通知添加到通知列表中。
    • active:系统立即显示通知,点亮屏幕,并可以播放声音。
    • time-sensitive:系统立即呈现通知,点亮屏幕,并可以播放声音,但不会突破系统通知控制。
    • critical:系统立即显示通知,屏幕亮起,并绕过静音开关播放声音。
    active
    iOSRelevanceScoredouble

    摘要突出显示分数。取值范围:[0,1]的浮点数。

    0.01
    iOSExtParametersstring

    iOS 通知的扩展属性。

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

    {"attachment": "https://xxxx.xxx/notification_pic.png"}
    AndroidNotifyTypestring

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

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

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

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

    true
    AndroidOpenTypestring

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

    • APPLICATION:打开应用(默认值)
    • ACTIVITY:打开应用 AndroidActivity
    • URL:打开 URL
    • NONE:无跳转
    APPLICATION
    AndroidActivitystring

    设定通知打开的 activity。

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

    com.alibaba.cloudpushdemo.bizactivity
    AndroidOpenUrlstring

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

    仅当 AndroidOpenType=”URL”时传入。

    https://xxxx.xxx
    AndroidPopupActivitystring

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

    com.alibaba.cloudpushdemo.bizactivity
    AndroidPopupTitlestring

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

    长度限制:30 字符。

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

    hello
    AndroidPopupBodystring

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

    长度限制:128 字符。

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

    hello
    AndroidRenderStyleinteger

    通知样式,取值为:

    • 0:标准模式(默认)
    • 1:长文本模式(支持华为、荣耀、小米、OPPO、魅族、自有通道)
    • 2:大图模式(仅支持小米)
    • 3:列表模式(支持华为、荣耀、小米、OPPO、自有通道)
    说明 若使用非标准模式,此参数必须提供。
    1
    AndroidBigTitlestring

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

    • 当前仅支持荣耀通道和华为通道 EMUI11 及以上版本。

    • 若长文本模式下未提供此参数,则从 Title、AndroidPopupTitle 里取第一个非空值。

    示例长标题
    AndroidBigBodystring

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

    当前支持:

    •  华为:EMUI10 及以上

    •  荣耀:Magic UI 4.0 及以上

    •  小米:MIUI10 及以上

    •  OPPO:ColorOS 5.0 以上

    •  魅族:Flyme

    •  自有通道:安卓 SDK3.6.0 及以上

    说明 若长文本模式下未提供此参数,则从 Body、AndroidPopupBody 里取第一个非空值。
    示例长文本
    AndroidBigPictureUrlstring

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

    https://imag.example.com/image.png
    AndroidXiaomiBigPictureUrlstring

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

    https://f6.market.xiaomi.com/download/MiPass/aaa/bbb.png
    AndroidImageUrlstring

    大图标 URL。 当前支持:

    • 华为 EMUI(仅长文本模式、Inbox 模式下适用)。

    • 荣耀 Magic UI(仅长文本模式下适用)。

    • 自有通道:安卓 SDK3.5.0 及以上。

    https://imag.example.com/image.png
    AndroidXiaomiImageUrlstring

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

    说明 上传到小米服务器上,返回的图标 URL。具体请参考:链接
    https://imag.example.com/image.png
    AndroidInboxBodystring

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

    • 华为:EMUI9 及以上
    • 荣耀:Magic UI 4.0 及以上
    • 小米:MIUI10 及以上
    • OPPO:ColorOS 5.0 以上
    • 自有通道:安卓 SDK3.6.0 及以上
    ["第一行","第二行"]
    AndroidNotificationBarTypeinteger

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

    2
    AndroidNotificationBarPriorityinteger

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

    0
    AndroidNotificationNotifyIdinteger

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

    100001
    AndroidNotificationChannelstring

    Android app 的 channelId,需要与 app 中的 channelId 能对应上。

    • 设置 NotificationChannel 参数,具体用途请参见常见问题:Android 8.0 以上设备通知接收不到
    • 因 OPPO 通知私信通道的 channel_id 与 app 的 channelId,故 OPPO 通道推送时,channel_id 取此值。
    • 华为、FCM、阿里云自有通道推送中,channel_id 取此值。
    1
    AndroidNotificationHuaweiChannelstring

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

    • LOW:资讯营销类消息
    • NORMAL:服务与通讯类消息
    说明
  • 当前华为通道建议使用 AndroidMessageHuaweiCategory 进行通知分类,可不再使用 AndroidNotificationHuaweiChannel。
  • 需要在 Huawei 平台申请,申请链接
  • LOW
    AndroidNotificationHonorChannelstring

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

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

    需要在荣耀平台申请,申请链接

    LOW
    AndroidNotificationXiaomiChannelstring

    设置小米通知类型的 channelId,需要在小米平台申请,详见:申请链接

    说明
  • 小米通道单个应用最多可申请 8 个 channel,请提前做好规划。
  • michannel
    AndroidNotificationVivoChannelstring

    设置 vivo 通知消息分类,取值为:

    • 0:运营类消息(默认)
    • 1:系统类消息
    说明
  • 当前 vivo 通道建议使用 AndroidMessageVivoCategory 进行通知分类,可不再使用 AndroidNotificationVivoChannel。
  • 需要在 vivo 平台申请,详见:申请链接
  • classification
    AndroidNotificationGroupstring

    消息分组,同一组消息在通知栏里只显示最新一条和当前该组接受到的消息总数目,不会展示所有消息也无法展开。当前支持:

    • 华为
    • 荣耀
    • 自有通道
    group-1
    AndroidNotificationThreadIdstring

    消息分组,同一组消息在通知栏里折叠展示,可展开,不同组通知分开展示。当前支持:

    • 自有通道 安卓 SDK3.9.2 及以上
    thread-1
    AndroidExtParametersstring

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

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

    {"key1":"value1","api_name":"PushNoticeToAndroidRequest"}
    AndroidMessageHuaweiUrgencystring

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

    • HIGH
    • NORMAL

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

    HIGH
    AndroidMessageHuaweiCategorystring

    作用一:完成自分类权益申请后,用于标识消息类型,确定消息提醒方式,对特定类型消息加快发送,取值请参考华为推送官方文档的消息分类标准,填写文档表格中的“云端通知 category 取值”或“本地通知 category 取值”。

    作用二:申请特殊权限后,用于标识高优先级透传场景,取值如下:

    • VOIP:音视频通话
    • PLAY_VOICE:语音播报
    说明 对于“云端通知 category 取值”为“不涉及”的一概走阿里云自有通道,对于“本地通知 category 取值”为“不涉及”的一概走华为通道。
    VOIP
    AndroidMessageOppoCategorystring

    OPPO 将消息分类:通讯与服务、内容与营销两个类别进行管理。

    通讯与服务(需申请权限):

    • IM:即时聊天、音频、视频通话
    • ACCOUNT:个人账号与资产变化
    • DEVICE_REMINDER:个人设备提醒
    • ORDER:个人订单/物流状态变化
    • TODO:个人日程/待办
    • SUBSCRIPTION:个人订阅

    内容与营销:

    • NEWS:新闻资讯
    • CONTENT:内容推荐
    • MARKETING:平台活动
    • SOCIAL:社交动态

    详细请参考 OPUSH 消息分类细则

    MARKETING
    AndroidMessageOppoNotifyLevelinteger

    OPPO 通道通知栏消息提醒等级。可取值为:

    • 1:通知栏
    • 2:通知栏+锁屏(通讯与服务类消息默认通知级别)
    • 16:通知栏+锁屏+横幅+震动+铃声(需申请权限)
    说明 使用 AndroidMessageOppoNotifyLevel 参数时,必须同时传 AndroidMessageOppoCategory 参数。
    1
    AndroidMessageVivoCategorystring

    vivo 将消息分为:系统消息、运营消息两个类别进行管理。 系统消息:

    • IM:即时消息
    • ACCOUNT:账号与资产
    • TODO:日程待办
    • DEVICE_REMINDER:设备信息
    • ORDER:订单与物流
    • SUBSCRIPTION:订阅提醒

    运营消息:

    • NEWS:新闻
    • CONTENT:内容推荐
    • MARKETING:运营活动
    • SOCIAL:社交动态

    详细请参考分类说明

    TODO
    AndroidTargetUserTypeinteger

    设置厂商通道通知类型:

    • 0:正式通知(默认)。
    • 1:测试通知。
    说明
  • 本参数配置后等价于同时配置 AndroidHuaweiTargetUserType、AndroidHonorTargetUserType、AndroidVivoPushMode 三个参数,具体厂商通道的对应参数能覆盖本参数。
  • 当前支持:华为通道、荣耀通道、vivo 通道。
  • 0
    AndroidHuaweiTargetUserTypeinteger

    设置华为通道通知类型:

    • 0:正式通知(默认)。
    • 1:测试通知。
    说明 每个应用每日可发送该测试通知 500 条且不受每日单设备推送数量上限要求。
    0
    AndroidHonorTargetUserTypeinteger

    设置荣耀通道通知类型:

    • 0:正式通知(默认)。
    • 1:测试通知。
    说明 每个应用每日可发送该测试通知 1000 条且不受每日单设备推送数量上限要求。
    0
    AndroidVivoPushModeinteger

    设置 vivo 通道通知类型:

    • 0:正式推送(默认)。
    • 1:测试推送。
    说明 测试推送请事先在 vivo 控制台配置测试设备。测试设备 RegId 可在设备启动日志中搜索“onReceiveRegId regId”获得。
    0
    AndroidHuaweiReceiptIdstring

    华为通道回执 ID,该回执 ID 可以在华为通道推送运营平台的回执参数配置中查看。

    说明 如果在华为通道推送运营平台配置的默认回执配置是阿里云回执,则无需提供,如果不是,建议优先在阿里云 EMAS 移动推送控制台中配置华为通道默认回执 ID。
    RCP4C123456
    AndroidVivoReceiptIdstring

    vivo 通道回执 ID,该回执 ID 可以在 vivo 开放平台推送服务的应用信息中查看。

    说明 如果在 vivo 开放平台配置的默认回执配置是阿里云回执,则无需提供,如果不是,建议优先在阿里云 EMAS 移动推送控制台中配置 vivo 通道默认回执 ID。
    123
    AndroidBadgeClassstring

    角标设置应用入口 Activity 的全类名

    说明 仅华为/荣耀产商通道推送时有效
    com.alibaba.cloudpushdemo.bizactivity
    AndroidBadgeAddNuminteger

    设置角标累加值,在原角标的基础上进行累加

    说明 仅华为/荣耀厂商通道推送时有效。AndroidBadgeAddNum 与 AndroidBadgeSetNum 同时存在时,以 AndroidBadgeSetNum 为准
    1
    AndroidBadgeSetNuminteger

    设置角标数字固定值,取值范围[1~99]。

    说明 仅华为,荣耀,阿里云通道推送时生效。 在小米机型上自有通道推送时为当前通知的 messageCount 的值。
    5
    AndroidMusicstring

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

    HarmonyRemindboolean

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

    如果消息转通知推送成功,收到通知是展示的数据为服务端设置的 HarmonyRemindTitle 和 HarmonyRemindBody 参数值。

    false
    HarmonyRemindTitlestring

    Harmony 消息转通知时使用的 Harmony 通知标题,仅当 HarmonyRemind 为 true 时有效。

    新消息
    HarmonyRemindBodystring

    Harmony 消息转通知时使用的 Harmony 通知内容,仅当 HarmonyRemind 为 true 时有效。

    您有一条新消息,请查收
    HarmonyCategorystring

    通知消息类别。完成申请通知消息自分类权益后,用于标识消息类型,不同的通知消息类型影响消息展示和提醒方式。取值如下:

    • IM:即时聊天
    • VOIP:音视频通话
    • SUBSCRIPTION:订阅
    • TRAVEL:出行
    • HEALTH:健康
    • WORK:工作事项提醒
    • ACCOUNT:账号动态
    • EXPRESS:订单&物流
    • FINANCE:财务
    • DEVICE_REMINDER:设备提醒
    • MAIL:邮件
    • CUSTOMER_SERVICE:客服消息
    • MARKETING:新闻、内容推荐、社交动态、产品促销、财经动态、生活资讯、调研、功能推荐、运营活动(仅对内容进行标识,不会加快消息发送),统称为资讯营销类消息

    详情参见鸿蒙官网 Notification.category

    IM
    HarmonyNotificationSlotTypestring

    使用指定类型的通知渠道。仅在阿里云自有通道在线时有效。

    • SOCIAL_COMMUNICATION: 社交通信。
    • SERVICE_INFORMATION: 服务提醒。
    • CONTENT_INFORMATION: 内容资讯。
    • CUSTOMER_SERVICE: 客服消息。该类型用于用户与商家之间的客服消息,需由用户主动发起。
    • OTHER_TYPES: 其他。

    详情参见鸿蒙官网 SlotType

    SOCIAL_COMMUNICATION
    HarmonyNotifyIdinteger

    每条消息在通知显示时的唯一标识。不携带时,推送服务自动为每条消息生成一个唯一标识;不同的通知消息可以拥有相同的 notifyId,实现新消息覆盖旧消息功能。

    详情参见鸿蒙官网 Notification.notifyId

    0
    HarmonyActionTypestring

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

    • APP_HOME_PAGE:打开应用首页
    • APP_CUSTOM_PAGE:打开应用自定义页面
    APP_HOME_PAGE
    HarmonyActionstring

    应用内置页面 ability 对应的 action。

    注意 当 HarmonyActionType 为 APP_CUSTOM_PAGE 时,字段 HarmonyUri 和 HarmonyAction 至少填写一个。

    详情参见鸿蒙官网 ClickAction.action

    com.example.action
    HarmonyUristring

    应用内置页面 ability 对应的 uri。

    注意 当 HarmonyActionType 为 APP_CUSTOM_PAGE 时,字段 HarmonyUri 和 HarmonyAction 至少填写一个。当存在多个 Ability 时,分别填写不同 Ability 的 action 和 uri,优先使用 action 查找对应的应用内置页面。

    详情参见鸿蒙官网 ClickAction.uri

    https://www.example.com:8080/push/example
    HarmonyRenderStylestring

    通知消息样式:

    • NORMAL: 普通通知(默认值)
    • MULTI_LINE: 多行文本样式
    NORMAL
    HarmonyImageUrlstring

    通知右侧大图标 URL,URL 使用的协议必须是 HTTPS 协议。

    说明 支持图片格式为 png、jpg、jpeg、heif、gif、bmp,图片长*宽<25000 像素。

    详情参见鸿蒙官网 Notification.image

    https://example.com/xxx.png
    HarmonyInboxContentstring

    多行文本样式的内容,当 HarmonyRenderStyle 为 MULTI_LINE 时,本字段必填,最多支持 3 条内容。

    ["1.content1","2.content2","3.content3"]
    HarmonyExtParametersstring

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

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

    {"key1":"value1","api_name":"PushNoticeToAndroidRequest"}
    HarmonyTestMessageboolean

    测试消息标识:

    • false:正常消息(默认值)
    • true:测试消息

    详情参见鸿蒙官网 pushOptions.testMessage

    true
    HarmonyReceiptIdstring

    鸿蒙通道回执 ID,该回执 ID 可以在鸿蒙通道推送运营平台的回执参数配置中查看。

    说明 如果在鸿蒙通道推送运营平台配置的默认回执配置是阿里云回执,则无需提供,如果不是,建议优先在阿里云 EMAS 移动推送控制台中配置鸿蒙通道默认回执 ID。

    详情参见鸿蒙官网 pushOptions.receiptId

    RCPB***DFD5
    HarmonyExtensionPushboolean

    PushType 为 NOTICE 时,是否为鸿蒙通知扩展消息。

    • true:发送通知扩展消息
    • false:发送普通通知

    通知扩展消息需要先在鸿蒙侧申请权限才能发送,相关内容请参考鸿蒙文档发送通知扩展消息
    鸿蒙 SDK1.2.0 版本开始支持。

    true
    HarmonyExtensionExtraDatastring

    通知扩展消息的额外数据。
    发送鸿蒙通知扩展消息时有效。
    概念上等同鸿蒙通知扩展消息的 extraData 字段,具体定义参考鸿蒙 ExtensionPayload 说明
    鸿蒙 SDK1.2.0 版本开始支持。

    示例额外数据
    HarmonyBadgeAddNuminteger

    鸿蒙应用角标累加数字。参考鸿蒙角标 addNum 字段说明
    鸿蒙 SDK1.2.0 版本开始支持。

    1
    HarmonyBadgeSetNuminteger

    鸿蒙应用角标设置数字。参考鸿蒙角标 setNum 字段说明。 鸿蒙 SDK1.2.0 版本开始支持。

    1
    SmsTemplateNamestring

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

    短信模板名称
    SmsSignNamestring

    补发短信的签名。

    短信签名
    SmsParamsstring

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

    key1=value1
    SmsDelaySecsinteger

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

    若使用短信联动必须设置,推荐设置为 15 秒以上,最大不超过 3 天,避免短信和推送的重复。

    说明 短信联动时,ExpireTime 参数失效,通知失效时间以 SmsDelaySecs 参数计算,失效时间为当前时间加上 SmsDelaySecs 时间。
    15
    SmsSendPolicyinteger

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

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

    该参数已废弃。

    0
    AndroidXiaoMiNotifyTitledeprecatedstring

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

    AndroidXiaoMiNotifyBodydeprecatedstring

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

    AndroidXiaoMiActivitydeprecatedstring

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

    请求参数补充说明

    Title/Body 展开说明如下:

    属性\推送类型消息(iOS)消息(Android)通知(iOS)通知(Android)
    Title消息标题,对应消息回调中 CCPSysMessage 的 title 字段CPushMessage.title 字段通知标题通知标题,通知回调方法(onNotificationOpened)
    Body消息体,对应消息回调中 CCPSysMessage 的 body 字段消息体,CPushMessage.content 字段通知内容通知内容,通知回调方法(onNotificationOpened)

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

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

    • 集成第三方辅助通道。
    • StoreOffline 参数设为 true。
    • 推送通知(无需设置 AndroidRemind)或者推送消息并设置 AndroidRemind 为 true。
    • 正确设置 AndroidPopupActivity、AndroidPopupTitle、AndroidPopupBody 参数。

    返回参数

    名称类型描述示例值
    object
    MessageIdstring

    标志一次推送的消息 ID。

    501029
    RequestIdstring

    请求 ID。

    9998B3CC-ED9E-4CB3-A8FB-DCC61296BFBC

    示例

    正常返回示例

    JSON格式

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

    错误码

    HTTP status code错误码错误信息描述
    400InvalidPeriod.ExceedDaysThe period between specified EndTime and StartTime exceeds %s days.开始时间和结束时间超过%s天。
    400Invalid%s.FormatThe specified %s format is invalid.参数格式错误。
    400AccountDisabledYour account is not enabled.功能未启用。
    400FileNotExistThe specified file does not exist.指定的文件不存在。
    400IncorrectPasswordThe password is incorrect.密码错误。
    400NotApnsCertificateThe Certificate is not an APNs certificate.不是APNs证书。
    400PermissionDeniedThe specified AppKey is not authorized.您没有访问该app的权限,请您检查Appkey参数是否属于该账户。
    400SendSpeedNotSupportedSendSpeed is not supported for specified Target.制定目标不支持SendSpeed参数。
    400SmsProfileConfigFailedFailed to configure SMS profile.SMS配置失败。
    400SmsProfileGetFailedFailed to get SMS profile.SMS配置获取失败。
    400SmsRoleAuthorizeFailedFailed to authorize SMS role.SMS角色授权失败。
    400SmsRoleUnauthorizedThe SMS role is unauthorized.SMS角色没有授权。
    400TagsNumberBeyondLimitThe number of tags bound to this app exceeds the limit.当前app绑定的tag数量超过限制。
    400TargetNotSupportedTarget is not supported for file push.文件推送不支持的Target。
    400Invalid%s.LengthExceedThe specified %s length cannot be greater than %s.参数长度超限。
    400Invalid%s.BytesExceedThe specified %s exceeds the %s bytes limit.参数的字节数超限。
    400Invalid%s.EmptyThe specified %s cannot be empty.参数不能为空。
    400Invalid.ParameterThe specified parameter is invalid: %s.参数%s无效。
    500InternalErrorThe request processing has failed due to some unknown error. Please try again. If the error still exists, submit a ticket.服务端错误,建议重试,仍然失败则提工单
    500TimeoutThe request processing is timeout.请求处理超时。

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

    变更历史

    变更时间变更内容概要操作
    2024-10-10OpenAPI 错误码发生变更、OpenAPI 入参发生变更查看变更详情
    2024-08-07OpenAPI 错误码发生变更、OpenAPI 入参发生变更查看变更详情
    2024-06-25OpenAPI 错误码发生变更、OpenAPI 入参发生变更查看变更详情
    2024-01-22OpenAPI 错误码发生变更查看变更详情
    2023-12-18OpenAPI 错误码发生变更、OpenAPI 入参发生变更查看变更详情
    2023-10-12OpenAPI 错误码发生变更、OpenAPI 入参发生变更查看变更详情
    2023-03-15OpenAPI 错误码发生变更、OpenAPI 入参发生变更查看变更详情
    2021-09-15OpenAPI 错误码发生变更、OpenAPI 入参发生变更查看变更详情

    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); // 离线消息是否保存,若保存, 在推送时候,用户即使不在线,下一次上线则会收到,安卓中若为 false 则只走阿里云自有在线通道
    final String expireTime = ParameterHelper.getISO8601Time(new Date(System.currentTimeMillis() + 12 * 3600 * 1000)); // 12 小时后消息失效, 不会再发送
    pushRequest.setExpireTime(expireTime);
    pushRequest.setSendChannels("accs,huawei,honor,vivo,xiaomi,oppo"); // 指定下发的推送通道,若不填可从任何可行的通道下发
    pushRequest.setAndroidNotificationNotifyId(1234567); // 设置通知覆盖参数,避免重试等场景用户显示多条相同的通知
    pushRequest.setAndroidTargetUserType(0); // 代表本次推送如果推送到华为、荣耀、vivo 通道,是一个正式通知,但本代码示例中这个值被厂商通道特有参数所覆盖
    pushRequest.setAndroidHuaweiTargetUserType(1); // 代表本次推送如果推送到华为通道,是一个测试性质的通知
    pushRequest.setAndroidHonorTargetUserType(1); // 代表本次推送如果推送到荣耀通道,是一个测试性质的通知
    pushRequest.setAndroidVivoPushMode(1); // 代表本次推送如果推送到华为通道,是一个测试性质的通知,请在推送前把 vivo 设备 regId 加入 vivo 推送平台的测试设备列表中
    pushRequest.setAndroidHuaweiReceiptId("ABCDEFG"); // 华为厂商通道
    // 厂商通道通知分类
    pushRequest.setAndroidNotificationChannel("user_define"); // OPPO 通道私信通道 channel_id,以及通用安卓 channel_id
    pushRequest.setAndroidNotificationXiaomiChannel("user_define"); //小米通道通知类型 channel_id
    pushRequest.setAndroidNotificationHonorChannel("NORMAL"); // 荣耀通道消息分类参数,对应荣耀通道 importance 参数
    pushRequest.setAndroidMessageHuaweiCategory("ACCOUNT"); // 华为通道的通知分类参数,服务与通讯类通知需向华为通道申请权限
    pushRequest.setAndroidMessageVivoCategory("ACCOUNT"); // vivo 通道的通知分类参数,系统消息需向 vivo 通道申请权限
    // 短信融合通知
    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());