Push模块管理推送消息功能,可以实现在线、离线的消息推送,通过plus.push可获取推送消息管理对象。
void plus.push.addEventListener( event, listener, Boolean );
说明:添加推送消息事件监听器,当指定推送事件发出时触发。
参数:
type: ( String ) 必选 事件类型,支持事件类型:"click"-从系统消息中心点击消息启动应用事件;"receive"-应用从推送服务器接收到推送消息事件。
listener: ( PushReceiveCallback ) 必选 事件监听器回调函数,在接收到推送消息时调用
capture: ( Boolean ) 可选 是否捕获事件,此处可忽略
返回值:void : 无
平台支持:Android - 2.2+ (支持),iOS - 4.3+ (支持): 在客户端在运行时收到推送消息触发receive事件,离线接收到的推送消息全部进入系统消息中心。
示例:
Push Example
void plus.push.clear();
说明:清空系统消息中心所有的推送消息。
返回值:void : 无
void plus.push.createMessage( content, payload, option );
说明:在本地直接创建推送消息,并添加到系统消息中心。
参数:
content: ( String ) 必选 消息显示的内容,在系统通知中心中显示的文本内容。
payload: ( String ) 可选 消息承载的数据,可根据业务逻辑自定义数据格式。
option: ( MessageOptions ) 可选 创建消息的额外参数,参考MessageOptions。
返回值:void : 无
PushMessage[] plus.push.getAllMessage();
说明:获取客户端接收到的所有推送消息。 仅包括在系统消息中心显示的推送消息,不包括调用setAutoNotification(false)方法设置不显示推送消息后接收到的消息。
返回值:PushMessage : Array[PushMessage]对象,推送消息PushMessage数组。
平台支持:Android - 2.2+ (支持),iOS - 4.3+ (不支持): 无法获取系统消息中心的消息列表,调用此方法返回空数组。
ClientInfo plus.push.getClientInfo();
说明:客户端标识信息用于业务服务器下发推送消息时提交给推送服务器的数据,用于说明下发推送消息的接收者(客户端)。需要客户端在第一次运行时提交到业务服务器保存。
返回值:ClientInfo : 客户端推送标识信息对象
示例:
Push Example
void plus.push.setAutoNotification( notify );
说明:默认情况下程序在接收到推送消息后将会在系统消息中心显示,通过此方法可关闭默认行为,接收到推送消息后不在系统消息中心显示,通过addEventListener方法的“receive”事件监听处理接收到的消息。 在这种模式下可通过createMessage方法创建在系统消息中心显示的消息。
参数:
notify: ( Boolean ) 必选 是否自动提示推送消息。可取值true或false,true表示自动显示推送消息,false则不显示。默认值为true。
返回值:void : 无
平台支持:Android - 2.2+ (支持): 如果程序没有运行时接收到推送消息,则在程序启动后调用addEventListener方法监听“receive”事件时返回接收到的消息。 注意:个推平台仅透传消息才支持此功能,其它消息依然会显示到系统消息中心。
iOS - 4.3+ (不支持): 无法修改是否显示离线推送消息,当程序在前台运行时接收到消息时一定不会添加到系统消息中心,当程序在不再前台运行时一定会添加到系统消息中。
示例:
Push Example
void plus.push.remove( message )
说明:删除系统消息中心指定的推送消息,可通过getAllMessage方法获取所有的消息后进行操作。
参数:message: ( PushMessage ) 必选 要删除的消息对象,可通过getAllMessage()方法来获取消息。
返回值:void : 无
平台支持:Android - 2.2+ (支持),iOS - 4.3+ (不支持): 无法对单条消息进行删除操作,可调用clear()方法清空所有消息。
属性:
(1)、token: (String 类型 )设备令牌(iOS设备唯一标识),用于APNS服务推送中标识设备的身份。平台支持Android - 2.2+ (支持): 设备的唯一标识号,通常与clientid值一致。iOS - 4.5+ (支持): 设备的DeviceToken值,向APNS服务器发送推送消息时使用。
(2)、clientid: (String 类型 )推送服务令牌(设备唯一标识),用于标识推送信息接收者身份。第三方推送服务器管理的设备唯一标识,在iOS平台此值通常与token不同;在其它平台此值通常与token值一致。
(3)、appid: (String 类型 )第三方推送服务的应用标识。第三方推送服务器管理的应用标识,通常需要在第三方推送服务器平台进行注册获取。
(4)、appkey: (String 类型 )第三方推送服务器的应用键值。第三方推送服务器管理的应用键值,通常需要在第三方推送服务器平台进行注册获取。
属性:
(1)、title: (String 类型 )推送消息显示的标题。平台支持Android - 2.2+ (支持)iOS - ALL (支持): 。
(2)、content: (String 类型 )推送消息显示的内容。
(3)、payload: (JSON 类型 )推送消息承载的数据。如果推送消息中传输的数据不符合JSON格式,则作为String类型数据保存。
(4)、aps: (JSON 类型 )Apple APNS推送协议数据。平台支持Android - 2.2+ (不支持): 不支持此数据,返回值为undefined。iOS - 5.0+ (支持): 仅封装标准APNS协议中的数据,其它数据封装在payload中。如果是通过本地API创建的消息此属性值则为undefined。
属性:
(1)、title: (String 类型 )推送消息的标题。在系统消息中心显示的通知消息标题,默认值为程序的名称。平台支持Android - ALL (支持),iOS - 5.0+ (不支持): 不支持设置消息的标题,固定为程序的名称。
(2)、sound: (String 类型 )推送消息的提示音,显示消息时的播放的提示音,可取值: “system”-表示使用系统通知提示音; “none”-表示不使用提示音; 默认值为“system”。平台支持Android - 2.3+ (支持),iOS - 5.1+ (支持): 当程序在前台运行时,提示音不生效。 注:通常应该设置延迟时间,当程序切换到后台才创建本地推送消息时生效。
(3)、cover: (Boolean 类型 )是否覆盖上一次提示的消息。可取值true或false,true为覆盖,false不覆盖,默认为permission中设置的cover值。平台支持
Android - ALL (支持)。iOS - 5.0+ (不支持): 不支持覆盖消息,只能创建新的消息。
(4)、when: (Date 类型 )消息上显示的提示时间。默认为当前时间,如果延迟显示则使用延时后显示消息的时间。平台支持Android - ALL (支持),iOS - 5.0+ (不支持): 不支持设定消息的显示时间,由系统自动管理消息的创建时间。
(5)、delay: (Number 类型 )提示消息延迟显示的时间。当设备接收到推送消息后,可不立即显示,而是延迟一段时间显示,延迟时间单位为s,默认为0s,立即显示。平台支持:Android - 2.2+ (支持),iOS - 4.3+ (支持): 不支持title、cover、when属性,忽略其属性值。
void onReceive( msg ) {
// Recieved push message code.
}
参数:msg: ( String ) 必选 接收到的推送信息msg
返回值:void : 无
void onClick( msg ) {
// Clicked push message code.
}
参数:msg: ( String ) 必选 用户点击的推送信息msg
返回值:void : 无