Building a Notification App for iOS with Sencha Touch and PhoneGap – Part 1 of 4

Push it….Push it real good!

At Fig Leaf Software, we’re seeing increased demand to add push notifications to our customer’s mobile apps. Push notifications are a great way to notify your customer base about important events.

While Sencha Touch 2.x directly supports push notifications through its Ext.device.Push class,  as of this writing, its support is limited to iOS. We therefore opted to use a PhoneGap-based solution, described below, that supports both iOS and Android in order to support a broader audience.

(click here if you didn’t get the salt & pepa reference above)

• Part I of this tutorial focuses on using Apple’s developer portal to generate the required certificates necessary for app compilation and testing. It also describes how to prepare a PhoneGap project to support push notifications.
• Part II of this tutorial focuses on using PHP on a test server for sending push notifications to Apple. (coming soon!)
• Part III of this tutorial describes how to integrate the PhoneGap Push Notifications plugin with your Sencha Touch application. (coming soon!)
• Part IV of this tutorial describes how to make your application available to beta testers

Prerequisites

This tutorial assumes that you have procured an iOS developer account ($99 USD) and that you’re working with Sencha Touch 2.2+ and Sencha Cmd 3. You’ll also need a physical iOS device (I used an iPod Touch) and tethering cable, since notifications are not supported by the iOS simulator. No prior experience with compiling a Sencha Touch app is necessary to complete this tutorial.

PART I: Download the required software

1. Download and install XCode
2. Download PhoneGap 2.50
   Note: Sencha Touch seems to have some difficulties with Phonegap > 2.50
3. Download the Cordova PushNotification Plugin
4. Download the Cordova openUDID plugin
   Note: This is used by the Cordova PushNotification plugin
5. PHP for OS/X, which you can enable by following these instructions.

Part II: Generate a Development Cert for your App

1. Log into the iOS provisioning portal
2. Click the link for Certificates, Identifiers, and Profiles
3. In the iOS Developer Portal, click on Certificates
4. Click on the [+] button
5. Select iOS App Development and click Continue
6. Follow the on-screen instructions to create a CSR file and click Continue.
7. Click Choose File and select the CSR file that you created in the previous step.
8. Click the Generate button.
9. Click the Download button
10. Double-click on the .cer file to install it into Keychain Access
11. Return to the iOS Developer portal and click the Add Another button.

PART III: Register your App with the iOS Provisioning Portal

1. Log into the iOS provisioning portal
2. Click the link for Certificates, Identifiers, and Profiles
3. Click on Certificates
4. Click on App Ids
5. Click on the [+] to define a new App ID
6. Fill out the form:
   1. Enter an App ID Description, e.g. ‘Fig Leaf Software Notifications’
   2. Under the App Services heading, check the box labeled “Push Notifications”
   3. Enter a bundle id  in reverse domain style, e.g. ‘com.figleaf.notifications’
7. Click the Continue Button
8. Click the Submit Button. Your App’s definition should resemble the following:
   
   

Part IV: Create a Push Notification Development Certificate

This is used by your server to communicate with Apple’s Push service. Each app will have its own development and production push notification SSL certificate.

1. Click back on App IDs and  select your app. Note that the items labeled Push Notifications are marked as “Configurable” as illustrated below:
2. Click the Settings button. At the bottom of the screen, under the Push Notifications heading, you should see output similar to the following:
3. Click on the Create Certificate button under the Development SSL Certificate.
4. Go through the process to generate the certificate.
5. Click on App IDs
6. Click on your application
7. Click on the Settings button
8. Click on the Download button to download the Development SSL Certificate for Push Notifications
9. Double-click on the certificate that you downloaded in the prior step in order to install it into KeyChain Access.

Part V: Registering Test Devices and Defining a Provisioning Profile

1. Open XCode
2. Tether your iOS device to your computer.
3. Select Window > Organizer
4. Click on the Devices tab.
5. In the Devices column, click on your device. Organizer should appear similar to the following:
6. Copy the device’s identifier to your clipboard
7. Return to the iOS Provisioning portal in your browser.
8. Click on Devices.
9. Click on the [+] to register your device.
10. Register your device as illustrated below:
    
11. Click Continue
12. Click on the Provisioning Profiles link
13. Click the [+] to add a new Provisioning Profile
14. Click the Radio button labeled iOS App Development
15. Click Continue
16. Select your App from the select list and click Continue.
17. Choose your iOS Development Certificate and click Continue.
18. Choose your device and click Continue
19. Enter a name for your profile, e.g. Notification App Testing
20. Click the Generate button.
21. Click the Download button.
22. Double-click on the downloaded mobileprovision file to install it into KeyChain access.

Part VI: Create a Phonegap Project

