Cordova への導入

Apache Cordova で動作するモバイルアプリに Kii Cloud SDK for JavaScript を組み込むことができます。

Cordova で Kii Cloud SDK を使う方法はいくつかありますが、ここでは Cordova の構成ファイルに直接 SDK のファイルを追加する方法を示します。

準備として、Cordova のプロジェクトを作成し、"Hello World" 的なモバイルアプリが動作する状態にしておきます。

Kii Cloud SDK の導入

以下の手順で、Kii Cloud SDK をあなたのプロジェクトに追加します。

Kii Cloud SDK の ZIP ファイルをダウンロードします。

まずはライブラリーをダウンロードします。開発者ポータル（https://developer.kii.com）にログインし、"ダウンロード" ページで SDK のリンクをクリックするとライブラリーがダウンロードされます。
Kii Cloud SDK の ZIP ファイルを展開して配置します。

SDK を展開すると、KiiSDK.min.js、KiiSDK.js という 2 つのファイルがあります。どちらか一方を選択し、Cordova プロジェクトの /app/www/js ディレクトリなどにコピーします。

いずれも同じ機能を持っていますが、KiiSDK.min.js はソースから空白などの情報が取り除かれています。リリース時にはサイズの小さな KiiSDK.min.js を、開発時にはソースが参照可能な KiiSDK.js を利用できます。
HEAD タグ内で Kii Cloud SDK を読み込ませます。

SDK の JS ファイルが起動時に読み込まれるように設定します。Cordova プロジェクトでの SDK のディレクトリはコピーした位置に合わせて適宜変更してください。
```
<head>
    <script type="text/javascript" src="js/KiiSDK.min.js"></script>
  ...
</head>
```
Kii Cloud SDK の初期化メソッドを呼び出します。

モバイルアプリの起動時に初期化メソッドを呼び出します。deviceready イベントや www/js/index.js などでの実行が適切です。
```
document.addEventListener('deviceready', function () {
   // Initialize the Kii Cloud SDK. Call this method before any other Kii SDK API calls.
   Kii.initializeWithSite("___APPID___", "___APPKEY___", KiiSite.JP);

   // Initialize other components.
   ...
});
```
___APPID___ には開発者ポータルにて取得した AppID を、___APPKEY___ には任意の値を設定してください。

AppID をクライアントサイドのスクリプトに埋め込んでも、アクセス制御を正しく行えば安全性は確保できます。詳細は、セキュリティをご覧ください。

プッシュ通知の導入

Cordova では、phonegap-plugin-push を使って、FCM または APNs を使ったプッシュ通知を利用できます。

プッシュ通知の設定

phonegap-plugin-push でプッシュ通知を利用するには、以下のような設定が必要です。

Cordova への導入方法の詳細は、上記リンク先の README や、Web 上の一般的な技術情報などを参照してください。

FCM では Firebase コンソールからプッシュ通知関連の設定を行い、Server key や送信者 ID を取得します。APNs では Apple Developer Web サイトからプッシュ通知やビルドに関連した設定を行い、証明書を取得します。
Cordova プロジェクトや Xcode プロジェクトに対して、送信者 ID や証明書を設定します。
Kii Cloud の開発者ポータルに、FCM の Server key や APNs の証明書を設定します。

Kii Cloud 関連の設定は、ネイティブアプリケーション向けのプッシュ通知の解説（FCM の技術概要とチュートリアル、APNs の技術概要とチュートリアル）を参考にしてください。

デバイスのインストール

Kii Cloud でプッシュ通知を使用する際には、デバイストークンのインストール処理を Kii Cloud 向けに実装する必要があります。デバイスのインストール処理の概要については、Kii Cloud SDK for Android のプッシュ通知の仕組みを参考にしてください。

デバイストークンのインストールは、phonegap-plugin-push の registration イベントで実行します。以下のように、registration イベントの発生時に data.registrationId からデバイストークンを取得し、Kii Cloud に登録します。

登録の際に使用する KiiPushInstallation クラスのメソッドは、FCM が installGcm()、APNs が installApns() で、その他の処理は同一です。

この API を実行するには、プッシュ通知を受け取るユーザーでログインしておく必要がある点に注意してください。

FCM

push.on('registration', function(data) {
  var deviceToken = data.registrationId;

  // 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().installGcm(deviceToken, 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;
    }
  );
}

push.on('registration', function(data) {
  var deviceToken = data.registrationId;

  // 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().installGcm(deviceToken, 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;
    }
  });
}

APNs

push.on('registration', function(data) {
  var deviceToken = data.registrationId;

  // 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().installApns(deviceToken, 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;
    }
  );
}

push.on('registration', function(data) {
  var deviceToken = data.registrationId;

  // 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().installApns(deviceToken, 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 で指定してください。

デバイスのインストールが完了すると、ログイン中のユーザーは、指定されたデバイストークンと紐付けて Kii Cloud に登録されます。既存のデバイストークンはインストールによって新しいユーザーとの組み合わせで上書きされるため、以前紐付いていたユーザーへのプッシュ通知はこのデバイスに届かなくなります。

デバイスのアンインストール

Kii Cloud に登録しているデバイスの登録を解除したい場合は、デバイスをアンインストールします。この処理を実行することによってデバイスはプッシュ通知を受信できない状態になります。

// Specify the device type by "ANDROID" or "IOS".
var deviceType = "ANDROID";

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

// Specify the device type by "ANDROID" or "IOS".
var deviceType = "ANDROID";

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

アンインストール処理で呼び出すメソッドは、FCM と APNs で共通ですが、第 2 引数で指定するパラメーターが異なります。FCM の場合は文字列 "ANDROID" を、APNs の場合は "IOS" を指定します。

第 1 引数の installationRegistrationID には、インストール時に installGcm() または installApns() から response.installationID として返した値を指定します。