Telerik blogs

Part of the great appeal of hybrid apps is the opportunity to leverage not just native device features, but native "stack" features. These are things that require us to integrate not just with the device, but also with the proprietary cloud systems that power them. Push Notifications are a prime example of this.

Push Notifications are a message sent to your device with some metadata which the app that sent it uses to respond appropriately. Programming the client-side of push notifications is relatively simple.  It really involves the following...

  • Request permission to send notifications
  • When the notification arrives, handle the event that is fired when the user interacts with the notification and is taken into your app.
Push Notifications are not sent directly to the device.  They are instead sent to the OS vendors who then send to the device.  These OS vendors (by and large) would be Apple, Google and Microsoft.  In the case of some vendors (read Google) this is easy.  In the case of others (read Apple), not so much.

80% Configuration / 20% Determination

iOS has a rather convoluted certification and provisioning process. There are various types of certificates, provisioning profiles, registered devices - it can all get quite overwhelming.  Working inside the bounds of Apple's process is much like working with Java - it's 80% configuration and 20% sheer determination on your part.  

What we're going to do today is walk together though setting up Push Notifications on iOS. We're going to use the Everlive Push Notifications services so that we can expand push notifications to Android devices in the future should we choose to.

Prerequisites

Before we get started, you will be needing an iOS Developer Account. This is the $99 per year account that allows you to submit your application to the iOS App Store.

I'm also going to assume that you have an Icenium project created already. You don't need to be using Kendo UI Mobile.

I'll be breaking this process down into a series of steps while keeping it as concise as possible. This is not hard, just more complicated that we would like.  Here we go.

Create A New Provisioning Profile

If you don't already have one, head to the iOS Dev Center and go to the Certificates and Provisions Dashboard. You will want to create a new Certificate.

1. Create New Development Certificate

Push Notifications only work with development Apple profiles. You cannot work with the Ad Hoc or Production type since that will only work in production.

2. Generate A Certificate Signing Request From Icenium

In your Icenium project (Mist in this case), click on your name and then Options.  Then click on Cryptographic Identities in the left-hand nav.  Now create a new certificate signing request.

This will download a .csr file. Go back to the Apple Certification Dashboard and click Continue, then click Continue on the next screen. This will bring you to a screen where you can upload the .csr file you just created.

3. Upload Your Certificate Signing Request To the iOS Developer Portal

Click Generate. On the next screen, click Download.

Now you have a certificate that we can match up to the Certificate Signing Request we generated in step 2. Head back to Icenium.

4. Match the Certificate (.cer) To The Certificate Signing Request (.csr)

Back in the Icenium "Options" screen for iOS under Cryptographic Identities, you will see your request with an icon in the "Pending" column.

Select the check box out to the left and click the Import button. Select the .cer file created in step 3.

The Icenium Cryptographic Identities will now show your certificate as being good.

5. Create An App Identifier

