Simple Push

Simple Push API、別名プッシュ通知 API はウェイクアップして通知を受け取る能力をアプリにもたらします。Simple Push は同期メカニズムとしても、あるいはサードパーティのサーバーから最新データを取得する方法としても利用できます。

「プッシュ」とはリモートサーバーから送られてくるイベントに過ぎません。これは以下のようにして動作します。アプリは Simple Push API を使ってエンドポイントと呼ばれる特殊なユニーク URL をリクエストします。このリクエストは、Mozilla がこの目的のために管理する既存のサーバー（これは「プッシュサーバー」と呼ばれます）へ送られます。プッシュサーバーから返されるエンドポイントをアプリが受け取ると、アプリは自身のサーバー（あなたのアプリサーバーです）へエンドポイントを送信します。アプリサーバーはこのエンドポイントを保存します。その後、アプリをウェイクアップしたいと思った時にバージョン番号付きでエンドポイントを呼び出し、プッシュサーバーはアプリにそのバージョン番号通知を連絡します。アプリは通知を受け取った時に、それを無視することも含め何らかのこと行うことができます。

Simple Push APIは window.navigator を拡張して PushManager オブジェクトを保持する push プロパティを持たせ、またプッシュの状態を監視するために受け取れる新しいイベントをいくつか追加します。

基本を説明する例

Simple Push の使い方はいくつかあります。この例では基本的な使い方を取り上げます。例は以下の一般的な手順からなります。各手順の完全な情報についてはその後のセクションをご覧ください。

1. アプリのマニフェストファイルに push の設定を追加する
2. PushManager.register を呼んでエンドポイントをリクエストする
3. エンドポイントをサーバーに送信する
4. アプリにプッシュ通知用のメッセージハンドラーを追加する
5. エンドポイントを使ってサーバーから通知を送信する

1. アプリのマニフェストファイルに push の設定を追加する

Sinple Push を使えるようにするため、マニフェストファイルで二か所変更が必要です。

1. messages フィールド - push と push-register メッセージを追加。
   これはアプリの（push と push-register の）各イベントを受け取るページを示します。この例ではどちらも同じ「/index.html」ページへ進みますが、異なるページを使っても構いません。より詳細な各イベントの情報は後述します。
2. permissions フィールド - アプリがプッシュ通知受け取りを要求することを追加。
   なぜ push 権限が必要なのか、エンドユーザーが理解できるように明確な説明を提供するのはいい考えです。

"messages": [
   { "push": "/index.html"},
   { "push-register": "/index.html"}
],
"permissions": {
  "push": {
    "description": "サッカーの試合中にゴールが決まるたび更新を受け取るのに必須",  
  }
}

2. PushManager.register() を呼んでエンドポイントをリクエストする

アプリは PushManager.register を呼び出してエンドポイントをリクエストする必要があります。いつ呼び出すかはあなたが決めなければなりません。ユーザーがログインした時やサッカーの試合を観戦することに決めた時など何らかの時点でエンドポイントを呼び出せます。以下のコードがそのための一例です。

if (navigator.push) {
  // エンドポイントをリクエストします。PushManager.register() を使います。
  var req = navigator.push.register();
  
  req.onsuccess = function(e) {
    var endpoint = req.result;
      console.log("新しいエンドポイント：" + endpoint );
      // ここであなたのサーバーにエンドポイントを送信するため、何らかの呼び出しを使用します。
      // 例えばこうです。
      /* 
      var post = XMLHTTPRequest();
      post.open("POST", "https://your.server.here/registerEndpoint");
      post.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
      post.send("endpoint=" + encodeURIComponents( endpoint ) );
      */
      // 明らかに .onload と .onerror ハンドラー、及びユーザー ID の情報や
      // その他エンドポイントとユーザーを関連付ける必要のある何らかの情報を追加したくなるでしょう。
    }

   req.onerror = function(e) {
     console.error("新しいエンドポイント取得に関するエラー：" + JSON.stringify(e));
   }
} else {
  // DOM 上で push が使用できないためそれ以外のことをします。
}

3. エンドポイントをサーバーに送信する

エンドポイントを取得したらそれをアプリケーションのサーバーに送る必要があります。方法は一つではありません。例えばメール送信や POST、PUT、果ては GET を使った送信など好きな方法で送ることができます。エンドポイントは、アプリケーションから送られるクッキーやユーザー名、その他エンドポイントとユーザーの組を特定する時に使う何らかのユーザーデータとともに保存することを推奨します。

とは言え、サーバーに送信するのであれば以下の優れたプラクティスに従うことを推奨します。

1. XMLHttpRequest で送信する。
2. 常に HTTPS を使う。さもなくば何者かがエンドポイントを傍受してアプリに通知を送り始めるかも知れない。
3. クッキーなど、ユーザー（やインストールしたアプリケーション）をもとにエンドポイントを照合できる物を使用する。
4. エンドポイントを安全に保つこと！　エンドポイントがあれば、顧客のバッテリーの浪費やサーバーとの不要な接続など迷惑なことを引き起こせます。いつでもクライアントに新しいエンドポイントを取得して古い物を捨てさせることができますが、あなたのサーバーがその変更を検知できるようにしなければならないことを覚えておいてください。

