Send a Push notification from a mobile app in 5 m

IBM BlueMix is a beta-level product, and it will be changing as we continually make things better and easier to use. We'll do our best to keep this article up to date, but it will not always be perfectly aligned. Thanks for understanding.

You may already know about some of the benefits of IBM Bluemix™, IBM's open platform for developing and deploying mobile and web applications. The many pre-built services in Bluemix make it easy to build and enhance applications. In this article, we'll cover the steps for how to use JavaScript APIs to send a Push notification from your mobile app.

This article uses the open source Apache Cordova hybrid mobile application project. Apache Cordova enables mobile app developers to access native device functions through JavaScript. Cordova apps are written using standard web technologies, such as HTML, CSS, and JavaScript.

“As a mobile application developer, I want to get up and running with traditional native features like Push notifications as fast as possible. With open technologies like Apache Cordova and Cloud Foundry as part of IBM Bluemix, I found a way.”

What you'll need for your application

0

 

• Familiarity with Apache Cordova
• Familiarity with JavaScript for IBM Mobile Cloud Services
• Familiarity with IBM Mobile Cloud Services npm modules

Get the code

Create an Apache Cordova project

0

 

If you already have an existing hybrid mobile project, such as an IBM Worklight® project, skip this section.

1. If you haven't already done so, download the node packaged module for Apache Cordova and set up your environment for Apache Cordova.
2. After Cordova is installed, open a command prompt.
3. Create a new project in your current working directory by running the following command:

   cordova create bluemixpush com.example.bluemixpush BluemixPush

4. Change to the new project directory by running the following command:

   cd bluemixpush

5. Add the platforms you want to test on, by running the following command:

   ex. cordova platform add android

Note: If this is your first time developing a Cordova project for a specific platform, you need to perform some additional steps to set up the platform's development environment.

For example, to configure an Android environment, perform the following steps:

1. Install the Android SDK.
2. Add the Androidtoolsandplatform-toolslocation to yourPATHenvironment variable.
3. Download ANT and add it to yourPATHenvironment variable.
4. Ensure that the Java™ path is set in yourPATHenvironment variable. Note: Ensure that it's a full JDK, not just a JRE.
5. Optionally, download and install Eclipse with ADT to run the emulator and debug your application using the Eclipse LogCat capabilities.

READ:Apache Cordova plugins

Install the ibmbaas npm package

0

 

The Push service used in this article, along with many mobile cloud services provided as part of Bluemix, is available as a node packaged module. Install the ibmbaas package to initialize the Push service with the Bluemix mobile app.

1. On a command line, change to the hybrid mobile project's www directory.
2. As stated in the npm documentation for the ibmbaas module, to install for a web or hybrid application, use the bower package manager by running the following command:

   bower install https://hub.jazz.net/git/mobilec/ibmbaas/.git

Install the ibmpush npm package

0

 

Install the IBM Push service from npm:

1. On a command line, change to the hybrid mobile project's www directory.
2. As stated in the npm documentation for the ibmpush module, to install for a web or hybrid application, use the bower package manager by running this command:

   bower install https://hub.jazz.net/git/mobilec/ibmpush/.git

Successful installation of the Bluemix ibmpush package results in the following response.

Click to see larger image

Set up Bluemix

0

 

Now that you have a hybrid application ready to go and your own IBM Push service installed from npm, you need to set up Bluemix to use the service:

1. Sign in to Bluemix.
2. On the dashboard under Applications, click Add an application.
3. On the new page, select Mobile Cloud under Boilerplates.
4. Click Create Application.
5. In the new dialog box, choose the space and give your application a name.
6. Click Create.
7. You are redirected to the Dashboard, where you now see your application. The green status indicator for the new mobile application running in Bluemix indicates that the app moved through the staging process and started.
8. Click on your application. You are redirected to the Applications page, where you can see the application ID and determine which services are bound to the application. The application ID, as shown in the following figure, is required to connect to the Bluemix services. Make a note of the ID.

