Push notifications are a fantastic way to notify your users of relevant information in a timely fashion, even when your mobile app is running in the background or not running at all.

The MAF 2.1.1 extension provides two sample applications – PushDemo, which demonstrates how to receive push notifications in a MAF app, and PushServer,  which demonstrates how to send push notifications to a MAF app.

This blog post will provide an introduction to push notifications and a detailed description of how to configure the PushDemo and PushServer sample applications, as a vehicle for learning about push notifications. Readers can use the lessons learned to implement push notifications in their own applications.

How push notifications work

Although technically different, the logical push notifications architecture is similar for mobile apps running on both Android and iOS, with Google and Apple each providing a cloud-based Push Notifications service that acts as the go-between your server application and your mobile app.

The flow of push notifications is also similar: including a registration process followed by the sending of a notification to one or more devices, as follows:

Each time a push-enabled mobile app starts, it registers with the Apple Push Notifications service (APNs) or Google Cloud Messaging (GCM), based on the device type.  The registration request includes an identifier. Successful registration results in a registration token being returned that uniquely identifies this mobile app running on this device.

The push notification will originate from a server application, so the mobile app must register with the server application, providing enough information for the server application to be able to uniquely identify the user associated with the app on this device. This registration with the server application would typically be done following successful authentication of the user and must include the registration token.

Having completed the registrations, when an event occurs later on that requires a push notification to be sent to one or more users, the server application reviews all the registrations and sends a push notification to the user’s registered device(s) via APNs, GCM, or both. Each push notification message includes the unique registration token for the target device.

Required push notifications setup

APNs

Apple requires you to create an explicit App ID that enables push notifications and a corresponding client SSL certificate. 

The App ID is used to create a provisioning profile that is embedded into your mobile app.  This provisioning profile informs APNs that your mobile app is a trusted app.

The client SSL certificate is used by your server application when communicating with APNs.   It informs APNs that your server application is a trusted application and that it is permitted to send push notifications to your mobile app.

For more information refer to Apple Push Notification Service and Configuring Push Notifications.

GCM

Google requires you to create a Google API project and obtain an API Key.

The project number is used by your mobile app as the Sender ID when registering with GCM. It indicates to GCM which server application (or server applications, since more than one Sender ID can be specified) is permitted to send push notifications to your mobile app.

The API Key is used by your server application as the Sender Auth Token when communicating with GCM. It gives your server application access to Google services and ensures that push notifications originating from your server application are targeted to your mobile app.

For more information refer to Google Cloud Messaging Overview and Getting Started on Android.

About the PushDemo sample app

The PushDemo sample app is a MAF app that works in conjunction with the PushServer sample app to demonstrate registration for, sending and receipt of push notifications. (More details about the sample apps provided within each MAF release and where to find them are provided here.)

The PushDemo sample app has three functions:

  • Each time you launch the PushDemo sample app, it automatically registers with GCM or APNs, as appropriate for your device, and receives a registration token.
  • It provides a registration page for you to initiate registration with a running instance of the PushServer sample app.  In a real-world app, this step would normally be automatically handled by the client app following a user login, or retrieval of stored user details.
  • It provides a page for displaying the message received when a push notification is received by the PushDemo sample app.

About the PushServer sample app

The PushServer sample app is a server application that uses a GCM client library provided by Google for connecting to the GCM server, and sample code for connecting to APNs.

GCM and APNs have different policies regarding push notification error handling and de-registration of devices.  The PushServer sample app does not provide any special handling, but you should be aware of these policies when designing your server application if it will support push notifications. To review these policies, refer to Implementing GCM Server and Provider Communication with Apple Push Notification Service.

There are two components to the PushServer sample app:

  • A registration servlet that enables an instance of the PushDemo sample app running on a mobile device to register with the server application.  The  registration request includes the registration token received from GCM or APNs, the mobile app’s Bundle ID, the user ID entered into the registration page of the mobile app and the device type.  These are stored in a database on the server for later sending of push notifications to the user’s mobile device.
  • A push notification page displays the registered devices and enables you to enter a message to push to a selected device.

