Sunday Jun 09, 2013

Push Notification Support and (Provide Your Own?) Provider (Part 1)

Updated Aug 2, 2013 - see the paragraph below in red for the additions. 

Note: This is the first part of a multi-part series on Push Notification support.  First part focus on how Push Notification works, and discuss implementation options.  Future parts would include sample Push Notification applications and specific examples/use cases. 

ADF Mobile 11.1.2.4 adds Push Notification Support to ADF Mobile.  Push Notification I am sure is a familiar concept for everyone - at one time or another we have all received Push Notification from popular mobile apps such as Facebook, Email, Twitter, etc.  Implementing Push Notification has been made much easier with ADF Mobile 11.1.2.4, especially since it provides cross-platform support for notifications.  However, client-side code is only half of the story.  Below are some details around how Push Notification works, how you would implement client side code, and what you should implement on the server side.

What Is Push Notification?

Generally Push Notification mechanisms requires mobile platform vendors to host some server-side services that can deliver notifications to devices, as well as some services in the mobile OS to process the notifications.  ADF Mobile integrates with device-native push notification mechanisms, and they are:

For details of how these mechanisms work, as well as re-requisite such as setting up SSL certificates or accounts, please click on the link above and navigate to the respective websites.

How Does It Work?

There are four primary components in delivering Push Notifications to end users:

  • ADF Mobile Application: The framework has added hooks that would allow an ADF Mobile app to register with the Push Notification Services, launched from device's push notifications and messages, and start special application logic to process the Push Notification and its message content.
  • Mobile Device Operating System: Mobile Device Operating Systems brokers push notification registration and requests between the server-side services and mobile applications, as well as providing the critical visual cue for inbound messages.  For a demo of what push notification looks like, please follow this link to view the 11.1.2.4 New Feature video.
    • The iOS operating system allows end users to configure notification alerts as banner on top of the screen, an alert popup message, or turn off visual notification altogether.  All messages would be queued and listed in the Notification Center.  User would be able to launch the application from any of these mechanisms.
    • The Android operating system simply displays the push notification in the device's Notification Manager, and user can launch the ADF Mobile application from the notification entry.
  • Push Notification Services: Apple Push Notification Services and Google Cloud Messaging service hands device/application registration requests from the devices, as well as acts as a gateway for the Provider to send the notification to.
  • Provider (Application Server): Provider is a set of server-side services that developer would create to store device token and user information, as well as initiating the push notification request.  At this time, ADF Mobile does not provide out of box server-side Provider services, but this article does provide a very simple sample of the Provider service.

The following is an event diagram of the entire Push Notification lifecycle:


There are a few steps during the development of the ADF Mobile application that would enable the app to leverage the Push Notification services.  These steps are described in the next section.  For now, assuming that the application has been developed to enable push notifications: 

  1. When an ADF Mobile application starts up, it would initiate a registration request with push notification services.
  2. The registration request goes to the mobile device operating system.
  3. And the operating system pass the request to the Apple Push Notification or Google Cloud Messaging Services.
  4. The Push Notification service would pass a token (a string consisted of alpha-numeric characters) back that would uniquely identify the ADF Mobile application and the device.
  5. This token is then received by the ADF Mobile application.
  6. When the token is received, the onOpen method in the Application Lifecycle event listener is invoked.
  7. In the onOpen Method, you would typically register the device with your Provider application.  In order to properly support Push Notification functionality, the Provider application would typically need the following information from the ADF Mobile application:
    • The Token that uniquely identifies a device and the ADF Mobile application
    • Mobile operating system type if the application supports multiple operating systems
    • User ID if Provider needs to push notifications to specific user(s)
