gistfile1.txt

Last AeroGear release (1.2.0) main focus is on push notifications. (TODO link to Matzew's blog.) Push notifications are heavily used in today mobile apps. They become key features, changing the UX in a push-notification-enabled application. Notifications can wake up applications to provide updates, and that simple feature brings thousands of business use cases.

However, with the broad variety of proprietary Push notification solutions: APNS (Apple Push Notification Service), GCM (Google Cloud Messaging), AMD (Amazon Device Messaging),  WNS (Window Push Notification Service), etc... and with SimplePush notification for Firefox OS, notifications are for web app too!  (TODO link to Dan)

It mays quickly sound like cacophony to a developer willing to target multiple market places. Here comes Unified Push Server, a solution to treat push notifications in cross platform approach. Push in the Open.

But AeroGear Unified Push Server, in short how does it work? 


A picture is worth a thousand words:



[TODO hylke picture]

1. Push application registration: unified push (UP) server is based on PUB/SUB model, you need to register you application. After registering your app, you will get a pushApplicationId. A push application can target different platforms. You can add variants to it. A variant contains platform specific properties, such as Google API key for Android, certificate credentials for Apple, or a PushNetwork URL for SimplePush. Out of the variant registration, you get a variantId and its associated secret.

2. Installation registration: This is the actual device registration. Given the pushApplicationId and VariantId and associated secrets, the device will register itself on first connection.

3. Send notifications: All set with registration, now your backend app wants to broadcast push notifications to all devices. Using sender API with its fluent message API, it's easy. You can do broadcast and selective send.

4. Underneath, UP server allows you to work with APNS, GCM or simply over the web with SimplePush

5. Receive push notifications whether you're online or offline.

And maybe we can do more than just talking about it let's see it in action. First of all we need a use case.

Our use case: AeroDoc


AeroDoc is a company in the health care industry, selling a revolutionary medial products. The company's sales department has a call center agents, doing phone calls all along the day and mobile sales agents, most of their time on the roads, attending conferences and meeting potential clients.

As soon as a call agent get a lead, he uses AeroDoc Admin app to filter out available sales agents in the neighbourhood of the company interested by the products. Call center agent can send mobile sales agents push notifications.

Sales agents receive the notifications on their smart phones. Once a mobile sales agent accepts the lead on his mobile device (using either iOS AeroDoc client app or Android Aeroc app), the other agents get a push notification that the lead is taken care of. In a highly competitive market, being able to process a lead directly is for sure a competitive advantage :)

Let's start our step by step approach

Step1: Deploy Unified Push Server


Unified Push server should be up and running. To install it on JBoss, follow instructions from aerogear unified push server github repo. Alternatively, you can used the cloud deployed version in OpenShift. (TODO Farah blog).

Step2: Deploy AeroDoc Admin app


Let's start cloning aerogear-aerodoc-backend github repository. AeroDoc backend should be deployed. Follow instructions from AeroDoc backend.

Step3: Register process


You have 2 options: either use the Admin Unified Push Server or do it simply with curl command. It depends whether you're more a UI person or command line addicted.

