Push · Html5+參考

# [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 : 無