プッシュ通知（MQTT）の導入

ここでは、Web アプリに MQTT によるプッシュ通知の機能を組み込む場合の導入手順について説明します。Cordova アプリでプッシュ通知を利用する場合は、Cordova への導入をご覧ください。

MQTT の技術的な概要については、MQTT プロトコルをご覧ください。

導入手順

MQTT によるプッシュ通知を利用するために必要な準備は以下の 4 つです。

ライブラリーの選択
ユーザー/Thing のインストール
MQTT エンドポイントの取得
MQTT コネクションの確立
ユーザー/Thing のアンインストール

ライブラリーの選択

JavaScript 上で MQTT を使用するには、MQTT に対応した外部ライブラリーを用意する必要があります。利用可能なライブラリーの例は、たとえば MQTT.org が公開しているこちらのリストを参照してください。

Kii Cloud では、MQTT.js によるテストを行っています。また、Paho での動作実績があります。

ユーザー/Thing のインストール

Web アプリにプッシュ通知を送る準備として、プッシュ通知の送信先のユーザーや Thing をインストールします。この処理によって、Kii Cloud のユーザーまたは Thing と MQTT のコネクションが Kii Cloud 上で紐付けられます。

プッシュ通知用にユーザーをインストールする例を以下に挙げます。

// Configure the push notification in production mode.
var development = false;

// Set up an MQTT endpoint for the logged-in user to Kii Cloud.
KiiUser.getCurrentUser().pushInstallation().installMqtt(development).then(
  function(response) {
    var installationID = response.installationID;
    var installationRegistrationID = response.installationRegistrationID;
    // Do something.
  }
).catch(
  function(error) {
    // Handle the error.
    var thePushInstallation = error.target;
    var errorString = error.message;
  }
);

// Configure the push notification in production mode.
var development = false;

// Set up an MQTT endpoint for the logged-in user to Kii Cloud.
KiiUser.getCurrentUser().pushInstallation().installMqtt(development, {
  success: function(response) {
    var installationID = response.installationID;
    var installationRegistrationID = response.installationRegistrationID;
    // Do something.
  },
  failure: function(error) {
    // Handle the error.
    var thePushInstallation = error.target;
    var errorString = error.message;
  }
});

引数の development で開発環境か、配布環境かを指定します。上記の例では development に false を設定しているため配布環境向けの設定になります。

なお、installMqtt() メソッドを実行するには KiiUser をログイン状態にしておく必要があります。Kii Cloud では、プッシュ通知の送信先は Bucket やトピックを購読しているユーザーであるため、ログイン処理は必須となります。

Thing をインストールする場合は、JavaScript SDK で Thing を実装に示す pushInstallation() メソッドを使ってインストール処理を実行します。

MQTT エンドポイントの取得

次に、MQTT エンドポイントを Kii Cloud より取得します。この処理により、MQTT ブローカーへの接続や MQTT トピックの購読に必要な情報が取得できます。

MQTT エンドポイントを取得する例を以下に挙げます。

var installationID = "[INSTALLATION_ID]";

// Get the MQTT endpoint for the logged-in user to Kii Cloud.
KiiUser.getCurrentUser().pushInstallation().getMqttEndpoint(installationID).then(
  function(response) {
    var username = response.username;
    var password = response.password;
    var mqttTopic = response.mqttTopic;
    var xMqttTtl = response["X-MQTT-TTL"];
    var portTCP = response.portTCP;
    var portSSL = response.portSSL;
    var portWS = response.portWS;
    var portWSS = response.portWSS;
    // Do something.
  }
).catch(
  function(error){
    // Handle the error.
  }
);

var installationID = "[INSTALLATION_ID]";

// Get the MQTT endpoint for the logged-in user to Kii Cloud.
KiiUser.getCurrentUser().pushInstallation().getMqttEndpoint(installationID, {
  success: function(response) {
    var host = response.host;
    var username = response.username;
    var password = response.password;
    var mqttTopic = response.mqttTopic;
    var xMqttTtl = response["X-MQTT-TTL"];
    var portTCP = response.portTCP;
    var portSSL = response.portSSL;
    var portWS = response.portWS;
    var portWSS = response.portWSS;
    // Do something.
  },
  failure: function(error) {
    // Handle the error.
  }
});

installationID には installMqtt() メソッドでユーザーまたは Thing をインストールした際に入手した Installation ID を指定します。

MQTT エンドポイントの準備はユーザーまたは Thing のインストールを契機に開始されます。もし MQTT エンドポイントの取得を要求した時点でエンドポイントの準備ができていない場合、getMqttEndpoint() メソッドは 1 秒間のインターバルをおいて最大 3 回まで取得を試みます。

MQTT コネクションの確立

MQTT エンドポイントの取得が完了すると、MQTT コネクションを確立する（i.e. MQTT ブローカーに接続し MQTT トピックを購読する）ために必要な情報がすべて揃います。

MQTT トピック講読の際には以下の情報を利用します。

