IBM Cloud Push Notifications Web SDK

The IBM Cloud Push Notifications service provides a unified push service to send real-time notifications to mobile and web applications. The SDK enables Safari, Chrome, Firefox browsers and Chrome Apps & Extensions to receive push notifications sent from the service.

Ensure that you go through IBM Cloud Push Notifications service documentation before you start.

Prerequisites
Installation
Initialize SDK
- Initialize client Push SDK
- Initialize web Push SDK
Register for notifications
- Unregistering from notifications
Push Notifications service tags
Parameterize Push Notifications
Samples and videos

Prerequisites

Firefox 49.0 or later
Chrome 54.0 or later
Safari 9.1 or later

Installation

Download the Push Notifications Web Client SDK package.

Initialize SDK

Complete the following steps to initialize the SDK.

Initialize client Push SDK

Complete the following steps:

Ensure that you go through service configuration before starting the client configuration.

Choose any of the following options, based on your browser:

Chrome and Firefox web browsers

Ensure that you go through service configuration before starting the client configuration. To install the Javascript SDK in Chrome and Firefox, complete the following steps:
1. Add the BMSPushSDK.js,BMSPushServiceWorker.js and manifest_Website.json files to your project root folder.
2. Edit the manifest_Website.json file.
  - For Chrome browser:
```
{
	"name": "YOUR_WEBSITE_NAME",
	"gcm_sender_id": "GCM_Sender_Id"
}
```
    Change the name to your website's name and update the gcm_sender_id to your Firebase Cloud Messaging (FCM) [sender ID] (https://cloud.ibm.com/docs/services/mobilepush/push_step_1.html#push_step_1_android). Note that the gcm_sender_id value contains only numbers.
    
    Note: gcm_sender_id is not required if you are using the applicationServerKey in BMS push init method.
  - For Firefox browser, add the following values in manifest_Website.json file.
```
{
"name": "YOUR_WEBSITE_NAME"
}
```
    Change name to your website's name.
3. Change the manifest_Website.json file name to manifest.json.
4. Include the manifest.json in <head> tag of your html file .
```
 <link rel="manifest" href="manifest.json">
```
5. Include IBM Cloud Web push SDK to the script ,
```
<script src="BMSPushSDK.js" async></script>
```
Safari web browsers

For Safari web browsers, add the BMSPushSDK.js in the html file: HTML <script src="BMSPushSDK.js" async></script>
Chrome Apps

For installing the Javascript SDK in Chrome Apps, complete the following steps:
1. Add the BMSPushSDK.js and manifest_Chrome_App.json .
2. Configure the manifest file:
  1. For Chrome App in the manifest_Chrome_App.json file provide name, description , and icons.
  2. Add the BMSPushSDK.js in the app.background.scripts.
  3. Change the manifest_Chrome_App.json to manifest.json.
3. In your Javascript file (background.js), add the following to receive push notifications:
```
chrome.gcm.onMessage.addListener(BMSPushBackground.onMessageReceived)chrome.notifications.onClicked.addListener(BMSPushBackground.notification_onClicked);
 chrome.notifications.onButtonClicked.addListener(BMSPushBackground.notifiation_buttonClicked);
```
Chrome Extensions

Add the BMSPushSDK.js and manifest_Chrome_Ext.json .
1. Configure the manifest file:
  - For Chrome Extensions in the manifest_Chrome_Ext.json file, provide name, description , and icons.
  - Add the BMSPushSDK.js in the background.scripts.
  - Change the manifest_Chrome_Ext.json to manifest.json.
2. In your Javascript file, add the following to receive notifications:
```
chrome.gcm.onMessage.addListener(BMSPushBackground.onMessageReceived)
chrome.notifications.onClicked.addListener(BMSPushBackground.notification_onClicked);
chrome.notifications.onButtonClicked.addListener(BMSPushBackground.notifiation_buttonClicked);
```

Initialize web Push SDK

Initialise the web push SDK with IBM Cloud Push Notifications service app GUID,clientSecret,websitePushIDSafari,deviceId and app Region.