1. Unzip PhoneGap to a temporary directory
2. Create a folder in your webroot named Cordova
3. Copy PhoneGap’s lib/ios folder to webroot/Cordova. This should give you a /webroot/Cordova/ios folder.
4. Open a command prompt to /webroot/Cordova/ios/bin
5. Type the following command to generate an Xcode project:

   sudo .create [path to project folder] [application bundle id] [application name]
   

   e.g.:

   sudo .create ../../notifications com.figleaf.notifications FigLeafNotifications
   

6. Using Finder, set read/write permissions on the generated project folder and all of its files.
7. Verify that your project folder resembles the following:

Part VII: Install the PhoneGap Notification Extension into your XCode Project

1. Double-click on your .xcodeproj file to launch Xcode.
2. Unzip the Cordova Push Notification Plugin that you downloaded in Part I/Step 3 into a temporary folder.
3. Rename the Cordova Push Notification Plugin’s src/ios folder to ‘PushNotification’
4. Drag and drop the ‘PushNotification’ folder from finder into your project’s ‘Plugins’ folder in XCode. When prompted, select ‘Create groups for any added folders’
5. Copy the Cordova Push Notification Plugin’s www/PushNotification.js file into your Xcode project’s www folder.
6. In XCode, open your project’s config.xml file.
7. Add the following entry to the file’s plugins section:

   <plugin name="PushNotification" value="PushNotification" />

8. In XCode, open classes/AppDelegate.h
9. Append the following line just below the other imports:

   #import "PushNotification.h"
   

10. In XCode, open classes/AppDelegate.m
11. Append the following code just before the @end statement located at the end of the file:

     #pragma - PushNotification delegation
    
        - (void)application:(UIApplication*)app didRegisterForRemoteNotificationsWithDeviceToken:(NSData*)deviceToken
        {
            PushNotification* pushHandler = [self.viewController getCommandInstance:@"PushNotification"];
            [pushHandler didRegisterForRemoteNotificationsWithDeviceToken:deviceToken];
        }
    
        - (void)application:(UIApplication*)app didFailToRegisterForRemoteNotificationsWithError:(NSError*)error
        {
            PushNotification* pushHandler = [self.viewController getCommandInstance:@"PushNotification"];
            [pushHandler didFailToRegisterForRemoteNotificationsWithError:error];
        }
    
        - (void)application:(UIApplication*)application didReceiveRemoteNotification:(NSDictionary*)userInfo
        {
            PushNotification* pushHandler = [self.viewController getCommandInstance:@"PushNotification"];
            NSMutableDictionary* mutableUserInfo = [userInfo mutableCopy];
    
            // Get application state for iOS4.x+ devices, otherwise assume active
            UIApplicationState appState = UIApplicationStateActive;
            if ([application respondsToSelector:@selector(applicationState)]) {
                appState = application.applicationState;
            }
    
            [mutableUserInfo setValue:@"0" forKey:@"applicationLaunchNotification"];
            if (appState == UIApplicationStateActive) {
                [mutableUserInfo setValue:@"1" forKey:@"applicationStateActive"];
                [pushHandler didReceiveRemoteNotification:mutableUserInfo];
            } else {
                [mutableUserInfo setValue:@"0" forKey:@"applicationStateActive"];
                [mutableUserInfo setValue:[NSNumber numberWithDouble: [[NSDate date] timeIntervalSince1970]] forKey:@"timestamp"];
                [pushHandler.pendingNotifications addObject:mutableUserInfo];
            }
        }
    
    

12. Add the following block inside the ‘- (BOOL) application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary*)launchOptions’ function,  just before the return YES.

       // PushNotification - Handle launch from a push notification
        NSDictionary* userInfo = [launchOptions objectForKey:UIApplicationLaunchOptionsRemoteNotificationKey];
        if(userInfo) {
            PushNotification *pushHandler = [self.viewController getCommandInstance:@"PushNotification"];
            NSMutableDictionary* mutableUserInfo = [userInfo mutableCopy];
            [mutableUserInfo setValue:@"1" forKey:@"applicationLaunchNotification"];
            [mutableUserInfo setValue:@"0" forKey:@"applicationStateActive"];
            [pushHandler.pendingNotifications addObject:mutableUserInfo];
        }
    

13. Unzip the Cordova openUDID plugin that you had previously downloaded into a temporary folder.
14. Drag and drop the OpenUDID.h and OpenUDID.m files into your XCode project’s Classes folder.
15. In XCode, open www/index.html and add the following <script> tag after the <script> tag that loads cordova-2.5.0.js:

    <script type="text/javascript" src="PushNotification.js"></script>
    

16. Select your device from the list of test devices as illustrated below:
17. Click the Run button. The app should compile successfully and install to your device.

— End —