How to configure and run the PushServer sample app

Apple and Google registration

To implement push notifications, the app must be registered with Apple and/or Google, depending on the device(s) you wish to use for testing.

If you are an Oracle employee, this has already been done for you and you can retrieve the necessary signing artifacts by clicking on the link “How to use the PushDemo sample app” found on the internal MAF uptake guide wiki.

Otherwise for customers, you will need to register your app with Apple and/or Google and retrieve the necessary signing artifacts, as described above under Required Push Notifications Setup.

Database setup

The PushServer sample app requires a database for storing the mobile device registration details. A dummy database connection called “pushServerDB” is provided in the connections.xml.

If you are an Oracle employee intending to run the server application on the Oracle intranet, you can configure the PushServer sample app to connect to a hosted database as described on the internal MAF uptake guide wiki.

Otherwise for customers, you must install a database, create the required schema using the pushschema.sql script found in the PushServer sample app’s Model/database folder and modify the properties of the “pushServerDB” database connection in the connections.xml file as follows.  If your database is not an Oracle database, you may also need to modify certain properties of the Application Modules that are configured in the bc4j.xcfg file.  The configuration steps are described below.

Server application configuration

Follow these steps to configure the server application:

  1. Open the PushServer sample app in JDeveloper 12.1.3 with MAF 2.1.1 extension.
  2. Modify the dummy databaseconnection as follows:
    1. Expand Application Resources > Connections > Database to reveal pushServerDB.
    2. Right-click on pushServerDB and select Properties.
    3. Enter all the required properties for the database you intend to use.
    4. Verify the entered details by clicking on Test Connection.
    5. Save the entered details by clicking on OK.
  3. If you are using a non-Oracle database, you may need to update certain properties of the configured Application Modules as follows:
    1. Open Projects > Model > Application Sources > oracle.adfmf.demo > push > model > RegistrationModule > RegistrationModel.xml.
    2. Open the Configurations tab.
    3. Click on the link for bc4j.xcfg.
    4. For each listed Application Module, select it and click on the Edit icon, open on the Properties tab, modify the relevant properties and click OK.  For example, to connect to a MySQL database, change the jbo.SQLBuilder property to “SQL92”.
  4. Open the MessageBean.java file under Projects > ViewController > Application sources > oracle.adfmf.demo > push.
  5. Set the GOOGLE_APIKEY variable to your Google project’s API Key.
  6. Set the IOS_KEYFILE variable to the full path to your iOS keystore (.p12 file).
  7. Set the IOS_KEYPWD variable to the password you set on your iOS keystore.
  8. If you will run the server application on a corporate intranet, such as the Oracle network, set the PROXY_HOST and PROXY_PORT variables appropriately.
  9. Otherwise, leave both the PROXY_HOST and PROXY_PORT variables set to null.
  10. Save all your changes.

WebLogic Server configuration

The server application must be deployed to a running WebLogic Server (WLS) instance.  The most convenient option for developers is to configure and run the embedded WLS within JDeveloper as follows:

  1. If you are on a corporate intranet, such as the Oracle network, configure the JDeveloper proxy settings in Preferences > Web Browser and Proxy > Proxy Settings.
  2. Start an instance of the embedded WLS in JDeveloper via Run > Start Server Instance.
  3. You will be prompted to enter and confirm a password.  At this point, you may also change the listening address or port.  I recommend you keep the default settings, which should be to listen on All Available Addresses using port 7101, with port 7102 for SSL.
  4. Once the WLS has started, open http://localhost:7101/console in your preferred browser.  This is the WLS console.
  5. Login to the WLS console as user “weblogic” and the password you entered in step 3.
  6. Turn off hostname verification in the WLS console via Domain Configurations > Environment > Servers> Default Server > Configuration > SSL > Advanced. By setting “Hostname Verification” to None.
  7. Click on Save.

Deploy the server application

