Mobile Push Notifications for iOS using APNS

  • Updated: Nov 30, 2016
  • Starting Guide

To be able to receive push notifications in your application, you need to sign it with a provisioning profile that is configured for push. Your server needs to sign its communications to APNS with an SSL certificate. Relax, we do that for you.

There are two kinds of provisioning profile, for development and for distribution. In this guide we will cover development profiles. We presume that you have a Development Certificate for iOS Developer Program. If so, the next steps should be familiar.

Generating the Certificate Signing Request (CSR)

Digital certificates are based on public-private key cryptography. The certificate is the public part of this key pair. It is safe to give it to others, which is exactly what happens when you communicate over SSL. The private key, however, should be kept private. It’s important to know that you can’t use the certificate if you don’t have the private key. When you create the CSR, a new private key is generated and is put into your keychain.

The first step requires that you launch the Keychain Access application (in Applications/Utilities) and choose the menu option "Request a Certificate from a Certificate Authority. You must generate a certificate request file so that you can use it to request for a development SSL certificate later on.

You should now see the following window:

Enter your email address. It's recommended that you use the same email address that you used to sign up for the iOS Developer Program, but it seems that any email will just do the job. In Common Name you can type anything you want here, but you should choose something that identifies your app or something that you recognise, allowing to easily find the private key later. Check "Saved to disk". Name the file wisely, for example, “MyMagnificientPushApp.certSigningRequest”. and save it to a location where you can find it later.

Creating an APP ID

In the provisioning portal of the iOS Dev Center, select "Certificates, Identifiers & Profiles". Now in the iOS panel choose Identifiers. On the left panel of portal, select App IDs, pressing the "plus" button in the top of the right side, you will be able to create a new App ID. If everything goes well, you will see the "Register an App ID" form, like the one in the next image

App ID is a two-part string used to identify one or more apps from a single development team. As push applications need its own unique ID (because push notifications are sent to a specific application) you cannot use a wildcard ID.

- First enter a valid App ID Description.
- Check Explicit App ID, enter your own Bundle Identifier. You will need it to set this same bundle ID in your Xcode project (will see it later).
- Don't forget to check Push Notification Services.
- After you’re done filling all the details press the Continue button. You will be asked to verify the details of the app id, if everything seems okay click Submit.
Now you have your app ID.

Choose your newly-created App ID. If in the “Push Notification” row, there are two orange lights that say “Configurable” in the Development and Distribution column, like in the following image, this means that your App ID can be used with push notifications, but you still need to configure this up. Click on the "Edit" button to configure this settings and create a SSL certificate.

The next menu will show you App ID configurable services. Scroll down to the Push Notifications section and select the Create Certificate button in the Development SSL Certificate section. Doing so will jump up the “Add iOS Certificate” wizard. It will ask you to generate a Certificate Signing Request. You already did that, so click Continue. In the next step upload the CSR generated earlier. Choose the CSR file and click Generate.

Wait for a few seconds to generate the SSL certificate. Click Continue when it’s done. Download it and follow the instructions, double click the certificate to add it to your Keychain. You’ll see that it is now associated with the private key.

Hurray! You have successfully create a SSL certificate associated with your APP ID.

Making Provisioning Profile

You´re not yet finished with certificates. For testing your application with push, you will need to deploy it in a device, so you will need a provisioning profile. it's your next task.

In the provisioning portal of the iOS Dev Center, select on the left side "Provisioning Profiles" (All), like the image. You now should see a "+" button on top right side, click on it for create a new provisioning profile.

Choose your desired provisioning profile type and click "Continue". In this case "iOS App Development".

Now is time to choose the app Id. Choose the one that you created in the previous section. This will ensure that this provisioning profile is explicitly tied to your application.

In the next step you select the certificates you want to include in this provisioning profile.

Select the devices you want to include in this provisioning profile. Since you’re creating the development profile you would typically select the devices you use for development here. If you don't have any device, you can do this later.

Name the profile. It's important to set the provisioning profile name as something that you easily recognise later. And thats it, your are done with the Dev Center.

Export your Private Key

Now its time to register your application into the Realtime Framework website. We need the information that you just generated about your application, for us to be able to send push notifications to your app. You just need to export your private key and SSL certificate and enter them in your Realtime Cloud Messaging subscription details. We will do the magic.

To export your private key open Keychain Access (Applications/Utilities), go to Keys section. You will see that your private key has appeared in your keychain. If you expand this option, you will see that the key is associated with the SSL certificate, wich is called “Apple Development iOS Push Services” followed by app bundle id. Right click on the private key and choose Export. Check the example image.

Save the private key as Personal Information Exchange (.p12) format and enter a passphrase. Remember save the file somewhere you can access it and choose a passphrase that you can recall, or you won’t be able to use the private key later.

