Using APNs

In order to use the APNs push notification feature in Kii Cloud, you should get familiar with the following concepts:

• APNs structure
• Building an iOS app
• Difference between a code signing certificate and a push notification certificate

For more information, see the Apple documentation.

APNs structure

Push notification by APNs is provided by coordinating communications among devices, the APNs server, and the application server (Kii Cloud).

APNs requires secure SSL connections between Kii Cloud and the APNs server. Get a certificate for SSL connections from the Apple Developer website and register it to Kii Cloud with the developer portal in advance. Kii Cloud uses this certificate to establish SSL connections when it requests the APNs server to send push messages.

Note that you need to be a member of the Apple Developer Program to get a certificate from the Apple Developer website.

APNs accepts two types of certificates for push notification: development certificates and production certificates. Each type is used for the corresponding push notification network. You can get both types of certificates from the Apple Developer website and register them to Kii Cloud. Kii Cloud uses the right certificate for the target push notification network when it requests APNs to send messages.

You specify the development network or production network with the user interface and/or as an API parameter of Kii Cloud for sending messages.

Setting up the certificate

The diagram below illustrates the process flow of getting a certificate for push notification and registering it to Kii Cloud.

You can perform the steps with background colors by following the instruction for setting up a development certificate as described in iOS Push Notification Tutorial. Take the remaining steps to register a production certificate before you release your mobile app.

The tutorial guides you through the following steps:

• Registering the App ID (automatically in Xcode)

  Register the bundle identifier of your mobile app under development to the Apple Developer website. The bundle identifier is treated as an Apple App ID.

  Enable the automatic code signing feature of Xcode, and then build and run your mobile app. Xcode and Apple's server work together to register the build identifier automatically as the App ID. Therefore, you need to build your mobile app in Xcode before setting up push notification.

  You can also set up the App ID manually in the Apple Developer website.

• Getting a Certificate

  Create a certificate signing request (CSR file) in Keychain Access of your local machine. Then upload it to the Apple Developer website to get a certificate (CER file). Store the obtained certificate with the private key in Keychain Access.

• Uploading the Certificate

  Convert the certificate in Keychain Access to a personal information exchange file (P12 file) to register it in the Kii Cloud developer portal.

The process of creating a certificate for push notification is linked to that of building an iOS app.

Building an iOS app

Xcode 8 introduced the "Automatically manage signing" option as a build setting. You can automate the necessary steps for code signing by enabling this option.

This topic supplements necessary information for setting up push notification by explaining the basic flow of the automatic setting.

Flow of building an app for a real device

In order to build an execution module in Xcode, you need a proper digital signature on the module. A provisioning profile is referenced to identify the device that has a certificate and execution permission for code signing.

You need to use a real device to test push notification on iOS. You cannot test it with an iPhone simulator.

A provisioning profile is a configuration file that you create on the Apple Developer website. Download it to your machine that has the build environment. This file includes the following information:

• A list of certificates available for signing the executable.
• The App ID of your mobile app (It is the same as the bundle identifier).
• The UDID for identifying the target device.

There are four types of provisioning profiles (Development, In-house, Ad hoc, and App Store) and two types of application certificates (development and production). The following chart summarizes them.

The diagram below illustrates the steps that are automatically processed by Xcode when building a mobile app. Especially, the steps with the background color are automatically processed when you debug your mobile app by following the instruction described in iOS Push Notification Tutorial. The remaining steps are to be processed when you release your mobile app.

If you do not use the automatic code signing feature of Xcode, you need to take corresponding steps manually on the Apple Developer website. See web resources for more information as those steps are not part of the Kii Cloud technology.

Difference between a code signing certificate and a push notification certificate

Development and production certificates for code signing are different from those for push notification.

• Code signing certificate

  Development and production certificates for code signing are selectively used according to the build mode of Xcode: Debug and Release. The build mode determines the certificate to use for signing the execution module.

  Normally, a development certificate is referenced when you debug your mobile app in Debug mode. Similarly, a production certificate is referenced when you build your mobile app in Release mode to release it to App Store.

• Push notification certificate

  Development and production certificates for push notification are selectively used according to the push notification network.

  With APNs, you can use two types of network environments: development and production. Therefore, you can separately handle push notifications sent to development and production environments. When initializing devices to receive push notifications, you specify which network environment to use as a parameter of the initialization API of Kii Cloud. When you send a push notification, you specify the network environment to use with the user interface and/or as an API parameter of Kii Cloud.

  When Kii Cloud sends a push message, it establishes an SSL connection with the APNs server. A development certificate is used to send a message to the development network while a production certificate is used to send a message to the production network.

Usually, you use the same type of certificates for code signing and push notification. However, it is possible to use different types of certificates. For example, you can send a message to the production network from an execution module build in Debug mode. To achieve this, you build your mobile app with a development certificate for code signing and send a push message with a production certificate for push notification.