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

This section explains the detail of the device installation process. The sample code below is the one implemented in [the push notification tutorial ](/en/samples/push-notifications/push-notifications-android-fcm/.

First, get a device token from the push notification network. This is a process represented as :num1: and :num2: in the first diagram in this topic. This process is implemented as below in the push notification tutorial.

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

A device token is obtained as fcmToken for FCM.

Next, register the obtained device token to Kii Cloud. This is a process represented as :num3: in the first diagram in this topic.

When a device is installed, the currently logged-in user gets associated with the device token and registered to Kii Cloud. A previous user associated with the existing device token, if any, is overwritten by the new user. Therefore, push notifications addressed to the previous user will not be sent to the device anymore.

When a device is installed, the user must be logged in. This is required because Kii Cloud sends push notifications to users who have subscribed to buckets and topics. It is practical to implement the device installation process after the login process.

You can use the blocking or non-blocking API to install a device to Kii Cloud. The push notification tutorial uses the non-blocking API because it is called within an activity.

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

Set the push notification network to use with the mobile app as the first argument of the pushInstallation() method. Set PushBackend.GCM for FCM (The GCM symbol is used for FCM).

Set the push notification environment as the second argument. Set true for the development environment and false for the production environment. For more information, see Development and production environments.

Replace "[DEVICE_TOKEN]" of the install() method with the device token that is fcmToken for FCM.

Uninstalling a device

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

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

Use the pushInstallation() method as with for device installation. Replace "[DEVICE_TOKEN]" with the device token.

Like the install() method, you need to execute the uninstall() method with the user being logged in,

The device will no longer receive the push notification once its uninstallation is completed.