デバイスのインストール

Kii Cloud でプッシュ通知を使用するための初期化処理では、デバイストークンをプッシュ通知ネットワークから取得し、それをユーザーと紐付けて登録する必要があります。Kii Cloud ではこの処理をデバイスのインストールと呼んでいます。

プッシュ通知設定チュートリアルでは、プログラムの実装のステップでデバイスのインストール処理を実装しています。チュートリアルの処理をモバイルアプリでそのまま利用する場合、このページで説明している処理は別途実装する必要はありません。

デバイスのインストールの位置づけ

リクエストの流れに示したとおり、以下の図のに相当する処理がデバイスのインストール処理です。

Kii Cloud では、デバイストークンとユーザーを紐付けて管理します。Kii Cloud SDK では、デバイストークンとユーザーの 1 件分の対応を KiiPushInstallation クラスで表します。

FCM や APNs では、デバイストークンはモバイルアプリが起動するたびに新しい値を取得し、デバイスのインストール処理を実行するように実装します。また、FCM/APNs サーバー側でデバイストークンの更新が必要になった場合も、同様の処理を行います。

プッシュ通知が不要になった場合は、デバイスのアンインストール処理を行い、Kii Cloud 上のデバイストークンとユーザーの対応を破棄することができます。なお、プッシュ通知ネットワークからデバイストークンが無効になったことが Kii Cloud に通知された場合も、デバイスのアンインストール処理が実行されます。

デバイスとユーザーの関係

Kii Cloud では、FCM や APNs から発行されたデバイストークンを使ってプッシュメッセージの通知先を識別します。ログイン中のユーザーと、デバイス上のモバイルアプリを紐付けることによって、Kii Cloud ではユーザーに対するプッシュ通知をデバイスに配信できます。

この仕組みにより、プッシュ通知は以下のような動きとなります。

1 人のユーザーは異なるデバイスから、複数のデバイストークンをインストールできます。これは、同じユーザーがスマートフォンとタブレットに同時にログインすると、両方でプッシュ通知を受け取れることを意味します。
1 つのデバイス上の同じモバイルアプリで、異なるユーザーを使うと、最後にデバイストークンをインストールしたユーザーだけがプッシュ通知を受け取れます。新しいユーザーでデバイストークンをインストールすると、Kii Cloud 上のデバイストークンは新しいユーザーとの組み合わせで上書きされるためです。
仮ユーザーを使った場合、デバイスごとに異なるユーザーとして識別されます。仮ユーザーを使ったモバイルアプリでは、1 人のユーザーに向けたプッシュ通知を異なるデバイスで受け取ることはできません。

デバイストークンが Kii Cloud から削除されるのは、以下のタイミングです。

モバイルアプリから明示的にプッシュ通知のアンインストール API を呼び出した場合
別のユーザーによって、デバイストークンが上書きインストールされた場合
デバイストークンが無効になったことを Kii Cloud のサーバーが検出した場合（モバイルアプリの起動ごとにデバイスのインストールを行うことが適切です）

デバイスのインストール処理

以下、デバイスのインストール処理の詳細を説明します。ここに示すサンプルコードは、プッシュ通知導入作業において、プッシュ通知設定チュートリアルによってすでに実装されています。

まず、FCM からデバイストークンを取得する処理が必要です。これは、このページの冒頭に示した図のとの結果を取得する処理です。プッシュ通知設定チュートリアルでは、それぞれ以下のように実装されています。

String fcmToken = FirebaseInstanceId.getInstance().getToken();

デバイストークンは、FCM での fcmToken として取得できます。

次に、取得したデバイストークンを Kii Cloud にインストールします。これは、このページの冒頭に示した図のに相当する処理です。

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

インストールの際はユーザーをログイン状態にしておく必要があります。Kii Cloud では、プッシュ通知の送信先は Bucket やトピックを講読しているユーザーであるため、ログイン処理は必須となります。そのため、実際のプログラムでは、デバイスのインストール処理をログイン完了時の処理として実装するのが現実的です。

Kii Cloud へのインストール処理はブロッキング API とノンブロッキング API の両方に対応しています。プッシュ通知設定チュートリアルでは、いずれも Activity から呼び出しているためノンブロッキング API を使用しています。

try {
  // Configure the push notification in production mode.
  boolean development = false;

  // Register the device token for the logged-in user to Kii Cloud.
  KiiUser.pushInstallation(PushBackend.GCM, development).install("[DEVICE_TOKEN]");
} catch (ConflictException e) {
  // Handle the error.
} catch (AppException e) {
  // Handle the error.
} catch (IOException e) {
  // Handle the error.
}

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

// Register the device token for the logged-in user to Kii Cloud.
KiiUser.pushInstallation(PushBackend.GCM, development).install("[DEVICE_TOKEN]", new KiiPushCallBack() {
  @Override
  public void onInstallCompleted(int taskId, Exception exception) {
    if (exception != null) {
      // Handle the error.
      return;
    }
  }
});

pushInstallataion() メソッドの第 1 引数は、使用するプッシュ通知ネットワークの種類を指定します。FCM は PushBackend.GCM を（シンボル上、FCM は GCM とします）を指定します。

第 2 引数は、プッシュ通知の環境を開発環境とするか、配布環境とするかの指定です。開発用の場合は true、配布用の場合は false を指定します。機能の詳細は開発環境と配布環境を参照してください。

また、install() メソッドの [DEVICE_TOKEN] には、デバイストークン（FCM の fcmToken）を指定します。

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

Kii Cloud に登録しているデバイスの登録を解除したい場合は、デバイスをアンインストールします。

try {
  // Configure the push notification in production mode.
  boolean development = false;

  // Unregister the device token for the logged-in user from Kii Cloud.
  KiiUser.pushInstallation(PushBackend.GCM, development).uninstall("[DEVICE_TOKEN]");
} catch (AppException e) {
  // Handle the error.
} catch (IOException e) {
  // Handle the error.
}

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

// Unregister the device token for the logged-in user from Kii Cloud.
KiiUser.pushInstallation(PushBackend.GCM, development).uninstall("[DEVICE_TOKEN]", new KiiPushCallBack() {
  @Override
  public void onUninstallCompleted(int taskId, Exception exception) {
    if (exception != null) {
      // Handle the error.
      return;
    }
  }
});

pushInstallataion() メソッドの指定方法はデバイスのインストールと同じです。また、"[DEVICE_TOKEN]" はデバイストークンを指定します。

実行時は install() を呼び出したときと同じユーザーでログインしている必要があります。

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