Installing a Device

In order to use the push notification feature on Kii Cloud, you need to initialize the feature by getting a device token from the push notification network, associate it with the user, and register it to Kii Cloud. This process is called device installation in the Kii Cloud environment.

The push notification tutorial explains how to install a device in the topic for program implementation. If you use the code in the tutorial as it is for your mobile app, you do not need to implement the process described in this topic separately.

Position of the device installation

As shown in Request flow, Process :num3: in the diagram below installs the device.

A device token and a user are managed as a pair in Kii Cloud. The Kii Cloud SDK represents a pair of a device token and a user with the KiiPushInstallation class.

For FCM and APNs, implement your mobile app to get a new device token each time the mobile app starts and install the device. Execute the same process when the FCM or APNs server updates the device token.

When the user does not need to receive push notifications anymore, uninstall the device so that Kii Cloud discards the association of the device token and the user. Execute this process also when the push notification network informs Kii Cloud that the device token is not valid any longer.

Relation between a device and a user

Kii Cloud uses device tokens issued by the push notification network for identifying the destination of push messages. Kii Cloud associates a currently logged-in user with the mobile app on the device and then delivers a push notification addressed to the user to a device.

On the basis of this mechanism, the push notification feature works as below:

  • A user can install multiple devices and gets multiple device tokens. If the user concurrently logs in to a smartphone and a tablet, both devices receive push notifications.

  • If multiple users log in to the same mobile app on the installed device, only the last user who installs the device receives push notifications. When a new user installs a device, the pair of the old user and the device token is overwritten with the pair of the new user and the device token on Kii Cloud.

  • If the pseudo user feature is used, a different pseudo user is assigned to each device. A mobile app that implements the pseudo user feature does not allow a single user to receive push notifications on multiple devices.

A device token is deleted from Kii Cloud when any of the following actions are taken:

  • The mobile app calls the API to uninstall the device from Kii Cloud.

  • A different user installs the device and the previous user paired with the device token is overwritten on Kii Cloud.

  • Kii Cloud detects that the device token is not valid any longer (Therefore, it is appropriate to install the device each time the mobile app starts).

Installing a device

You need to send the device token that the APNs server assigns to the device to Kii Cloud. This process is called installation. Installation associates the Kii Cloud user with the device token on Kii Cloud.

The code below initializes push notification in the development network environment. Set developmentMode to NO if you use the production network environment.

See the code below that sends the device token from the APNs server to 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;
    }
  }];
}

For a real program, you need to call this API after the user has logged in to Kii Cloud. If you have a separate login screen, save deviceToken somewhere, get it after login, and then call the API.

Note that the device installation will update the user who is bound to the device token to the current user. If the device token was bound to another user, the binding is canceled by the installation; push notifications sent to the old user will no longer be delivered to the device.

You will get no error if the device fails to get the device token from the APNs server. You might want to implement a logic to recognize an error as shown in the following sample code.

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);
}

Uninstalling a device

You can unbind the device registered on Kii Cloud with the device uninstallation procedure.

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;
  }
}];

You need to specify the device token when uninstalling the device. The device will no longer receive the push notification once its uninstallation is completed.