var bmsPush = new BMSPush()
function callback(response) {
	alert(response.response)
}
var initParams = {
    "appGUID":"push app GUID",
    "appRegion":"Region where service hosted",
    "clientSecret":"push app client secret", // optional parameter. This value is needed for userId based notifications registration.
	"websitePushIDSafari": "website Push ID for safari" // Optional parameter for Safari web push,
    "deviceId":"Optional deviceId for device registration"
}
bmsPush.initialize(params, callback)

The App Region specifies the location where the Push service is hosted. You can use one of the following three values:

For US Dallas - .ng.bluemix.net
For UK - .eu-gb.bluemix.net
For Sydney - .au-syd.bluemix.net
For Germany - .eu-de.bluemix.net
For US East - .us-east.bluemix.net
For Tokyo - .jp-tok.bluemix.net

Note:For debugging, use bmsPush.isDebugEnable(true).

Register for notifications

Use the register() or registerWithUserId() API to register the device with IBM Cloud Push Notifications service. Choose either of the following options:

To register without userId use the following pattern

var bmsPush = new BMSPush()
function callback(response) {
	alert(response.response)
}
var initParams = {
	"appGUID":"push app GUID",
	"appRegion":"Region where service hosted",
	"clientSecret":"push app client secret"
}
bmsPush.initialize(initParams, callback)
bmsPush.register(function(response) {
	alert(response.response)
})

For UserId based registration, use the following code snippet,

var bmsPush = new BMSPush()
function callback(response) {
	alert(response.response)
}	
var initParams = {
	"appGUID":"push app GUID",
	"appRegion":"Region where service hosted",
	"clientSecret":"push app client secret"
}
bmsPush.initialize(initParams, callback)
  bmsPush.registerWithUserId("your UserId",function(response) {
	alert(response.response)
})

WithUserId is the user identifier value with which you want to register devices in the push service instance.

Note: If userId is provided, the client secret value must be provided.

Unregistering from notifications

To unregister from receiving notifications, add the following unRegisterDevice() method:
```
bmsPush.unRegisterDevice(function(response) {
	alert(response.response)
}
```
To unregister the device from UserId based registration, you have to call the registration method. See the Register without userId option in Register for notifications.

Push Notifications service tags

Retrieve available tags

To retrieve all the available tags, use the retrieveAvailableTags() method.

 bmsPush.retrieveAvailableTags(function(response) { //Retrieve available tags
   var jsonResponse = JSON.parse(response.response)
   var tagsArray = []
   for (i in jsonResponse.tags){
     tagsArray.push(jsonResponse.tags[i].name)
   }
   alert(tagsArray)
 })

Subscribe to tags

The subscribe() API will subscribe the web application for a list of given tags. After the device is subscribed to a particular tag, the device can receive push notifications that are targeted to an audience who have subscribed to that tag.

Use the following code snippet in your application to subscribe a list of tags.

bmsPush.subscribe(tagsArray,function(response) {
  alert(response.response)
})

Retrieve subscribed tags

The retrieveSubscriptions API will return the list of tags to which a website is subscribed.

Use the following code snippet in your application to get a subscription list.

bmsPush.retrieveSubscriptions(function(response){
   alert(response.response);
})

Unsubscribing from tags

To unsubscribe to a tag or tags, use the unSubscribe() method. Pass the array of tag names as parameter.

bmsPush.unSubscribe(tagsArray,function(response) {
	alert(response.response)
}

Parameterize Push Notifications

Add the variables in the Push initialize params values.

var templateValues = {
  "userName":"testname",
  "accountNumber":"3564758697057869"
}

var initParams = {
  "appGUID":"push app GUID",
  "appRegion":"Region where service hosted",
  "clientSecret":"push app client secret",
  "pushVaribales":templateValues
}

bmsPush.initialize(initParams, callback)

While registering the device IBM Cloud Push Notifications Web SDK will pass these variables to IBM Cloud Push Notifications service.

While sending push notification add the varibale key in {{}}


  {
      "message": {
          "alert": "hello {{username}} , balance on your account {{accountNumber}} is $1200"
      }
  }

Samples and videos

For samples, visit - Github Sample
For video tutorials visit - IBM Cloud Push Notifications

Learning more

Visit the IBM Cloud Developers Community.
Getting started with IBM MobileFirst Platform for iOS

Connect with IBM Cloud

Twitter | YouTube | Blog | Facebook |

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Home