4. アプリに push 通知用のメッセージハンドラーを追加する

これまでの手順でエンドポイントを設定したらようやく、アプリがメッセージハンドラーを使って push と push-register のメッセージの待ち受けを開始できます。

push メッセージハンドラーを追加する

push メッセージハンドラーは index.html ファイル内や main.js のスクリプト内で登録することもできますが、そのスクリプトだけを持った特別な push-message.html ファイル内で登録することもできます。これは push メッセージを受け取った時にアプリが閉じている場合に便利でしょう。サイズの小さい部分的な HTML/JavaScript コードだけををロードして、アプリ全体を開く必要があるのかバックグラウンドで何かを行う必要があるのか決められるからです。push メッセージハンドラーをどこに置くことに決めたにせよ、マニフェストファイルが正しい場所を示すようにしてください（前述の最初の手順参照）。そうしないとアプリが更新を受け取れません。push メッセージハンドラーの例は以下の通りです。

if (window.navigator.mozSetMessageHandler) {
  window.navigator.mozSetMessageHandler('push', function(e) {
    console.log('エンドポイントは ' + e.pushEndpoint);
    console.log('新しいバージョンは ' +  e.version);
    //複数の pushEndpoint がある場合、ここで処理できることを
    //憶えておいてください
    if (e.pushEndpoint === emailEndpoint) {
      emailHandler(e.version);
    } else if (e.pushEndpoint === imEndpoint) {
      imHandler(e.version);
    }
  });
} else {
  // メッセージハンドラーなし
}

push-register メッセージハンドラーを追加する

デバイスの （UAID または User Agent Identifierと呼ばれる）内部的な iDが変わった時は、全アプリに push-register メッセージが送信されます。これは、プッシュサーバーが変わった、サーバーがダウンして復旧が必要、その他の事情が原因となり得ます。こうしたうちの一つが発生すると、過去のエンドポイントは不適合となるため、全エンドポイントを再登録しなければならないことを意味します。そのため、アプリは push-register メッセージハンドラーを実装する必要があります。以下のサンプルコードを参照してください。

if (window.navigator.mozSetMessageHandler) {
  window.navigator.mozSetMessageHandler('push-register', function(e) {
    console.log('push-register を受信、再度エンドポイントを登録する必要あり！');

    var req = navigator.push.register();
    req.onsuccess = function(e) {
      var endpoint = req.result;
      console.log("新しいエンドポイント：" + endpoint );
      localStorage.endpoint = endpoint;
    }

    req.onerror = function(e) {
      console.error("新しいエンドポイント取得に関するエラー：" + JSON.stringify(e));
    }
  });
} else {
  // メッセージハンドラーなし
}

5. エンドポイントを使ってサーバーから通知を送信する

一旦あなたのサーバーにエンドポイントを保持すれば、ボディを version=<version> にした HTTP PUT リクエストをエンドポイントに送るだけで通知を送れます。例えばエンドポイントが

https://updates.push.services.mozilla.com/update/abcdef01234567890abcdefabcdef01234567890abcdef

という URL で、バージョンが 5

version=5

だとしましょう。curl を使う場合、通知はこのようにして確認します。

curl -X PUT -d "version=5" https://updates.push.services.mozilla.com/update/abcdef01234567890abcdefabcdef01234567890abcdef

プッシュサーバーが正しく動いていれば、ステータスが 200（OK）でボディが {} となっているレスポンスを受け取ります。また、メッセージは受け入れられたけれど代わりのシステムを使って処理できるということを示すステータス 202 を受け取るかも知れません。そうでなければエラーを説明する JSON つきの妥当な HTTP エラーレスポンスが返ります。

version の値は増加する整数になるはずだということを覚えておいてください。もし新しいバージョンがサーバーやデバイスに保存しているものよりも低い場合は、アプリケーションは新しい通知を受け取りません。バージョンは、アプリが本当に確認しておくべきなのに「見逃された」イベントがないかを表すのに便利かも知れません。また、実際のバージョンの値がそれほど重要でない場合には現在の UTC（1970 年 １ 月 1 日の真夜中からの経過秒数。GMT）を使うだけでもいいでしょう。

エンドポイントを登録解除する

エンドポイントを使い終えてこれ以上通知を受けとりたくなくなった場合は、PushManager.unregister を使って古いエンドポイントを登録解除するようお願いします。これによりデバイスがプッシュサーバーに送信する多量のデータを一掃でき、また使用しない通知をアプリに送信しないことでバッテリー使用量を抑えることにもなります。

仕様

ブラウザー互換性

関連項目

• PushManager
• Window.navigator.push
• pushJSLibrary。この API を実装していないブラウザー向けのプッシュ shim
• SimplePush の元々の設計と議論のページ。