push
Push模块管理推送消息功能,可以实现在线、离线的消息推送,通过plus.push可获取推送消息管理对象。
方法:
- addEventListener: 添加推送消息事件监听器
- clear: 清空所有推送消息
- createMessage: 创建本地消息
- getAllMessage: 获取所有推送消息
- getClientInfo: 获取客户端推送标识信息
- setAutoNotification: 设置客户端是否显示离线推送消息
- remove: 删除推送消息
对象:
- ClientInfo: JSON对象,获取的客户端标识信息
- PushMessage: JSON对象,推送消息对象
- MessageOption: JSON对象,获客户端创建本地消息的参数
回调方法:
- PushReceiveCallback: 客户端接收到推动消息的回调函数
- PushClickCallback: 获取设备方向信息失败的回调函数
权限:
permissions
"Push": { "description": "访问推送插件" }属性:
- cover: 设定显示推送消息的模式
可取值true或false,true表示推送消息覆盖模式显示,即仅显示最后接收到的推送消息;false表示多条推送消息独立显示,将在消息中心中显示多条消息内容。默认值为ture。
平台支持
- Android2.2+ (支持)
- iOS4.3+ (不支持): 不支持消息显示模式的设置,每条信息都在消息中心显示,忽略cover属性值。
- WP7.5+ (不支持)
addEventListener
添加推送消息事件监听器
void plus.push.addEventListener( event, listener, Boolean );
说明:
添加推送消息事件监听器,当指定推送事件发出时触发。
参数:
- type:
(
DOMString
)
必选 事件类型
- listener:
(
PushReceiveCallback
)
必选 事件监听器回调函数,在接收到推送消息时调用
- capture:
(
Boolean
)
可选 是否捕获事件,此处可忽略
返回值:
void : 无平台支持:
- Android2.2+ (支持)
- iOS4.3+ (支持): 支持,只有在客户端在运行时收到推送消息才能触发receive事件,离线接收到的推送消息全部进入系统消息中心。
- WP7.5+ (不支持)
示例:
<!DOCTYPE html> <html> <head> <meta charset="utf-8"/> <meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/> <title>Push Example</title> <script type="text/javascript"> // 监听plusready事件 document.addEventListener( "plusready", function(){ // 扩展API加载完毕,现在可以正常调用扩展API }, false ); // 添加监听从消息中心启动事件 plus.push.addEventListener( "click", function ( msg ) { // 分析msg.payload处理业务逻辑 alert( "You clicked: " + msg.message ); }, false ); } </script> </head> <body> </body> </html>
clear
清空所有推送消息
void plus.push.clear();
说明:
清空系统消息中心中所有的推送消息。
参数:
无
返回值:
void : 无createMessage
创建本地消息
void plus.push.createMessage( content, payload, option );
说明:
在本地直接创建推送消息,并添加到系统消息中心。
参数:
- content:
(
DOMString
)
必选
消息显示的内容,在系统通知中心中显示的文本内容。 - payload:
(
DOMString
)
可选
消息承载的数据,可根据业务逻辑自定义数据格式。 - option:
(
MessageOption
)
可选
创建消息的额外参数,参考MessageOption。
返回值:
void : 无平台支持:
- Android2.2+ (支持)
- iOS4.3+ (支持): title属性不生效(在系统通知中心显示的标题为程序的名称),content和payload的数据长度之和不能超过256个字节。
- WP7.5+ (不支持)
getAllMessage
获取所有推送消息
PushMessage[] plus.push.getAllMessage();
说明:
获取客户端接收到的所有推送消息。仅包括在系统消息中心中显示的推送消息,不包括调用setAutoNotification(false)方法设置不显示推送消息后接收到的消息。。
参数:
无
返回值:
PushMessage : Array[PushMessage]对象,推送消息PushMessage数组。平台支持:
- Android2.2+ (支持)
- iOS4.3+ (不支持): 调用此方法将返回空数组。
- WP7.5+ (不支持)
getClientInfo
获取客户端推送标识信息
ClientInfo plus.push.getClientInfo();
说明:
客户端标识信息用于业务服务器下发推送消息时提交给推送服务器的数据,用于说明下发推送消息的接收者(客户端)。需要客户端在第一次运行时提交到业务服务器保存。
参数:
无
返回值:
ClientInfo : 客户端推送标识信息对象示例:
<!DOCTYPE html> <html> <head> <meta charset="utf-8"/> <meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/> <title>Push Example</title> <script type="text/javascript"> // 监听plusready事件 document.addEventListener( "plusready", function(){ // 扩展API加载完毕,现在可以正常调用扩展API // 获取客户端标识信息 var info = plus.push.getClientInfo(); alert( JSON.stringify( info ) ); }, false ); // 添加监听从消息中心启动事件 plus.push.addEventListener( "click", function ( msg ) { // 分析msg.payload处理业务逻辑 alert( "You clicked: " + msg.message ); }, false ); } </script> </head> <body> </body> </html>
setAutoNotification
设置客户端是否显示离线推送消息
void plus.push.setAutoNotification( notify );
说明:
默认情况下客户端在接收到推送消息后将会在系统消息中心中显示,通过此方法可关闭默认行为,接收到推送消息后不在消息中心中显示,通过addEventListener方法的“receive”事件监听处理接收到的消息。可通过createMessage方法创建在消息中心中显示的消息。
参数:
- notify:
(
Boolean
)
必选 是否自动提示推送消息
可取值true或false,true表示自动显示推送消息,false则不显示。默认值为true。
返回值:
void : 无平台支持:
- Android2.2+ (支持)
- iOS4.3+ (支持): 仅在客户端在前台运行时设置的值生效。
- WP7.5+ (不支持)
示例:
<!DOCTYPE html> <html> <head> <meta charset="utf-8"/> <meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/> <title>Push Example</title> <script type="text/javascript"> // 监听plusready事件 document.addEventListener( "plusready", function(){ // 扩展API加载完毕,现在可以正常调用扩展API // 在程序运行时接收到的消息不显示在系统消息中心 plus.push.setAutoNotification( false ); }, false ); </script> </head> <body> </body> </html>
remove
删除推送消息
void plus.push.remove( message )
说明:
删除系统消息中心中指定的推送消息。可通过getAllMessage方法获取所有的消息
参数:
- message:
(
PushMessage
)
必选 要删除的消息对象,参考PushMessage
返回值:
void : 无平台支持:
- Android2.2+ (支持)
- iOS4.3+ (不支持): 调用此方法不做任何处理。
- WP7.5+ (不支持)
ClientInfo
JSON对象,获取的客户端标识信息
属性:
- token: (DOMString
类型
)设备令牌(客户端唯一标识),用于标识推送信息接收者身份
PushMessage
JSON对象,推送消息对象
属性:
- title: (DOMString
类型
)推送消息显示的标题
- content: (DOMString
类型
)推送消息显示的内容
- payload: (JSON
类型
)推送消息承载的数据
如果推送消息中传输的数据不符合JSON格式,则此时为String对象,保存数据内容。
MessageOption
JSON对象,获客户端创建本地消息的参数
属性:
- title: (DOMString
类型
)推送消息的标题
在系统消息中心显示,默认值为程序的名称。
- cover: (Boolean
类型
)是否覆盖上一次提示的消息
可取值true或false,true为覆盖,false不覆盖,默认为permission中设置的cover值。
- when: (Date
类型
)消息上显示的提示时间
默认为当前时间,如果使用的延迟显示则默认使用延时后的时间。
- delay: (Number
类型
)提示消息延迟显示的时间
当设备接收到推送消息后,可不立即显示,而是延迟一段时间显示,延迟时间单位为s,默认为0s,立即显示。
PushReceiveCallback
客户端接收到推动消息的回调函数
void onReceive( msg ) { // Recieved push message code. }
参数:
- msg:
(
DOMString
)
必选 接收到的推送信息msg
返回值:
void : 无PushClickCallback
获取设备方向信息失败的回调函数
void onClick( msg ) { // Clicked push message code. }
参数:
- msg:
(
DOMString
)
必选 用户点击的推送信息msg