Join MDN and developers like you at Mozilla's View Source conference, 12-14 September in Berlin, Germany. Learn more at https://viewsourceconf.org

Simple Push API

這是一個實驗中的功能
此功能在某些瀏覽器尚在開發中,請參考兼容表格以得到不同瀏覽器用的前輟。

Simple Push API 也是所謂的 Push Notification API,可在接收通知時喚醒 App。多個 App 可請求「共用其伺服器」的單一網址,以便傳送 App 的後續版本號碼。另外亦可作為同步化機制,從第三方伺服器取得最新資料。

SimplePush API 可透過 push 屬性 (來自於 PushManager 專案) 而擴充 window.navigator,並添增新的事件給使用者,以監控推播 (Push) 的狀態。

範例

在本範例中,我們將依照下列步驟而設定完整的推播:

  1. push 的授權新增至 manifest 檔案中
  2. 呼叫 push.register() 以請求終端 (Endpoint)
  3. 將終端傳送到自己的伺服器
  4. 針對 App 之內的推播通知,新增訊息處理器 (Message handler)
  5. 從自己的伺服器中送出通知

修改 manifest 檔案

另外需修改 manifest 檔案中的 2 個地方:

  1. messages 欄位:新增 pushpush-register 訊息。
  2. permissions 欄位:新增想要接收推播通知的 App。
"messages": [
   { "push": "/index.html"},
   { "push-register": "/index.html"}
],
"permissions": {
  "push": {
    "description": "Required for be updated with new goals in soccer matchs",  
  }
}

呼叫 PushManager.register 以請求終端

一旦你認為該是請求終端的時候 (例如使用者登入,或有人想看場棒球賽的時候),即可呼叫此程式碼。

if (navigator.push) {
  var req = navigator.push.register();
  
  req.onsuccess = function(e) {
    var endpoint = req.result;
      debug("New endpoint: " + endpoint );
    }

   req.onerror = function(e) {
     debug("Error getting a new endpoint: " + JSON.stringify(e));
   }
} else {
  // No push on the DOM
}

將終端傳送至自己的伺服器

一旦獲得終端之後,就必須將之傳送至自己的 App 伺服器上。現有很多傳送終端的方法,如寄送電子郵件,或透過 POST、PUT、GET 均可傳送終端。我們建議以「來自於 App 的使用者資料」來儲存終端,例如 cookie、使用者名稱,或任何你用來識別終端使用者的資料均可。

但如果你正把資料傳送到伺服器,我們還是建議下列要點:

  1. 以 XMLHttpRequest 傳送。
  2. 最好使用 HTTPS。如果某人中斷了你的終端,即可開始將通知傳送到自己的 App。
  3. 使用如 cookie 的機制,可比對使用者 (或 App 安裝作業) 與終端。

新增 push 訊息處理器

一旦設定終端完畢,就可讓 App 開始監聽推播訊息。此功能亦可註冊在主要的 index.html 檔案,或註冊在自己的 main.js 指令碼中;也能註冊在特殊的 push-message.html 檔案 (特殊之處在於該檔案之內僅有指令碼) 上。這功能之所以方便的原因在於:如果接收到 push 訊息且 App 處於關閉狀態時,則該 App 只會載入一小部分的 HTML/JavaScript 程式碼,而且你也可以決定是否要完全開啟 App,或在背景中執行某些作業即可。

if (window.navigator.mozSetMessageHandler) {
  window.navigator.mozSetMessageHandler('push', function(e) {
    debug('My endpoint is ' + e.pushEndpoint);
    debug('My new version is ' +  e.version);
    //Remember that you can handle here if you have more than
    //one pushEndpoint
    if (e.pushEndpoint === emailEndpoint) {
      emailHandler(e.version);
    } else if (e.pushEndpoint === imEndpoint) {
      imHandler(e.version);
    }
  });
} else {
  // No message handler
}

新增 push-register 訊息處理器

請確實添增此處理器,並檢查是否正常運作。只要在產生 push-register 訊息當下,你並未重新註冊自己的終端,則之後將無法繼續接收其他推播通知。

一旦裝置變更了自己的 UAID (可能是因為推播伺服器變更,或當機之後需恢復作業,或其他更多情形),就會將 push-register 訊息傳送至所有 App。也就是說,因為你之前的終端均已無效,所以你必須再次重新註冊所有的終端。

if (window.navigator.mozSetMessageHandler) {
  window.navigator.mozSetMessageHandler('push-register', function(e) {
    console.log('push-register received, I need to register my endpoint(s) again!');

    var req = navigator.push.register();
    req.onsuccess = function(e) {
      var endpoint = req.result;
      console.log("New endpoint: " + endpoint );
      localStorage.endpoint = endpoint;
    }

    req.onerror = function(e) {
      console.error("Error getting a new endpoint: " + JSON.stringify(e));
    }
  });
} else {
  // No message handler
}

傳送通知

一旦你的伺服器擁有 endpoint 之後,「傳送通知」就如同「將 HTTP PUT 的請求 (其內容具備 version=<version>) 傳送至終端」一樣簡單。先假想某個終端具備下列網址:

https://push.src.openwebdevice.com/v1/notify/abcdef01234567890abcdefabcdef01234567890abcdef

而且是版本 5:

version=5

搭配 curl:

curl -X PUT -d "version=5" https://push.src.openwebdevice.com/v1/notify/abcdef01234567890abcdefabcdef01234567890abcdef

如果伺服器正確運作,所取得的反應內容就會包含 200 Status (OK){} 各 1 組作為內容 (Body)。如果發生錯誤,則會送出有效的 JSON 以解釋該錯誤。

另請注意,版號應該為逐漸遞增的整數。如果新版本的版號,小於裝置/伺服器上已儲存的版本,則 App 不會獲得新的通知。

規格

Specification Status Comment
Push API Working Draft Non standard

瀏覽器相容性

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support Not supported Not supported Not supported Not supported Not supported
Feature Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support Not supported Not supported

18.0 (18) moz

(From FirefoxOS 1.1)

Not supported Not supported Not supported

Gecko implementation note

This API is currently available on Firefox OS only for any installed applications.

另可參閱

文件標籤與貢獻者

 此頁面的貢獻者: MashKao
 最近更新: MashKao,