At this point, the Provider application has enough information to send notifications as needed.  You the developer of course would decide when you want the Provider application to push notifications, which typically correspond to some business events that you want to push to the end users.  When the Provider server application needs to push notifications to the ADF Mobile application running on users' devices, the following occurs:
  1. The Provider send the notification payload, Push Notification certificate, and the token to the push notification service.
  2. If the SSL Certificate is valid, the request would be accepted by the Push Notification service.  The Push Notification service would then verify the identity of the device and validity of the application with the token.
  3. If Push Notification service is able to verify the device and application, the Push Notification with its payload is sent to the device.  At this point, an alert or a message in the notification center of the device is displayed if the ADF Mobile application is running in the background or not running.
  4. When user clicks on the alert or message, the ADF Mobile application is then brought to the foreground if it is running in the background, or launched if it is not running.  
  5. At this point, the onMessage method in the application lifecycle event listener is called.  The onMessage method is where you would add the logic in the ADF Mobile application to handle the notification.  For details of the Push Notification behavior under different application state, please refer to the Push Notification chapter in the ADF Mobile Developer Guide.

How Do I Implement Push Notification?

The following are the key steps to follow and components to implement

  • Register with iOS and Android Developer Programs.  
  • Set up developer account for Push Notification development
    • For iOS, there are Application IDs, Provisioning Profiles, and SSL Certificates that need to be set up first.  Please consult Apple Developer Portal for details.
    • For Android, you would need to create a Project and obtain an API key from Google.  Instructions are listed here.  You will need these information when you create the request for Google Cloud Messaging service.
  • Implement client side (in ADF Mobile app) and server side (Provider) code.  

Client Side Code

In the ADF Mobile application, you will need:

  • Specify the Application Lifecycle Listener Implementation class in the adfmf-applications.xml file.  This allows you to invoke custom Java code during different phases of the application lifecycle.  
  • Add the PushNotificationConfig interface to the Application Lifecycle Listener class declaration:

    public class LifeCycleListenerImpl implements LifeCycleListener, PushNotificationConfig

  • In the start method of the Application Lifecycle Listener class, you would need to instantiate an eventSource object for the application, and add a listener to listen on native push notification events:

    EventSource evtSource = EventSourceFactory.getEventSource(NativePushNotificationEventSource.NATIVE_PUSH_NOTIFICATION_REMOTE_EVENT_SOURCE_NAME);
    evtSource.addListener(new PushNotificationListener());

    where PushNotificationListener is a class you would implement separately that handles Push Notification. 

  • Override and implement the getNotificationStyle and getSourceAuthorizationID methods of the PushNotificationConfig interface.  getNotificationStyle allows you to set the alert styles for an iOS application, and getSourceAuthorizationID allows you to enter the Google Project ID of the account where you would want to allow to send push notifications to ADF Mobile apps on Android.  Like this:
  public long getNotificationStyle () {

// Enable all possible alert styles

       return PushNotificationConfig.NOTIFICATION_STYLE_ALERT | PushNotificationConfig.NOTIFICATION_STYLE_BADGE | 
PushNotificationConfig.NOTIFICATION_STYLE_BADGE;
    }

 You will need to declare a Public String variable in your Application LifeCycleListenerImpl class and set it to the Google Project ID, and add this method below as well:

  public String getSourceAuthorizationId() {
          return SENDERID;
    }
  • Next, you would need to implement the listener class.  In this example, it's called PushNotificationListener but of course you can give it any name.  However, it must reside in the same project as the Application Lifecycle Event Listener class, and implements the EventListener interface.  Furthermore, the class would implement three methods invoked during the Push Notification event lifecycle - onOpen, onMessage, and onError.  As explained previously, onOpen is called during the Push Notification registration process, and onMessage is invoked when the ADF Mobile application is invoked and brought to the foreground.  onError is called when any error is encountered in the Push Notification lifecycle.  However, at the time of this blog, there is a bug where Push Notification errors would not properly invoke the onError method.  This fix is targeted for 11.1.2.4.2 (11.1.2.4 Patch 2).  Below is a skeleton of this class:
import oracle.adfmf.framework.api.AdfmfJavaUtilities;
import oracle.adfmf.framework.event.Event;
import oracle.adfmf.framework.event.EventListener;
import oracle.adfmf.framework.exception.AdfException;

