デバイスのインストール

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 のサーバーが検出した場合（モバイルアプリの起動ごとにデバイスのインストールを行うことが適切です）

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

デバイスにプッシュ通知を送る準備として、APNs サーバーがデバイスに割り当てたデバイストークンを Kii Cloud に送信する必要があります。これをインストール処理と呼んでいます。インストール処理によって、Kii Cloud のユーザーとデバイストークンが Kii Cloud 上で紐付けられます。

下記は開発用のネットワーク環境を指定してプッシュ通知を初期化しています。配布用のネットワーク環境を使用する場合は、developmentMode を NO にして実行します。

APNs サーバーより受け取ったデバイストークンを Kii Cloud に送信する例を以下に示します。

Swift:

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
  do{
    // Register the device token for the logged-in user to Kii Cloud
    // to configure the push notification in development mode.
    try KiiPushInstallation.installSynchronous(withDeviceToken: deviceToken, andDevelopmentMode: true)
  }catch let error as NSError {
    // Handle the error.
    return
  }
}

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
  // Register the device token for the logged-in user to Kii Cloud
  // to configure the push notification in development mode.
  KiiPushInstallation.install(withDeviceToken: deviceToken, andDevelopmentMode: true) { (installation : KiiPushInstallation?, error : Error?) -> Void in

    // Handle the error.
    return
  }
}

Objective-C:

- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken
{
  NSError *error;

  // Register the device token for the logged-in user to Kii Cloud
  // to configure the push notification in development mode.
  [KiiPushInstallation installSynchronousWithDeviceToken:deviceToken
                                      andDevelopmentMode:YES
                                                andError:&error];
  if (error != nil) {
    // Handle the error.
    return;
  }
}

- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken
{
  // Register the device token for the logged-in user to Kii Cloud
  // to configure the push notification in development mode.
  [KiiPushInstallation installWithDeviceToken:deviceToken
                           andDevelopmentMode:YES
                                andCompletion:^(KiiPushInstallation *installation, NSError *error) {
    if (error != nil) {
      // Handle the error.
      return;
    }
  }];
}

実際のプログラムでは、Kii Cloud へのログインが完了した状態でこの API を呼び出す必要があります。ログイン画面が別にある場合は、deviceToken をどこかに保存しておき、ログイン完了後に取得して API を呼び出すなどの工夫が必要です。

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

なお、そのままでは APNs からのデバイストークンの取得に失敗しても何も起こりません。エラーの発生を知るには次のメソッドも実装しておきます。

Swift:

func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
  print(@"Failed to register to APNs: \(error)")
}

Objective-C:

- (void)application:(UIApplication*)application didFailToRegisterForRemoteNotificationsWithError:(NSError*)error{
  NSLog(@"Failed to register to APNs: (%@)", error);
}

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

必要に応じて、アンインストール処理を実装します。Kii Cloud に登録しているデバイスの登録を解除したい場合は、以下の処理を実装します。

Swift:

do{
  // Unregister the device token for the logged-in user from Kii Cloud.
  try KiiPushInstallation.uninstallSynchronous(withDeviceToken: deviceToken)
}catch let error as NSError {
  // Handle the error.
  return
}

// Unregister the device token for the logged-in user from Kii Cloud.
KiiPushInstallation.uninstall(withDeviceToken: deviceToken) { (installation : KiiPushInstallation?, error : Error?) -> Void in
  // Handle the error.
  return
}

Objective-C:

NSError *error = nil;

// Unregister the device token for the logged-in user from Kii Cloud.
[KiiPushInstallation uninstallSynchronousWithDeviceToken:deviceToken
                                                andError:&error];
if (error != nil) {
  // Handle the error.
  return;
}

// Unregister the device token for the logged-in user from Kii Cloud.
[KiiPushInstallation uninstallWithDeviceToken:deviceToken
                                andCompletion:^(KiiPushInstallation *installation, NSError *error) {
  if (error != nil) {
    // Handle the error.
    return;
  }
}];

アンインストール処理では、インストール時に指定したデバイストークンが必要です。アンインストールが成功すると、プッシュ通知が届かなくなります。