Deploy both components of the server application within JDeveloper as follows:

  1. Expand Projects > ViewController > Application Sources > oracle.adfmf.demo > Push to reveal RegistrationServlet.java.
  2. Right-click on RegistrationServlet.java and select Run.
  3. You can ignore the error reported by the servlet, since it was launched without any parameters.
  4. Expand Projects > ViewController > Web Content to reveal pushregistration.jspx.
  5. Right-click on pushregistration.jspx and select Run.

How to configure and run the PushDemo sample app

Client app configuration

Configure the PushDemo sample app as follows:

  1. Open the PushDemo sample app in JDeveloper 12.1.3 with MAF 2.1.1 extension.
  2. Open the adf-config.xml file found in Application Resources > Descriptors > ADF META-INF.
  3. Select the Source tab and enter your Google project number into the value for the gcmSenderId property.
  4. Open the connections.xml file also found in Application Resources > Descriptors > ADF META-INF.
  5. Modify the url for the PushServiceConn connection by changing “127.0.0.1” to the relevant value for your server application, based on the network that will be shared by your server application and your mobile client app.
  6. Save all your changes.

Deploy the client app

Follow these steps to deploy and run the PushDemo app:

  1. Configure JDeveloper with the name of your push-enabled iOS provisioning profile and corresponding signing identity in Preferences > Mobile Application Framework > iOS Platform.
  2. Deploy the PushDemo app to your Android or iOS device, or Android emulator (you must use a “Google APIs” target).  Push notifications do not work on the iOS simulator.
  3. Ensure that your mobile device can access the Internet via a mobile data plan or wifi network.  Note for Oracle employees that push notifications are blocked on the “clear” wifi network, even with VPN enabled.  If you have no access to a mobile data plan or corporate wifi connection, you can setup a local wifi on the machine that is running the server application and connect to that.
  4. Launch the app and it will automatically register with APNs or GCM, as appropriate. 
  5. Switch to the Register feature and it should advise that registration was successful.
  6. If you have not registered your device with the server application previously, you will need to do this now.  If you are running your server application on a corporate intranet, such as the Oracle network, you will need to establish a VPN connection on your mobile device before communicating with the server application. 
  7. To register your device, enter a unique User ID into the client app and tap on the Register button.  A success or error message will be displayed below the Register button. 
    1. Note: The server application does not handle duplicate entries for one device and APNs or GCM may return a different token, so you may need to delete the old entry for your device from the database andtry again.
  8. If you are using an Android device and you have established a VPN connection, you must close this VPN connection now to ensure that you can receive push notifications.
  9. Switch to the Message feature, which will display any message received via push notifications.

How to send a push notification to the PushDemo sample app

When you deployed the server application's Push Registration page, it should have been displayed in your default browser.  You can send a push notification to the PushDemo sample app running on your mobile device from this page as follows:

  1. Select the entry for your mobile device.
  2. Enter a message into the Message field.
  3. Click the Push Message button.

Your mobile device should receive the push notification as follows:

  • If the PushDemo sample app is running in the foreground, the message you entered should be displayed on the Message feature’s main page.
  • Otherwise, your mobile device’s operating system should display the push notification in the standard manner. On Android, a notification banner is  presented for a short time and the notification can be viewed in the Notification Drawer. On iOS, depending on your notification settings, a banner or alert may be displayed and the notification can be viewed in the Notification Center.
  • If you tap on a notification displayed by your device’s operating system, the PushDemo sample app should be launched and/or moved to the foreground and the message should be displayed on the Message feature’s main page.

Conclusion

The PushDemo sample app demonstrates how to register for and receive push notifications using MAF 2.1.1. It works in conjunction with the PushServer sample app that demonstrates techniques for registering with GCM and APNs and sending push notifications using these services.

By following the steps described above, you should be able to send push notifications from a deployed instance of the PushServer sample app to your mobile device with the PushDemo sample app installed.

Based on the information and links provided in this blog post and the hands-on experience gained from configuring and using the provided sample apps, you should be able to implement push notifications in your own server application and MAF-based mobile app.