接続に必要な情報	設定する値
接続先ホスト名	取得した MQTT エンドポイントの `host` プロパティの値
接続先ポート番号	取得した MQTT エンドポイントの `portTCP` プロパティの値（TCP 接続）または `portSSL` プロパティの値（SSL/TLS 接続）
WebSocket 接続用ポート番号	取得した MQTT エンドポイントの `portWS` プロパティの値（TCP 接続）または `portWSS` プロパティの値（SSL/TLS 接続）
CONNECT 要求の Keep alive timer	アプリの実装に合わせて送信（キープアライブタイマー参照）
CONNECT 要求の Client identifier	取得した MQTT エンドポイントの `mqttTopic` プロパティの値
CONNECT 要求の Username	取得した MQTT エンドポイントの `username` プロパティの値
CONNECT 要求の Password	取得した MQTT エンドポイントの `password` プロパティの値
SUBSCRIBE 要求の Topic name	取得した MQTT エンドポイントの `mqttTopic` プロパティの値

これらの情報を元に MQTT ライブラリーの API を呼び出して、MQTT のコネクションを確立します。MQTT.js と Paho による実装例は、JavaScript（Web）プッシュ通知設定チュートリアルをご覧ください。

通常、Web アプリなど、ブラウザー上で使用する場合は portWSS によって WebSocket 上のコネクションを利用します。Thing から使用する場合は、portTCP によって TCP ソケット上のコネクションを利用します。

なお、Kii Cloud の MQTT では、仕様上 1 人のユーザーからは 1 つの MQTT コネクションしか生成できません。複数の Web アプリを同時に起動しても、接続できるコネクションは 1 つだけであることにご注意ください。

Web アプリを同時に起動すると、使用する MQTT ライブラリーによっては、コネクションの切断と再接続を繰り返す動きになるものがあります。必要に応じて、再接続の頻度をチェックし、接続エラーにするような処理を Web アプリ側のロジックとして作り込んでください。

キープアライブタイマー

MQTT では、コネクションが切れていないことを確認するために死活監視のプロトコルが定められています。

プロトコル上は、CONNECT 要求で送信した Keep alive timer 値の 1.5 倍の時間以内に、クライアントから何らかのメッセージを送信しないと、コネクションは自動的に切断されます。この時間内にクライアントからのメッセージ送信がない場合、PINGREQ リクエストを送信する必要があります。

PINGREQ リクエストの送信処理の実装方法はライブラリーによって異なります。ライブラリー内部で自動的に送信されるものや、プログラム側で送信処理を書く必要があるものがあります。実装方法は使用する MQTT ライブラリーのドキュメントを参照してください。

ユーザー/Thing のアンインストール

ユーザーまたは Thing のプッシュ通知を解除するには、アンインストール処理を実装します。このとき、Installation ID または Installation Registration ID を使ってアンインストール処理の対象を指定します。

まず、Installation ID を使ってユーザーのプッシュ通知を解除する例を挙げます。

var installationID = "[INSTALLATION_ID]";

// Delete the MQTT endpoint for the logged-in user from Kii Cloud.
KiiUser.getCurrentUser().pushInstallation().uninstallByInstallationID(installationID).then(
  function(response) {
    // Do something.
  }
).catch(
  function(error) {
    // Handle the error.
    var errorString = error.message;
  }
);

var installationID = "[INSTALLATION_ID]";

// Delete the MQTT endpoint for the logged-in user from Kii Cloud.
KiiUser.getCurrentUser().pushInstallation().uninstallByInstallationID(installationID, {
  success: function(response) {
    // Do something.
  },
  failure: function(error) {
    // Handle the error.
    var errorString = error.message;
  }
});

installationID には installMqtt() メソッドの実行時に返された Intallation ID を指定します。

次に、Installation Registration ID を使ってユーザーのプッシュ通知を解除する例を挙げます。

var installationRegistrationID = "[INSTALLATION_REGISTRATION_ID]";
var deviceType = "MQTT";

// Delete the MQTT endpoint for the logged-in user from Kii Cloud.
KiiUser.getCurrentUser().pushInstallation().uninstall(installationRegistrationID, deviceType).then(
  function(response) {
    // Do something.
  }
).catch(
  function(error) {
    // Handle the error.
    var errorString = error.message;
  }
);

var installationRegistrationID = "[INSTALLATION_REGISTRATION_ID]";
var deviceType = "MQTT";

// Delete the MQTT endpoint for the logged-in user from Kii Cloud.
KiiUser.getCurrentUser().pushInstallation().uninstall(installationRegistrationID, deviceType, {
  success: function(response) {
    // Do something.
  },
  failure: function(error) {
    // Handle the error.
    var errorString = error.message;
  }
});

installationRegistrationID には installMqtt() メソッドの実行時に返された Intallation Registration ID を指定します。また、deviceType にアンインストールするプッシュ通知の種類として MQTT を指定します。

アンインストールが成功すると、プッシュ通知が届かなくなります。

Thing のプッシュ通知を解除する場合は、JavaScript SDK で Thing を実装に示す pushInstallation() メソッドを使ってアンインストール処理を実行します。