Familiarize yourself with the Push service

0

 

On the mobile application information page in Bluemix for your new mobile app under Services, see the Push service bound to the application.

Click the Push service.

This Services section is your dashboard for all Push-related issues for your Bluemix app. You can even use this screen to send a test notification to registered devices.

Integrate Bluemix Push in the mobile app

0

 

Now that you have created a Bluemix app and saved the app ID, go back into development mode. Add the Bluemix Push JavaScript APIs to your hybrid mobile application to push messages:

1. Open your hybrid application within your favorite IDE.
2. Point your browser to the index.html page (or main HTML page) within your www directory.
3. Include the following script tag to begin using the npm Push component installed previously.

   <script src="bower_components/ibmpush/js/IBMPush.min.js"></script>

4. Include the JavaScript file to initialize the IBM Mobile Backend as a Service (IBMBaas).

   <script src="bower_components/ibmbaas/js/IBMBaaS.min.js"></script>

5. Initialize the IBMBaas SDK.

   IBMBaaS.initializeSDK(__YOUR_APP_ID__);

6. Before calling any Push commands, initialize the Push service by including the following JavaScript in your application.

   var push = IBMPush.initializeService();

7. Send a test message from within the application by invoking the following JavaScript:

   // Push Notification content
   var message = {
       alert : "Hello Bluemix World",
       url : "https://www.ng.bluemix.net"
   }
   
   // Send the notification
   push.sendBroadcastNotification(message).then(function(response) {
       alert("Push sent!" + JSON.stringify(response));
   },function(err) {
       console.log(err);
   	alert('error sending push message: ' + JSON.stringify(err));
   });

For more complicated Push examples using the IBM Push JavaScript APIs, see the JavaScript API section of the IBM Mobile Cloud Services SDK Developer Guide.

Test the app

0

 

Now you're ready to test the app. If you're using a pure Apache Cordova application, use the command line. For example, I am testing an Android application and using Eclipse to monitor the log output using LogCat.

1. Run the application, for example:

   cordova emulate android

2. You might see the GCM & APNS credentials error message, as shown.
   As the error states, the Bluemix mobile application ismissing GCM & APNS credentials. The Google Cloud Messaging or Apple Push Notification Service credentials (or both) have not been entered for the application in Bluemix. If you receive this error, see Enter Push notification credentials in Bluemix. If you do not see this error, skip to the next step.
3. After any errors are resolved, you will see a Push success message in the LogCat console.
   If you have devices registered with the Push service, you see your message pushed to those devices. To view the list of registered devices, go to the Bluemix console for your application, click on the Push service, and switch to the Registrations tab.

If devices are registered, they are displayed in a table.

With the JavaScript SDK for Bluemix Mobile Backend as a Service Push APIs, it is not possible to register devices to receive Push messages; you must use the Android and iOS native Bluemix SDK.

To register a device with Push to view Push notifications, see "Extend an Android app using the Push cloud service," which includes a complete code example that can be downloaded and installed on your device to test the ability to receive Push messages.

Enter Push notification credentials in Bluemix

0

 

If an error message indicates that the GCM & APNS credentials are missing, follow these steps to correct the problem:

1. Return to the Bluemix dashboard for your mobile application page.
2. Select the Push service to open the Push dashboard.
3. Click the Configuration tab. If no credentials are entered, you see no Push credentials.
4. Click Edit for the Push service you want to enable.
5. If you have your credentials, enter them into the appropriate fields and save. If you do not have credentials and are not sure how to get these credentials, click the informational icon next to the field, as shown.
   The information dialog box includes a link to how to sign up for Push credentials.

   Note: You can enter two different sets of credentials: one for Sandbox and another for Production. It is easy to toggle the service mode between Sandbox and Production when you're ready to switch.

6. After the credentials are saved, you are ready to retest the mobile application by using the previous steps.

Conclusion

0

 

You can now add Bluemix Push capabilities to an existing or new hybrid mobile application using the npm ibmpush module and available JavaScript APIs.