# [push]()
Push模块管理推送消息功能，可以实现在线、离线的消息推送，通过plus.push可获取推送消息管理对象。
### 方法：
- [addEventListener](http://www.dcloud.io/docs/api/zh_cn/push.shtml#plus.push.addEventListener): 添加推送消息事件监听器
- [clear](http://www.dcloud.io/docs/api/zh_cn/push.shtml#plus.push.clear): 清空所有推送消息
- [createMessage](http://www.dcloud.io/docs/api/zh_cn/push.shtml#plus.push.createMessage): 创建本地消息
- [getAllMessage](http://www.dcloud.io/docs/api/zh_cn/push.shtml#plus.push.getAllMessage): 获取所有推送消息
- [getClientInfo](http://www.dcloud.io/docs/api/zh_cn/push.shtml#plus.push.getClientInfo): 获取客户端推送标识信息
- [setAutoNotification](http://www.dcloud.io/docs/api/zh_cn/push.shtml#plus.push.setAutoNotification): 设置客户端是否显示离线推送消息
- [remove](http://www.dcloud.io/docs/api/zh_cn/push.shtml#plus.push.remove): 删除推送消息
### 对象：
- [ClientInfo](http://www.dcloud.io/docs/api/zh_cn/push.shtml#plus.push.ClientInfo): JSON对象，获取的客户端标识信息
- [PushMessage](http://www.dcloud.io/docs/api/zh_cn/push.shtml#plus.push.PushMessage): JSON对象，推送消息对象
- [MessageOption](http://www.dcloud.io/docs/api/zh_cn/push.shtml#plus.push.MessageOption): JSON对象，获客户端创建本地消息的参数
### 回调方法：
- [PushReceiveCallback](http://www.dcloud.io/docs/api/zh_cn/push.shtml#plus.push.PushReceiveCallback): 客户端接收到推动消息的回调函数
- [PushClickCallback](http://www.dcloud.io/docs/api/zh_cn/push.shtml#plus.push.PushClickCallback): 用户点击推送消息事件的回调函数
### 权限：
permissions
~~~
"Push": {
"description": "访问推送插件"
}
~~~
属性：
- cover: 设定显示推送消息的模式
可取值true或false，true表示推送消息覆盖模式显示，即仅显示最后接收到的推送消息；false表示多条推送消息独立显示，将在消息中心中显示多条消息内容。默认值为ture。
### 平台支持
- Android - 2.2+ (支持)
- iOS - 4.3+ (不支持): 不支持消息显示模式的设置，每条信息都在消息中心显示，忽略cover属性值。
# [addEventListener]()
添加推送消息事件监听器
~~~
void plus.push.addEventListener( event, listener, Boolean );
~~~
### 说明：
添加推送消息事件监听器，当指定推送事件发出时触发。
### 参数：
- type: *( DOMString ) 必选 *事件类型
- listener: *( [PushReceiveCallback](http://www.dcloud.io/docs/api/zh_cn/push.shtml#plus.push.PushReceiveCallback) ) 必选 *事件监听器回调函数，在接收到推送消息时调用
- capture: *( Boolean ) 可选 *是否捕获事件，此处可忽略
### 返回值：
void : 无
### 平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持): 支持，只有在客户端在运行时收到推送消息才能触发receive事件，离线接收到的推送消息全部进入系统消息中心。
### 示例：
~~~
<!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.addEventListener( "click", function ( msg ) {
// 分析msg.payload处理业务逻辑
alert( "You clicked: " + msg.content );
}, false );
}, 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](http://www.dcloud.io/docs/api/zh_cn/push.shtml#plus.push.MessageOption) ) 可选 *
创建消息的额外参数，参考MessageOption。
### 返回值：
void : 无
### 平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
# [getAllMessage]()
获取所有推送消息
~~~
PushMessage[] plus.push.getAllMessage();
~~~
### 说明：
获取客户端接收到的所有推送消息。仅包括在系统消息中心中显示的推送消息，不包括调用setAutoNotification(false)方法设置不显示推送消息后接收到的消息。
### 参数：
无
### 返回值：
[PushMessage](http://www.dcloud.io/docs/api/zh_cn/push.shtml#plus.push.PushMessage) : Array[PushMessage]对象，推送消息PushMessage数组。
### 平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (不支持): 无法获取系统消息中心中的消息列表，调用此方法将返回空数组。
# [getClientInfo]()
获取客户端推送标识信息
~~~
ClientInfo plus.push.getClientInfo();
~~~
### 说明：
客户端标识信息用于业务服务器下发推送消息时提交给推送服务器的数据，用于说明下发推送消息的接收者（客户端）。需要客户端在第一次运行时提交到业务服务器保存。
### 参数：
无
### 返回值：
[ClientInfo](http://www.dcloud.io/docs/api/zh_cn/push.shtml#plus.push.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 ) );
// 添加监听从消息中心启动事件
plus.push.addEventListener( "click", function ( msg ) {
// 分析msg.payload处理业务逻辑
alert( "You clicked: " + msg.content );
}, false );
}, false );
</script>
</head>
<body>
</body>
</html>
~~~
# [setAutoNotification]()
设置客户端是否显示离线推送消息
~~~
void plus.push.setAutoNotification( notify );
~~~
### 说明：
默认情况下客户端在接收到推送消息后将会在系统消息中心中显示，通过此方法可关闭默认行为，接收到推送消息后不在消息中心中显示，通过addEventListener方法的“receive”事件监听处理接收到的消息。可通过createMessage方法创建在消息中心中显示的消息。
### 参数：
- notify: *( Boolean ) 必选 *是否自动提示推送消息
可取值true或false，true表示自动显示推送消息，false则不显示。默认值为true。
### 返回值：
void : 无
### 平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持): 仅在客户端在前台运行时设置的值生效。
### 示例：
~~~
<!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](http://www.dcloud.io/docs/api/zh_cn/push.shtml#plus.push.PushMessage) ) 必选 *要删除的消息对象，可通过getAllMessage()方法来获取消息。
### 返回值：
void : 无
### 平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (不支持): 无法对单条消息进行删除操作，可调用clear()方法清空所有消息。
# [ClientInfo]()
JSON对象，获取的客户端标识信息
### 属性：
- token: *(DOMString 类型)*设备令牌（iOS设备唯一标识），用于APNS服务推送中标识设备的身份
### 平台支持
- Android - 2.2+ (支持): 设备的唯一标识号，通常与clientid值一致。
- iOS - 4.5+ (支持): 设备的DeviceToken值，向APNS服务器发送推送消息时使用。
- clientid: *(DOMString 类型)*推送服务令牌（设备唯一标识），用于标识推送信息接收者身份
第三方推送服务器管理的设备唯一标识，在iOS平台此值通常与token不同；在其它平台此值通常与token值一致。
- appid: *(DOMString 类型)*第三方推送服务的应用标识
第三方推送服务器管理的应用标识，通常需要在第三方推送服务器平台进行注册获取。
- appkey: *(DOMString 类型)*第三方推送服务器的应用键值
第三方推送服务器管理的应用键值，通常需要在第三方推送服务器平台进行注册获取。
# [PushMessage]()
JSON对象，推送消息对象
### 属性：
- title: *(DOMString 类型)*推送消息显示的标题
### 平台支持
- Android - 2.2+ (支持)
- iOS - ALL (支持): 。
- content: *(DOMString 类型)*推送消息显示的内容
- payload: *(JSON 类型)*推送消息承载的数据
如果推送消息中传输的数据不符合JSON格式，则作为String类型数据保存。
- aps: *(JSON 类型)*Apple APNS推送协议数据
### 平台支持
- Android - 2.2+ (不支持): 不支持此数据，返回值为undefined。
- iOS - 5.0+ (支持): 仅封装标准APNS协议中的数据，其它数据封装在payload中。如果是通过本地API创建的消息此属性值则为undefined。
# [MessageOption]()
JSON对象，获客户端创建本地消息的参数
### 属性：
- title: *(DOMString 类型)*推送消息的标题
在系统消息中心显示，默认值为程序的名称。若不支持此属性，在系统通知中心显示的标题固定为程序的名称
### 平台支持
- Android - ALL (支持)
- iOS - 5.0+ (不支持): 不支持设置消息的标题，标题固定为程序的名称。
- cover: *(Boolean 类型)*是否覆盖上一次提示的消息
可取值true或false，true为覆盖，false不覆盖，默认为permission中设置的cover值。
### 平台支持
- Android - ALL (支持)
- iOS - 5.0+ (不支持): 不支持覆盖消息，只能创建新的消息。
- when: *(Date 类型)*消息上显示的提示时间
默认为当前时间，如果使用的延迟显示则默认使用延时后的时间。
### 平台支持
- Android - ALL (支持)
- iOS - 5.0+ (不支持): 不支持设定消息的显示时间，由系统自动管理消息的创建时间。
- 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
### 返回值：
void : 无
- API参考
- Accelerometer
- Audio
- Camera
- Contacts
- Device
- Downloader
- Events
- Gallery
- Geolocation
- IO
- Key
- Messaging
- NativeUI
- Navigator
- Orientation
- Proximity
- SplashScreen
- Storage
- UI
- Uploader
- InterfaceOrientation
- Runtime
- WebView
- XMLHttpRequest
- Zip
- Plugins
- Barcode
- Maps
- Payment
- Push
- Share
- Speech
- Statistic
- Native.js
- Android
- iOS