0
0
1
2460
14028
Oracle
116
32
16456
14.0
Normal
0
false
false
false
false
EN-US
JA
X-NONE
How to implement push notifications in MAF 2.1.1
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 (refer to the Android Developer
site for details of how to install it) for connecting to the GCM server,
and sample code for connecting to APNs as described on the Apple
Developer site.
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:
Open the PushServer sample app in JDeveloper 12.1.3 with MAF 2.1.1 extension.
Modify the dummy database
connection as follows:
Expand Application Resources > Connections > Database to reveal pushServerDB.
Right-click on pushServerDB and select Properties.
Enter all the required
properties for the database you intend to use.
Verify the entered details by
clicking on Test Connection.
Save the entered details by
clicking on OK.
If you are using a non-Oracle
database, you may need to update certain properties of the configured
Application Modules as follows:
Open Projects > Model > Application Sources
> oracle.adfmf.demo > push > model > RegistrationModule >
RegistrationModel.xml.
Open the Configurations
tab.
Click on the link for
bc4j.xcfg.
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”.
Open the MessageBean.java file under Projects > ViewController > Application
sources > oracle.adfmf.demo > push.
Set the GOOGLE_APIKEY variable to your Google project’s API Key.
Set the IOS_KEYFILE variable to the full path to your iOS keystore (.p12 file).
Set the IOS_KEYPWD
variable to the password you set on your iOS keystore.
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.
Otherwise, leave both the PROXY_HOST
and PROXY_PORT variables set to null.
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:
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.
Start an instance of the
embedded WLS in JDeveloper via Run
> Start Server Instance.
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.
Once the WLS has started, open http://localhost:7101/console in your
preferred browser. This is the WLS
console.
Login to the WLS console as
user “weblogic” and the password you entered in step 3.
Turn off hostname verification
in the WLS console via Domain Configurations > Environment > Servers
> Default Server > Configuration > SSL > Advanced. By setting “Hostname Verification” to None.
Click on Save.
Deploy the server application
Deploy both components of the server application within JDeveloper as follows:
Expand Projects > ViewController > Application
Sources > oracle.adfmf.demo > Push to reveal RegistrationServlet.java.
Right-click on RegistrationServlet.java and select Run.
You can ignore the error
reported by the servlet, since it was launched without any parameters.
Expand Projects > ViewController > Web Content to reveal pushregistration.jspx.
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:
Open the PushDemo sample app in JDeveloper 12.1.3 with MAF 2.1.1 extension.
Open the adf-config.xml file found in Application Resources > Descriptors >
ADF META-INF.
Select the Source tab
and enter your Google project number into the value for the gcmSenderId
property.
Open the connections.xml file also found in Application Resources > Descriptors >
ADF META-INF.
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.
Save all your changes.
Deploy the client app
Follow these steps to deploy and run the PushDemo app:
Configure JDeveloper with the
name of your push-enabled iOS provisioning profile and corresponding signing
identity in Preferences
> Mobile Application Framework > iOS Platform.
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.
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.
Launch the app and it will
automatically register with APNs or GCM, as appropriate.
Switch to the Register feature and it should advise
that registration was successful.
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.
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.
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 and
try again.
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.
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:
Select the entry for your
mobile device.
Enter a message into the Message field.
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.