Our servers are better dealing with certificates in the Personal Information Exchange (PEM) format. To convert the certificate to this format, complete the following steps: Launch the Terminal application and enter the following command after the prompt:

openssl pkcs12 -in CertificateName.p12 -out CertificateName.pem -nodes -clcerts

You can verify the .pem certificate and private key files by using them to connect to APNS Sandbox.

Using a text editor open the CertificateName.pem file and copy the text from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE----- (including these marks) and save it into a new file named myapnsappcert.pem.

Repeat the copy process now from -----BEGIN RSA PRIVATE KEY----- to -----END RSA PRIVATE KEY----- to a new file named myapnsappprivatekey.pem

At a command prompt, type the following command in the same folder where you have saved the previous files:

openssl s_client -connect gateway.sandbox.push.apple.com:2195 -cert myapnsappcert.pem -key myapnsappprivatekey.pem

Obtaining an error means your configuration is not valid and you should review the previous steps before proceeding.

Configuring your Realtime Application Key

Now that you have your Certificate and Private Key you just need to enter them in your Realtime Cloud Messaging subscription details.

To do that select the Realtime subscriptions at the Accounts console and select the edit details option of your subscription.

The Mobile Push Notifications will be OFF by default.

Slide the Mobile Push Notifications to the ON position. The configuration fields will be shown.

Now open the CertificateName.pem file and copy the text from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE----- (including these marks). Paste the copied text at the certificate field of your Realtime Accounts Console.

Repeat the copy process now from -----BEGIN RSA PRIVATE KEY----- to -----END RSA PRIVATE KEY----- and paste the copied text at the private key field.

Keep the sandbox option checked while you are in development. When you’re ready to move your app to production you’ll need to repeat the process with the APNS production certificate and private key. At that moment uncheck the sandbox option and you’ll be ready to use the Apple production platform.

Now you only need to click the SAVE button to register your changes and start using the Realtime Mobile Push Notifications.

At this moment you are ready for receiving push notifications. Congratulations!

Remember that app Id that you have just created? When creating or configure your application, you should set a Product Name and Company Identifier corresponding to the App ID that you made earlier in the Provisioning Portal. Don't forget to choose your Provision Profile on the Code Signing section of Build Setting for your target application

In Xcode 8+ you also need to enable "Push Notifications" and background mode "Remote Notifications" under the "Capabilities" tab of your application target.

Subscribing iOS devices to Mobile Push Notifications

In order to use the Realtime Mobile Push Notifications in an ObjectiveC project, your Application Delegate must inherit from RealtimePushAppDelegate. You will also need to call it's super in your application:didFinishLaunchingWithOptions: implementation (more technical details can be found here).

To subscribe to a Realtime channel using Push Notifications you only need to call the subscribeWithNotifications method instead of the normal subscribe method.

        [ortcClient subscribeWithNotifications:@"myChannel" 
        			subscribeOnReconnected:YES 
        			onMessage:onMessage];
        

The RealtimePushAppDelegate class will take care of all the details like retrieving the user device token and registering it at the Realtime Messaging servers for the appropriate Realtime channel.

For a Swift 3 project you simply need to add the RealtimeMessaging-iOS-Swift3-Push Pod dependency in your project Podfile and invoke the method subscribeWithNotifications to subscribe to the desired channel.

Example

We know there's nothing like a good example, so checkout the real-time group chat app, using mobile push notifications to notify users of new chat messages when they are offline.

You’ll be able to find the complete source in the following GitHub repositories:

Getting ready for production

Prior to submitting your app to the App Store, you will need to configure push notifications for distribution. There are two types of distribution profiles: Ad Hoc, and App Store. You will need the latter to submit your app to the App Store, however it is good practice to test push notifications using an Ad Hoc profile prior to submitting your app.

Repeat the steps in this guide but instead of generating the certificate for development generate for production. Also generate the provisioning profile for Ad-Hoc first to test your app using the APNS production gateway and only after generate the App Store provisioning profile to Archive and upload your app to the App Store.

To test your certificate and private key for APNS production use the following command:

openssl s_client -connect gateway.push.apple.com:2195 -cert myapnsappcert.pem -key myapnsappprivatekey.pem

Obtaining an error means your configuration is not valid and you should review the previous steps before proceeding.

Don't forget to configure your Realtime application key to use the new production certificate and private key in the Realtime Account Management website, keeping "sandbox" unchecked.

Note that once you have uploaded a production certificate to Realtime, you will only be able to target devices using a distribution provisioning profile. Devices running an app signed with a development provisioning profile will need to install the newly provisioned build again.

Back to Mobile Push Notifications - Next: Mobile Push Notifications for Android

If you find this interesting please share: