Send a Push notification from a mobile app in 5 minutes or less

25 July 2014
PDF (641 KB)
Share:
Lisa Seacat DeLuca

Lisa Seacat DeLuca

Mobile Software Engineer, IBM Master Inventor

@LisaSeacat

Sign up for IBM Bluemix
This cloud platform is stocked with free services, runtimes, and infrastructure to help you quickly build and deploy your next mobile or web application.

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

 

Create an Apache Cordova project

 

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 Android tools and platform-tools location to your PATH environment variable.
  3. Download ANT and add it to your PATH environment variable.
  4. Ensure that the Java™ path is set in your PATH environment 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 ibmbluemix npm package

 

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 ibmbluemix 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 ibmbluemix 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/bluemixmobilesdk/ibmbluemix-javascript/.git

Install the ibmpush npm package

 

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/bluemixmobilesdk/ibmpush-javascript/.git

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

Image shows successful response for installation of Bluemix ibmpush package

Set up Bluemix

 

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 CREATE AN APP.Screenshot shows Create Application highlighted
  3. On the new page, select Mobile Cloud under Boilerplates. Boilerplate application
  4. Fill out the information and name as shown here:Create an application details
  5. Click CREATE.
  6. 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. Screenshot shows dashboard now showing your app and that it started
  7. Click on your application. You are redirected to the Applications page, where you can see the application ID and application secret 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. Screenshot shows your app's ID shown on the Applications page

Familiarize yourself with the Push service

 

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

Screenshot shows the Services section and 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

 

Now that you have created a Bluemix app and saved the application 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 (ibmbluemix).
    <script src="bower_components/ibmbluemix/js/IBMBluemix.min.js"></script>
  5. Initialize the IBMBluemix SDK.
    var values = {
    	 
    	        applicationId: "____bluemix_appid_________",
    			applicationRoute: "____bluemix_approute_________",		
                applicationSecret: "____bluemix_appsecret_________",
    
    }; 
    IBMBluemix.initialize(values);
  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.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

 

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. Screenshot shows an example of the GCM & APNS credentials error message
    As the error states, the Bluemix mobile application is missing 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. Screen shot shows a success message example
    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

 

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. Screenshot shows the configuration tab page for your applicatin showing no configurations entered
  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. Screenshot shows the info icon that can provide help for entering credentials
    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

 

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


RELATED TOPICS:Mobile Cloud Services communityMobile Cloud blogMobile Web Push

Add a comment

Note: HTML elements are not supported within comments.


1000 characters left

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Mobile development, Cloud computing
ArticleID=974615
ArticleTitle=Send a Push notification from a mobile app in 5 minutes or less
publish-date=07252014