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 欄位：新增 push 與 push-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 訊息處理器

一旦裝置變更了自己的 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 不會獲得新的通知。

規格

瀏覽器相容性

Gecko implementation note

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

另可參閱

• PushManager
• navigator.push
• pushJSLibrary, a push shim for browsers that do not implement the API