Your application must have a unique identifier that is in the form of a goofy reverse URL (that I have never liked if you can't tell).

In any event, go to back to the Apple Developer Portal and go to the App ID's section. Create a new App ID. Make sure you enable Push Notifications at the bottom! Huge screenshot incoming...

Click Continue and the Submit

6. Make Sure Your Project Identifier Matches Your App Identifier

In your Icenium General Project properties, make sure your application identifier matches the one you just put into Apple's portal.

7. Create Your Provisioning Profile

Back to Apple's portal. Under Provisioning Profiles, click Development and click the + button to create a new one.

Make sure to create an iOS App Development Provisioning Profile.

Select your App ID from the next screen.

Select your certificate created in Step 3. I should have named mine something else since I now have two with exactly the same name and I don't know which one is which. Thanks Apple!

I suppose I'll just guess.

Click Continue and select the device you will be using for development. In my case, I only have my iPhone registered as a valid device for my developer account.

Click Continue. Give your profile a name and click Generate. You profile will now be ready and you can download it.

Now that you have your provisioning profile, you are ready to go back to Icenium and add it.

7. Add Provisioning Profile To Icenium

In the Icenium Options under Provisioning Profiles, import the file you just downloaded from the Apple Developer Portal.

Setting Up Push Notifications In Everlive

If you don't have an Everlive project created, now is a great time to do so.

Once in the project, you will need to go to Settings and click on the Push Notifications icon.

This is where you will need to upload your .p12 file. You don't have one of those yet, so lets create one.

1. Create A Certificate Signing Request

Go back to the Options section of Icenium and then the Cryptographic Identities section. Create a new one.

As with before, this will download a .csr file. Time to head back to Apple's Portal to create a new certificate for Push Notifications.

2. Generate A Push Notifications Certificate

In order to send push notifications, you need a Push Notification certificate. Create a new one and select the Apple Push Notification service SSL type.

Click Continue and then select the App ID you created for your app that has the ability to receive push notifications.

Now upload your certificate signing request. You're getting good at all this uploading and downloading aren't you!

Click Generate and download the newly created certificate.

3. Match The Certificate (.cer) To The Certificate Signing Request (.csr)

Head back to Icenium and complete the .csr by selecting the check box next to it and clicking Import.

Now you will have a certificate for Push Notifications.

4. Generate .p12 File

This is the file that will give us the .p12 that Everlive needs. Select it and click the Export button. You will be prompted to enter a password. You can make it whatever you want, but make sure you remember it.

5. Fix The Provision Profile

Now that you have created a new certificate for push notifications, your Provisioning Profile is invalid. Why? Because Apple says so. To fix it, go to Apple's portal and find the invalid profile, click Edit and then save it again. You will then need to download it again and replace the existing provisioning profile in Icenium with this new one.

5. Add .p12 File To Everlive

Head back to Everlive. You should still be on the Push Notifications configuration screen. Select iOS to enable this section. Select Development and upload that precious .p12 file.

Add the password you gave the .p12 file and click save.

Registering A Device For Push Notifications

1. Add The Everlive SDK To Your Icenium Project

Go to the "downloads" section in Everlive and select your project.

You will want to download the SDK for your project. Since we are working with hybrid, select the Hybrid And Web button and download the JavaScript SDK for hybrid mobile apps and websites.

This will give you a ZIP file. Go ahead and upload that Zip file to your Icenium project by selecting Add / From Archive. Select the EverliveSDK.zip file and upload it.

This will add src and min directories to your project. I usually create a folder called everlive and drop them in it.

Add the everlive.all.min.js file to your page from the min folder.

2. Enable Push Notifications Plugin

Cordova/PhoneGap applications require a plugin to be able to ask the device for permission to send push notifications. Icenium includes this plugin for you, you just need to toggle it on under Plugins in your project's Properties

2. Register The Device With Everlive

In your JavaScript for your Icenium project, you need to get register the device with Everlive, and enable push notifications.  Doing this will automatically trigger the underlying PushPlugin to interact with device API's to register the device with Apple as being a legit recipient.

// initialize the Everlive API
var el = new Everlive("YOUR EVERLIVE KEY");

// specify what push notification features we want
// access to on the device as well as events
var settings = {
  iOS: { badge: true, sound: true, alert: true },
  notificationCallbackIOS: function (e) {  
    // this event gets fired for iOS
  },
  notificationCallbackAndroid: function(e) {
    // this event gets fired for Android
  }
};

// re-registers a device with Everlive
var reregister = function () {
  var currentDevice = el.push.currentDevice();

  // in case we are using the simulator, make a fake token
  if (!currentDevice.pushToken) {
    currentDevice.pushToken = "some token";
  }

  return el.push.currentDevice().register();
};

// add the device to Everlive
var device = el.push.currentDevice();

// enable notifications on the device 
// this is what invokes the PushPlugin 
device.enableNotifications(settings)
.then(
  function () {
    // we have permission, register the device for notifications
    return device.getRegistration();    
  },
  function(err) {
    // DENIED for some reason
    console.log("Push notifications are not enabled " + err);
  })
.then(
  function (e) {
    // this device is already registered - no need to do it again
    console.log("Device is already registered: " + JSON.stringify(e));
  },
  function (err) {
    // the device is registered, but it's been removed from Everlive
    // re-register it
    if (err.code === 801) {
      reregister();
    }
    else {
      console.log(JSON.stringify(err));
    }
  })
.then(
  function (registration) {
    if (registration) {
      // we have successfully registered and turned on push notifications
      console.log("Successful registration");
    }
    // if there is an existing registration of the device the function will not receive 'registration' parameter
  },
  function (err) {
    console.log("ERROR! An error occured while checking device registration status: " + err.message);
  }
);

That might look like a stretch of code, but there are several things going on here.  The device is registered with Everlive, then we request permission to send the user push notifications.  We have to handle the user denying that request.  We also have to handle the possibility that the user said yes, but our registration has been removed from Everlive by us or some other process.

If you run this in the simulator, you can step through the code and watch Everlive give you back a fake push token. In order to test a push notification, you need to deploy the application to your device.

Deploy To Test Push Notifications

In order to actually test a push notification, you have to deploy it on your device. The simulator cannot test this for you.

Select Build then iOS and Provision.

Select the correct provisioning profile and hit build. Remember, an Ad Hoc provisioning profile won't work for testing Push Notifications.

Once you have built the app, you must deploy it to your device using iTunes. On a Mac, this is simply double-clicking the downloaded .ipa file and then installing in iTunes under "apps". On Windows, you need to hit the View menu and select Show Sidebar. You can then drag the .ipa file onto your device and sync.

When you open the application, it will ask you if it's OK for it to send Push Notifications. Be prepared to handle a no here if your user decides they don't want them.

Assuming you said "OK", you can now head back to the Everlive Portal and send a test notification. You will get a banner message and an icon on your app showing that their is one new push notification.

Whoa

Push Notifications are not hard to do, but Apple's certification and provision process makes this tedious on a good day. Special thanks to Thomas Mullaly who patiently guided me through this process. To be honest, once you wrap your head around the certificates and provisioning profiles, this is much much easier and far less convoluted.

About the Author
is a web developer living in Nashville, TN. He enjoys working with and meeting developers who are building mobile apps with jQuery / HTML5 and loves to hack on social API's. Burke works for Telerik as a Developer Evangelist focusing on Kendo UI. Burke is @burkeholland on Twitter.


Comments

Comments are disabled in preview mode.