public class PushNotificationListener implements EventListener {
    public PushNotificationListener() {
        super();
    }

    public void onMessage(Event event) {

//Invoked when a Push Notification arrives.

    }

    public void onError(AdfException adfException) {

//Invoked when any error is encountered in the Push Notification Lifecycle (not working at the time of blog publication

    }

    public void onOpen(String token) {

//Invoked during the Push Notification registration process. The parameter "token" contains the token received from APNs or GCMs that uniquely identifies a specific device-application combination.

    }
}

                                              Now let's look at what you need to implement in the onOpen and onMessage methods more closely.

                                              onOpen Method

                                              onOpen method is invoked when the ADF Mobile application successfully registered the device/application with the Push Notification service (APNs or GCMs), and the parameter "token" contains a string from these services.  The length of the token string is different between APNs and GCMs, but in general it uniquely identifies a device and application combination.  This is essential for you to be able to push message to a specific ADF Mobile app running on a particular device.  At this point, you can either send the token to the server-side Provider service, or simply save the token in an applicationScope variable for later use.  

                                              The server-side Provider service would typically need the following information:

                                              • Token, in order to send messages to a particular ADF Mobile app running on a specific device.
                                              • Mobile OS, in order to target messages to APNs or GCMs for this device.
                                              • User ID, as needed by the mobile application logic.  For example, push a notification to user X when a business event relevant to user X occurs.

                                              Of course you are free to choose any of then supported interfaces to send these information to the server-side Provider - via SOAP or REST services.   

                                              One key item to note - Mobile OS (part of Device Info Data Control) and User ID are not available inside the Application Lifecycle Event Listener, before the Listener is executed before Cordova and Security modules are loaded.  Therefore, you will need to send these information inside a feature - a logical place would be in the activate method of the Feature Lifecycle Event Listener class for the default and secured feature.  You can pass the token string into the Feature Lifecycle Event Listener via an applicationScope variable.

                                              Furthermore, if you choose to secure the Provider's device registration service, you must implement the registration logic within a secured feature that authenticates against the Provider's authentication services.  

                                              onMessage Method

                                              onMessage method is always invoked - either when ADF Mobile application is started/brought from the background when user clicks on the notification message/item, or automatically if the application is already running in the foreground as the active application.  The method is invoked with the payload of the notification - an Java object class called Event.  Java Doc for the Event class is missing from the initial version of 11.1.2.4 of ADF Mobile, and is still incomplete.  The most recent version of the Java Doc can be found here.  The Java Doc is missing explanation for the following two methods for the Event object:

                                              • getPayload: as the name implies, this returns the payload portion of the Push Notification message as a string.  
                                              • isStartTriggered: this returns a boolean indicating whether or not the ADF Mobile application is launched as the result of user acting on the Push Notification popup or an item in the notification center.  This is useful when you need to know whether the start (and therefore onOpen) methods of the Application Lifecycle Event Listener was executed prior to onMessage getting called.

                                              In the Application Lifecycle Listener - onMessage method, you can parse the event payload and invoke additional application logic accordingly.  One of the most common visual cue for Push Notification on iOS devices is through "badging", which adds a red circle containing numbers next to the application icon on the device.   For details of the new badging API, please consult this section in the ADF Mobile Developer Guide.  Another common scenario here is you may want to navigate to a particular AMX page in a particular feature, retrieve data from the server, and display a particular record based on the notification payload.  The high level logic to do this is:

                                              • First, ensure the Provider passes data object type and some unique Row ID in the message payload
                                              • In the onMessage method of the Application Lifecycle Event listener, parse the notification payload, and save Data Object type and Row ID into applicationScope variables.
                                              • Navigate to a particular feature based on data type
                                              • In the default task in the feature's AMX task flow, determine if the feature is invoked as the result of a push notification using, for example, a Router.
                                              • Router can then navigate to an AMX page that can retrieve the data from the server and perform a setCurrentRow based on the unique RowID from the applicationScope variable

                                              Server-side Code

                                              The server-side code, or commonly referenced as the "Provider", will need to support at least these two services:

                                              • Token and User Registration Service: this service is invoked when the ADF Mobile application sends the token and any other relevant information to the Provider.  You may use expose any of the supported networking interface (SOAP or REST), as well as secure this registration service.  You will typically want to store the device token and other relevant information in a data store so they can be used later.
                                              • Push Notification Delivery Service: this service is invoked by your server-side logic when Push Notification needs to be sent to one or more devices.  This service needs to send the token, SSL Certificate, and the Notification payload to APNs or GCMs.  The format of the Push Notification call can be found in Apple and Google developer sites.

                                              Push Notification provides a channel to push notifications to clients, and the notification payload can contain some limited set of parameter-value pairs that can be parsed by the ADF Mobile app.  However, it is not intended to send the business data nor used to "synchronize" data between the client and the server.  It is intended to pass certain key values that the ADF Mobile application would need to, say, display a particular piece of data for which the notification is intended for. 

                                              Furthermore, neither Apple nor Google guarantee the delivery or the order of the Push Notification messages.  Therefore, treat each of the push messages as a self-contained set of operations, rather than relying on multiple messages to perform some business logic. 

                                              Future Blog Entries on Push Notification

                                              Additional blog entries on Push Notification will be published to cover additional details around Provider implementation, sample client-side implementations, as well as specific integrations with Fusion Middleware and Application backends.  Please return to the ADF Mobile team blog and other related blog entires/ADF Insider sites for future articles.  If you have further questions on this topic, please contact us through the ADF/JDeveloper Forum, or one of the PMs for ADF.

                                              Thanks,

                                              Joe Huang 

                                              Monday Jun 03, 2013

                                              Free ADF Mobile eCourse available!

                                              Announcing the launch of a new, interactive, online, and FREE ADF Mobile course: Developing Applications with ADF Mobile. The course blends media-rich content to bring you interviews with the experts, engaging interactions, and inviting demos and graphics that keep you interested as you learn all about ADF!  Developing Applications with ADF Mobile will take you straight through from the basics of ADF Mobile, to developing mobile applications, accessing web services, and integrating with mobile device functionality. A future release of the course will include mobile security topics as well. Online learning doesn’t have to be a mundane, passive experience. Put on your headphones, take ADF Academy for a spin, and be prepared to lean in and learn ADF.

                                              ADF Academy: Developing Applications with ADF Mobile is available for free on OTN – check it out!

                                              Friday May 31, 2013

                                              New ADF Mobile Insider video: Adding Charts to Your ADF Mobile Application

                                              A new ADF Mobile Insider video: Adding Charts to Your ADF Mobile Application was recently posted on YouTube.

                                              This demo shows how to build and format bar, pie, and combo charts, including:

                                              • Creating the charts using data binding
                                              • Changing series colors and marker types using the seriesStyle tag
                                              • Formatting the numbers on the Y axis
                                              • Configuring the chart legend

                                              Please let us know if you have any questions or feedback on charting in ADF Mobile.

                                              Thanks,

                                              Katarina Obradovic-Sarkic

                                              Wednesday May 22, 2013

                                              ADF Mobile 11.1.2.4 tid-bits and updates

                                              If you have recently migrated to ADF Mobile 11.1.2.4, or have just started ADF Mobile development, you may have seen some issues or puzzling tid-bits for the new version of ADF Mobile.  Here are a few key items worth noting:

                                              • You may have seen a little red icon on the upper left corner of application, and wondering if the framework somehow detected a bug in the mobile application.  As matter of fact, it simply indicates the application has been deployed in debug mode.  Deployment console window in JDeveloper also provides extra reminder that the application has been deployed in debug mode.

                                              • Google recently released Revision 22 of the Android SDK Tools.  Along with the update, Google has also made available a new SDK Zip download file containing a new "build-tools" folder.  A few of the utilities necessary for deploying an ADF Mobile application has been moved into this folder, which would cause deployment errors if you are using this new version of the zip file.  This only impact NEW download of the SDK zip file - if you have downloaded the zip file previously and simply updated the tool to Revision 22, deployment is expected to work as before.  This only applies to brand new downloads of the zip.  
                                                • If you have downloaded the latest SDK Zip and unable to deploy, please see this blog entry for workarounds.
                                                • This issue is planned to be addressed in one of the upcoming 11.1.2.4 patches.
                                              • 11.1.2.4 introduced push notification support, and many of you are wondering how to actually leverage this feature.  We are working on publishing further details on this topic - please keep watching this blog site.  In preparation for implementing push notifications, it would also be helpful to understand how Apple Push Notification (APN) and Google Cloud Messaging (GCM) Service work, and their pre-requisites.  APN and GCM both require some setup through the respective developer portals, regardless whether you are developing an app using ADF Mobile or just native tools.
                                              • One infrastructure change that should not impact most developers is update from PhoneGap 1.0 to Cordova 2.2.  However, if you are using localHTML or remoteURL features, you will have to conform to the Cordova 2.2 JavaScript APIs.  No changes are needed for AMX features using device data controls.
                                              • In case you have missed it in release notes, the way localHTML pages include framework and Cordova JavaScripts have also been greatly simplified.  You can replace all these references to adf.el.js/phongap/etc JS files with simply this - please note that adf.wwwPath may need to be adjusted according to where you place your HTML files.  The below example has local HTML file in a subfolder within the Web Content folder, i.e. .../public_html/helloWorld/localHTML.html
                                                      <script type="text/javascript">if (!window.adf) window.adf = {}; adf.wwwPath = "../../../../www/";</script>

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

                                              • Xcode 4.6 has been released.  While it was not fully certified, it is supported.  This is also necessary for Xcode to properly recognize iOS devices running the latest iOS version.
                                              • Android SDK Tools Revision 22 as referenced above has also been released.  It is known to work although with the workaround required above if you are downloading the SDK Zip rather than just updating the SDK Tools from an existing installation.
                                              • The ADF Mobile team is planning to release patches for 11.1.2.4 to address some late breaking issues.  They will be released over the next few weeks through the JDeveloper update center.  JDeveloper should notify you of these updates.

                                              Hope this article helps to address some questions.

                                              Thanks,

                                              Joe Huang 

                                              Thursday May 16, 2013

                                              Debugging ADF Mobile Apps on Devices using Native Tools

                                              In-Depth Debugging Using Device Native Tools
                                              In-Depth Debugging Using Native Tools and Devices

                                              Hi, everyone:

                                              As most of you are aware, ADF Mobile can hook into JDeveloper's Remote Debugging to support Java code debugging, such as setting breakpoints and stepping through the code interactively from an emulator or an actual device.  The steps to enable debugging are described in the latest ADF Mobile Developer Guide, and Shay also had a nice entry on how to enable debugging on Android.  The developer guide also contains details on how to enable more refined levels of logging, and view log output using either the Mac Console application or the Android Monitor application.  Let's explore how all this works in a bit more detail. 

                                              Furthermore, log output to the Mac console may not display certain logging messages - for example ones coming from the embedded Java Virtual Machine.  This is due to some compatibility issues between Mac OS (Mountain Lion) and the log output mechanism.  In this article, we will also discuss how to properly output all logging messages and perform more in-depth debugging and analysis using device native tools, with the same capability that native application developers enjoy when debugging an application written in native code such as Objective C.

                                              iOS Debugging Using Xcode Utilities

                                              Unreliable logging from the Java Virtual Machine is a major issue with debugging ADF Mobile application on iOS devices or simulator.  The underlying cause is incompatibility issues with Java Virtual Machine running on the latest Mac OS (Mountain Lion).  Furthermore, it is difficult to debug on an actual device - necessary when debugging issues with invoking device services such as camera or GPS.  However, you can use Xcode and a tethered iOS device to display all logging messages from the device, ADF Mobile container, and the embedded JVM, while running the ADF Mobile application.  To do this, you will need:
                                              • A Mac running Moutain Lion or Lion
                                              • Latest version of Xcode - as of May 2013, the latest version is 4.6.2.  Latest version of Xcode is necessary to properly recognize devices running latest version of iOS, as older versions of Xcode cannot properly connect to the most recent version of the iOS.
                                                • One frequently asked question here is that ADF Mobile does not always officially support the latest version.  In general, officially supported version has been thoroughly tested by Oracle QA, and therefore is recommended for most development purposes.  However, the latest version of Xcode would typically be compatible - please check JDeveloper Forum for any reports of issues. 
                                                • If indeed ADF Mobile for some reason can't  use the latest Xcode version to deploy an application, you can still follow the steps below.   When you open the temporary Xcode project generated by JDeveloper, you would simply use the latest version of Xcode.  The rest of the instructions would still be valid.
                                              • Oracle JDeveloper and ADF Mobile
                                              • An iOS device
                                              • Obtain and install Apple iOS Developer Certificates and Provisioning Profiles.  When you deploy your ADF Mobile application, you must deploy in Debug Mode, using Developer Certificates and Provisioning Profile. 
                                              Here is a short video of how to modify the temporary Xcode project and use Xcode utilities to display all logging messages from an ADF Mobile application running on a device.


                                              Android Debugging Using Android Debug Monitor


                                              Shay recently published a blog article on viewing logs and debugging on Android devices.    Debugging using an Android device using Android Debug Monitor is much simpler to set up.  There is no need to work with the temporary Android application project.  Instead, you will just need:
                                              • A PC, Mac, or Linux machine supported by the Android SDK
                                              • Latest version of Android SDK Tools - this refers to the set of tools and utilities that are part of the Android SDK.  Android Debug Monitor is part of that.
                                              • Oracle JDeveloper and ADF Mobile
                                              • An Android-based Device and associated device driver installed (for PC and Linux Machines)
                                                • Please note that the appropriate drivers on PC and Linux are typically needed for proper connection to the device.  If the machine cannot properly recognize the device, then debugging will not be possible.
                                              In addition to what Shay discussed in his blog article, a couple of additional notes that might be useful if you are looking at logging messages outside the embedded Java Virtual Machine:
                                              • In the LogCat window, set the filter by application ID.  You would see all logging messages related to the application, which includes events coming from the native part of the application (i.e. container), Cordova, device services, etc. 
                                              • You can optionally set your application as a "Debugging Application" by going to your device Settings-Developer options-Select debug app, and then select the ADF Mobile application you want to debug.  All applications compiled in "Debug" mode will show up here.  This will allow you to select the ADF Mobile application process in the Android Debug Monitor app, and perform additional debugging - most likely much more info than you will ever want (or care) to know.
                                              Please let us know if there are any issues or questions.

                                              Thanks,

                                              Joe Huang

                                              About

                                              This blog is is dedicated to tips and tricks for developing, integrating, securing, and managing mobile applications using Oracle Mobile Platform. It is created and maintained by the Mobile Suite/Oracle ADF Mobile product development team.

                                              Archive of past entries

                                              Even More Mobile Development Blogs

                                              Oracle A-Team Site - Mobile Related Entries

                                              Code samples from the Community

                                              Fusion Middleware Blogs

                                              Search

                                              Archives
                                              « April 2014
                                              SunMonTueWedThuFriSat
                                                
                                              1
                                              2
                                              3
                                              4
                                              5
                                              6
                                              7
                                              8
                                              9
                                              10
                                              12
                                              13
                                              14
                                              15
                                              16
                                              17
                                              18
                                              19
                                              20
                                              21
                                              22
                                              23
                                              24
                                              25
                                              26
                                              27
                                              28
                                              29
                                              30
                                                 
                                                     
                                              Today