AeroDoc push notification application, step by step

Last AeroGear release (1.1.0) main focus is on push notifications. Push notifications are heavily used in today mobile apps. They become key features, changing the UX in a push-notification-enabled application. Notifications' role is to wake up applications to provide updates, and that simple feature fulfils 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), even the web push is on its way with SimplePush notification for Firefox OS, it mays quickly sound like cacophony to a developer willing to target multiple market places. Here comes UnifiedPush Server, a solution to treat push notifications in cross platform approach. Push in the Open.

But AeroGear UnifiedPush Server, in short how does it work?

A picture is worth a thousand words:

1. Push application registration: UnifiedPush 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 day and mobile sales agents, most of their time on the road, 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 agents 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 AeroDoc 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 UnifiedPush Server

UnifiedPush server should be up and running. To install it on Wildfly, follow instructions from aerogear unified push server github repo. Alternatively, you can used the cloud deployed version in OpenShift.

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 UnifiedPush 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 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 UnifiedPush 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:

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

public void sendLeads(List users, Lead lead) {
        if (getActivePushConfig() != null) {
            Map categories = new HashMap();
            categories.put("lead", "version=" + leadVersion++); 
            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 {
           ....
        }
    }

Here we're sending to a list of users (see aliases method) of any variants of AeroDoc application, a message with a version and business attributes like name, location... Notice some native specific attributes 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 enable push notification?

First register your iOS app for Apple:


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"

< How does your iOS app register to AeroGear push notification? Once you get registered with APNS, you get a deviceToken:

- (void)application:(UIApplication> *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
  [self.viewController setDeviceToken:deviceToken];
}

It's now time to register to UnifiedPush server. It's done in application: didRegisterForRemoteNotificationsWithDeviceToken: where you register using the deviceToken provided by Apple with the variantId and secret you got when registering your iOS variant:

- (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:^() {
       ...
    } failure:^(NSError *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!
Maria is Minnesota, AeroDoc admin sends the lead to her.

1. lead Alpha is pushed to Maria

2. Maria accept the lead

3. lead Alpha is broadcasted as accepted and remove form available leads.

Step6: Android AeroDoc app

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

Step7: Web based AeroDoc app

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

Stay tuned!

UnifiedPush server is one feature of AeroGear project, there is more in it and more to come.






Tweet