Login (reset password if needed) 
Register your application (https://github.com/aerogear/aerogear-unifiedpush-server#register-push-app) to get your pushApplicationID and a masterSecret  
Register your iOS variant. Start using development variant, you will need your apple provisioning as explained in prerequisites. You should get a variantID and a secret

Step4: AeroDoc backend configuration


AeroDoc backend needs to know: 
which url is your Unified Push Server, it could be local or running on OpenShift. 
what is your pushApplicationID and masterSecret

You can configure it using its UI as shown below:

[TODO AeroDoc admin UI picture]

Extracted from LeadSender, the service responsible to do selective send, get a feeling of the sender API:

    public void sendBroadCast(Lead lead) {
    public void sendLeads(List users, Lead lead) {
        if (getActivePushConfig() != null) {
            Map categories = new HashMap();
            categories.put("lead", "version=" + leadVersion++); //TODO manage the version properly
            UnifiedMessage unifiedMessage = new UnifiedMessage.Builder()
                    .pushApplicationId(getActivePushConfig().getPushApplicationId())
                    .masterSecret(getActivePushConfig().getMasterSecret())
                    .aliases(users)
                    .simplePush(categories)
                    .attribute("id", lead.getId().toString())
                    .attribute("messageType", "pushed_lead")
                    .attribute("name", lead.getName())
                    .attribute("location", lead.getLocation())
                    .attribute("phone", lead.getPhoneNumber()).sound("default")
                    .alert("A new lead has been created").build();

            javaSender.sendTo(unifiedMessage);
        } else {
            logger.severe("not PushConfig configured, can not send message");
        }
    }

Here we're sending to a list of users (see line 9) of any variants of AeroDoc application, a message with a version and a light business attributes. Notice some native specific attribute like alert/sound.

Step5: iOS AeroDoc app configuration


Let's start with cloning aerogear-aerodoc-ios github repo. In config file, let's configure your varianId and secret :

#define URL_AERODOC @"http://localhost:8080/aerodoc/" 
#define URL_UNIFIED_PUSH @"http://localhost:8080/ag-push/" 
#define VARIANT_ID @"YOUR_VARIANT" 
#define VARIANT_SECRET @"YOUR_SECRET" 
#define ENDPOINT @"rest" 

You're all ready to launch the application on your iPhone. Notice that for Push notification test you can not use your iOS simulator, you need to test it on actual device.

How does your iOS app register to push notification?

Just register your iOS app:

- (BOOL)application:(UIApplication *)application
        didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  ...
  [[UIApplication sharedApplication]
    registerForRemoteNotificationTypes: (UIRemoteNotificationTypeBadge 
                                       | UIRemoteNotificationTypeSound
                                       | UIRemoteNotificationTypeAlert)];
  ...
}

Once the application is started the first time, it prompts you with a dialog box, where you have to agree that the application may receive "Push Notification Messages"

Where should you handle the push notification?

In application: didRegisterForRemoteNotificationsWithDeviceToken: method do the actual device regitration as shown below:

- (void) deviceRegistration {
#if !TARGET_IPHONE_SIMULATOR
    AGDeviceRegistration *registration = [[AGDeviceRegistration alloc] initWithServerURL:[NSURL URLWithString:URL_UNIFIED_PUSH]];
    
    [registration registerWithClientInfo:^(id clientInfo) {
        [clientInfo setVariantID:VARIANT_ID];
        [clientInfo setVariantSecret:VARIANT_SECRET];
        
        // if the deviceToken value is nil, no registration will be performed
        // and the failure callback is being invoked!
        [clientInfo setDeviceToken:self.deviceToken];
        
        UIDevice *currentDevice = [UIDevice currentDevice];
        [clientInfo setAlias: [[AeroDocAPIClient sharedInstance] loginName]];
        [clientInfo setOperatingSystem:[currentDevice systemName]];
        [clientInfo setOsVersion:[currentDevice systemVersion]];
        [clientInfo setDeviceType: [currentDevice model]];
        
    } success:^() {
        DLog(@"PushEE registration successful");
    } failure:^(NSError *error) {
        DLog(@"PushEE registration Error: %@", error);
    }];
#endif
}


How to push lead to my iOS app?

go to AeroDoc admin UI
login as john with password 123
go to your iOS app login as maria/123
john create a new lead, select it, search for an available sale agent, select Maria and push a  lead to Maria.
and Maria received a new lead

[TODO iOS lead picture]

Step6: Android AeroDoc app


You're not an iOS person and want to see it in java, follow the readme on aerogear-aerodoc-android. [TODO add readme on aerodoc-android]

Step7: Web based AeroDoc app


You're neither an Object-C nor Java guy, you want to see pure JavaScript. Look at readme on aerogear-aerodoc-web.

Stay tune


Unified Push server is one feature of AeroGear project, there is more in it and more to come. Stay tune!