Push Notifications Template

Laziness is Good

Let's face it, setting up push notifications for the first time is a bit daunting... There's the <code>SenderId</code> the <code>RegistrationId</code>, the <code>AppId</code>. What does it all mean??? When do I use what? Why isn't there a working sample project that I can drop in my app information and it just works?

Well, we at CAPS wondered the same thing, so we went ahead and set one up for everyone!

Table of Contents

• What You Need
  • Xcode, Android SDK, Microsoft Visual Studio
• What You Get
  • The iOS App
  • The Android App
  • The Server App
• Making it Work
• Scaling
• Server Options
• Credits
• License

The iOS App

To start receiving push notifications on your iOS devices, there is a little bit of set up work that must be done before writing any code in Xcode. Here's what you need to do:

Create An App ID

• Go to the iOS Developer Center
• Click "Certificates, Identifiers and Profiles"
• Create an AppId
• Make sure you enable Push Notifications at the very bottom of the page

Provisioning Profile

• Create a new Development Provisioning Profile for the AppId you created

Certificates

• Create a new certificate of type "Apple Push Notification service SSL (Sandbox)"
• Select the same AppID you've been using so far.
• Open "Keychain Access" on your Mac
• Click "Keychain Access->Certificate Assistant->Request A Certificate from a Certificate Authority" in the menu
• Enter in your credentials, and make sure it's "Saved to Disk", not "Email to Authority"
• Save it to Desktop
• Go back to your web browser, and continue where you left off in the dev portal
• Upload the certificate request and it will give you a certificate to download
• Add the downloaded certificate to Keychain Access
• Select the certificate, and then click "File->Export Items" in the menu
• Export it as a .p12 file - this is what you'll add to your Push Server. We will be using them in The Server App section

Coding The App

After adding the .p12 file to your Push Server, and setting that up, you're ready to begin adding Push Notification functionality to your iOS app. There's really not much you need to do here - and we've created a special class for you that handles a lot of the functionality, <code>PusherMan.{h,m}</code>. Add those 2 files to your project, and then:

<code>#import "PusherMan.h"</code> into

• AppDelegate.h
• Any class/controller where you will be registering notifications with your server

PusherMan is a singleton class that just holds onto your device token during the duration of the app, and handles a couple auxiliary methods for registering for notifications with Apple, and retrieving the types of notification that a current device is registered for. Once you've imported PusherMan to your classes, there are only three more methods to add to your <code>AppDelegate.m</code> file, and you are ready to roll. Add these three methods below.

#pragma mark - Push Notification Methods
- (void)application:(UIApplication*)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData*)deviceToken {
    // Successfully registered the current device with Apple's Push Notification Service
	[PusherMan setDeviceToken:deviceToken];
}

- (void)application:(UIApplication*)application didFailToRegisterForRemoteNotificationsWithError:(NSError*)error {
    // The App was unsuccessful in registering this device for APNS
	NSLog(@"Failed to get token, error: %@", error);
}

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo {
    // This method is called whenever the App receives a Push Notification from Apple,
    // and the app is open - or they tap on the actual push notification on screen that
    // then launches this app and calls this method.
    NSLog(@"Notification: %@", userInfo);
    UIAlertView *alertView = [[UIAlertView alloc] initWithTitle:@"New Noticiation" message:userInfo[@"alert"] delegate:nil cancelButtonTitle:@"Ok!" otherButtonTitles:nil];
    [alertView show];
}

All of these methods are delegate callbacks for either successfully registering for Push Notifications, failing to register, or actually receiving the push notification on your device. These three have to be implemented to receive push notification functionality. Also, at the very top of your AppDelegate should be the method, <code>- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions</code>. Add this line to that method:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    [PusherMan registerAppForPushNotifications];
    return YES;
}

All that line does is begin the process of registering for notifications, and then the delegate methods you implemented a second ago handle the rest.

Coding Style for Notifications

Once you've set up your app to receive/handle push notifications, you still need to talk to your server to let it know how/when to actually send the notifications. How your app does this is entirely up to you, and changes on a project by project basis.

The Android App

First let us take a look at the sample Android app provided in the Android App Template folder of the root directory. Inside you will find an app with 3 files.

• MainActivity.java

  • The startup activity for the app. Nothing special here, but all of our registration setup with Google will go in this class.

• GcmIntentService.java

  • This class will be what handles the push notification when it arrives. The <code>onHandleIntent()</code> method handles the raw intent from the push notification services of the operating system, while <code>sendNotification(String msg)</code> will display the text of the notification in the Notifcation Drawer.

• GcmBroadcastReceiver.java

  • This class allows you to receive intents, in our case GCM Intents. It's basically like a switchboard that routes the notification to the <code>GcmIntentService.java</code> class.

The Sender Id

Take a look in the <code>MainActivity.java</code> and you will find this variable near the top: <code>String SENDER_ID = "971352002353";</code>. So, you may be wondering where this seemingly random number comes from. It is actually the Project Number for your app. You can also find it in the goole developer console. For our sample app, we have provided you with this number

Retrieve the Device Registration Id

Every Android device will have a Device Registration Id for push notifications for a specific app. It is a long string of characters that your device will have assigned to it when the app registers for push notifications. Each time you have a new app that you want to send push notifications to, you will need to retreive this identifier from google.

Good news: Our sample Android app already does this! Take a look in the <code>doInBackground() method in PushAsyncTask</code>. Here you are fetching the Device Registration Id from Google, and having it print to the LogCat. In a true system, once you receive the id, you would upload it to your server for safe keeping, but for the sake of example, run the sample app on your droid device and then grab the Device Registration Id from the LogCat. It should look something like this

APA71bGDFHk6HCWxskob04URTmd-MDV3FdKJarba0CcMgkxRtpQdSTqg9zoWDioimi0L-fNiTcgepiRsdGyMbv2gW1FM4FZFV9xlikaSiKrY8s-b3BH2T-bii6kEojdXoM9FR0I6vj2E8WDWLbApaHHYgoBU6wuwWA

Go ahead and copy/paste this somewhere, as we will need it when it comes time to send a push notification to your device.

The Server App

We have provided a sample push server using PushSharp, a great C# library for sending Android and iOS push notifications (and blackberry and windows phone). You can install it through the nuget package manager in visual studio, but for brevity, we have already set that up for you in the sample app.

The push server app is written in MVC 4 and uses Web API to send a test push notification in an event-driven manner, perfect for getting things up and running. Open up the project solution in the Push Server Template folder and head to the Controllers folder to find <code>PushController.cs</code> Here you will find the following Web API method:

[HttpGet]
public void testPush()
{
	var push = new PushBroker();
            
            //**** iOS Notification ******
            //Establish the connections to your certificates. Here we make one for dev and another for production
            byte[] appleCertificate = null;
            //appleCertificate = Properties.Resources.DEV_CERT_NAME;
            //appleCertificate = Properties.Resources.PROD_CERT_NAME;

            //If the file exists, go ahead and use it to send an apple push notification
            if (appleCertificate != null)
            {

                //Give the apple certificate and its password to the push broker for processing
                push.RegisterAppleService(new ApplePushChannelSettings(appleCertificate, "password"));

                //Queue the iOS push notification
                push.QueueNotification(new AppleNotification()