JavaScript client-side API JavaScript Reference: Class WL.Client.Push

Class WL.Client.Push

WL.Client.Push

Description:: IBM® Worklight® provides a number of methods for supported push notification mechanisms. Push notifications are supported on iOS, Android, and Windows Phone 8 devices. SMS push notifications are supported on iOS, Android, Windows Phone 8, and BlackBerry devices that support SMS functions.

Note:: Subscription, and unsubscription, to SMS notifications can also be performed by making HTTP GET requests to the subscribe SMS servlet. The subscribe SMS servlet can be used for SMS subscriptions without the requirement for a user to have an app installed on their device.

Method Summary
Method Attributes	Method Name and Description
	backgroundJobDone(id, result) Complete the background job after receving the silent notification.
	getInteractivePushCategories() A function to return the iOS8 Interactive push notification categories.
	isPushSMSSupported() Checks whether SMS push notifications are supported.
	isPushSupported() Checks whether push notification is supported.
	isSMSSubscribed(alias) Checks whether current user is subscribed to an SMS event source.
	isSubscribed(alias) Checks whether current user is subscribed to an event source.
	isTagSubscribed(tagName) Checks whether the device is subscribed to a tag.
	onMessage(props, payload) A callback function to notify that push notification is arrived.
	onReadyToSubscribe() A callback function to notify that a device is ready to subscribe to push notifications.
	registerEventSourceCallback(alias, adapter, eventSource, callback) Registers a callback method that is called whenever a notification arrives from the specified event source.
	subscribe(alias, options) Subscribe to an event source.
	subscribeSMS(alias, adapterName, eventSource, phoneNumber, options) Subscribe to an SMS event source.
	subscribeTag(tagName, options) Subscribe to a tag.
	unsubscribe(alias, options) Unsubscribe from an event source.
	unsubscribeSMS(alias, options) Unsubscribe from an SMS event source.
	unsubscribeTag(tagName, options) Unsubscribe from a tag.

Method Detail

backgroundJobDone

backgroundJobDone(id, result)

Complete the background job after receving the silent notification. This API is applicable for iOS environment. When the silent notification arrives and the background job is completed, need to call this method to notify that the background job is completed.

Parameters:: id - Mandatory string. The callback-id received as part of notification properties.; result - Optional. The result of background activity. A negative number indicates failure, zero tells no data and positive number tells the data downloaded.

getInteractivePushCategories

getInteractivePushCategories()

A function to return the iOS8 Interactive push notification categories.

Returns:: A JSON Array block that contains the categories

Example:

WL.Client.Push.getInteractivePushCategories = function(){
		var categories = [
                         {
                            //Category identifier, this is used while sending the notification
                            id : "poll",
                            
                            //Optional array of actions to show the action buttons along with the message.
                            actions: [
                                       {
                                            //Action identifier
                                            id : "poll_ok",
                                            
                                            //Action title, to be displayed as part of the notification button  
                                            title : "OK",
                                            
                                            //Optional mode to run the action is foreground or background. 1-foreground. 0-background. 
                                            //Default is foreground.
                                            mode: 1,
                                            
                                            //Optional, To mark the action button in red color. Default is false
                                            destructive: false,
                                            
                                            //Optional, To set if authentication required or not before running the action.(Screen lock). 
                                            //For foreground this is always true.
                                            authenticationRequired: true 
                                         },
                                         {
                                          	id : "poll_nok",
                                             title : "NOK",
                                             mode: 1,
                                             destructive: false,
                                             authenticationRequired: true
                                         }
                                     ],
                             //Optional List of actions need to show in case alert. 
                             //If not specified then the first four actions will be shown
                             defaultContextActions: ['poll_ok','poll_nok'],
                             
                             //Optional List of actions need to show in the notification center, lock screen. 
                             //If not specified then the first two actions will be shown.
                             minimalContextActions: ['poll_ok','poll_nok'] 
                          }
                      ];
    return categories;
};

isPushSMSSupported

isPushSMSSupported()

Checks whether SMS push notifications are supported. Returns true if the IBM® Worklight® JavaScript API supports SMS push notifications in the current environment.

isPushSupported

isPushSupported()

Checks whether push notification is supported. Returns true if the IBM® Worklight® JavaScript API supports push notifications in the current environment.

isSMSSubscribed

isSMSSubscribed(alias)

Checks whether current user is subscribed to an SMS event source. Returns whether the currently logged-in user is subscribed to the SMS event source alias

Parameters:: alias - Mandatory string. The event source alias.

isSubscribed

isSubscribed(alias)

Checks whether current user is subscribed to an event source. Returns whether the currently logged-in user is subscribed to the specified event source alias

Parameters:: alias - Mandatory string. The event source alias.

isTagSubscribed

isTagSubscribed(tagName)

Checks whether the device is subscribed to a tag. Returns whether the device is subscribed to a tag with the given tagName

Parameters:: tagName - Mandatory string. The name of the tag.

onMessage

onMessage(props, payload)

A callback function to notify that push notification is arrived. You must declare it outside any function.

Parameters:: props - A JSON block that contains the notifications properties of the platform.; payload - A JSON block that contains other data that is sent from the IBM Worklight Server. It also contains the tag name for tag and broadcast notification. The tag name appears in the "tag" element. For broadcast notification, default tag name is Push.ALL.

Example:

WL.Client.Push.onMessage= function (props, payload) {
alert("Provider notification data: " + Object.toJSON(props));
alert("Application notification data: " + Object.toJSON(payload));
}

onReadyToSubscribe

onReadyToSubscribe()

A callback function to notify that a device is ready to subscribe to push notifications. You must declare it outside any function.

Example:

WL.Client.Push.onReadyToSubscribe= function () {
// You can enable the Subscribe button here or call WL.Client.Push.subscribe() or WL.Client.Push.subscribeTag()
// This callback is useful in case your app needs to call subscribe() upon startup.
WL.Client.Push.registerEventSourceCallback ('myAlias', 'myAdapter', 'myEventSource', notificationArrived);
}

function notificationArrived(props, payload){
alert("Provider notification data: " + Object.toJSON(props));
alert("Application notification data: " + Object.toJSON(payload));
}

registerEventSourceCallback

registerEventSourceCallback(alias, adapter, eventSource, callback)

Registers a callback method that is called whenever a notification arrives from the specified event source.

iOS and Android: Registers a callback method that is called whenever a notification arrives from the specified event source. If the notification arrives while the application is not running, the mobile OS starts the application at the specified callback.
Windows Phone 8: Registers a callback method that is called whenever a raw notification or a toast notification arrives and the application is running. If the notification arrives when the application is not running, then the callback method is not called. This behavior is defined in the Microsoft OS and cannot be changed.

Parameters:

alias - Mandatory string. A short ID that is used to identify the event source when the push notification arrives. Because notification text is usually limited in length, providing a short alias, rather than the entire adapter and event source names, can free more space in the notification text.

adapter - Mandatory string. The name of the adapter that contains the event source.

eventSource - Mandatory string. The name of the event source.

callback - Mandatory function. The function that is called if a notification arrives. The function receives two parameters when invoked:

props A JSON block, containing the notification properties from the platform.
payload A JSON block, containing other data that is sent from the IBM® Worklight® Server.

subscribe(alias, options)

Subscribe to an event source. Subscribes the user to the event source with the specified alias.

Parameters:: alias - Mandatory string. The event source alias, as defined in the invocation of WL.Client.Push.onReadyToSubscribe .; options - Optional. A standard options object. Custom subscription parameters that are supported by the event source in the adapter can also be included in this options object.

Example:

if (WL.Client.Push.isPushSupported()){ 
WL.Client.Push.subscribe( 'myAlias', {foo: 'bar', onFailure : notificationSubscriptionError});
}

function notificationSubscriptionError(response) {
alert("Error registering for push notifications. " + response.errorMsg);
}

subscribeSMS

subscribeSMS(alias, adapterName, eventSource, phoneNumber, options)

Subscribe to an SMS event source. Subscribes the user to the SMS event source with the specified alias.

Parameters:: alias - Mandatory string. A short ID defining the event source.; adapterName - Mandatory String. The name of the adapter that sets up the event source and communicates with the Worklight® server.; eventSource - Mandatory String. The name of the event source.; phoneNumber - Mandatory string. User phone number to which SMS notifications are sent. The phone number is provided by the user and can contain digits (0-9), plus sign (+), minus sign (-), and space ( ) characters only.; options - Optional. A standard options object. Custom subscription parameters that are supported by the event source in the adapter can also be included in this options object.

Example:

if (WL.Client.Push.isPushSMSSupported()){
	WL.Client.Push.subscribeSMS( “myAlias”,”SMSAdapter”,”SMSEventSource”, “1234567890”,
	{onSuccess: notificationSubscriptionSuccess, 
	onFailure : notificationSubscriptionError
	});
} 

function notificationSubscriptionSuccess(response){
	alert(“Registered for SMS push notification”);
}

function notificationSubscriptionError(response) { 
	alert("Error registering for SMS push notifications. " + response.errMsg); 
}

subscribeTag

subscribeTag(tagName, options)

Subscribe to a tag. Subscribes the device to a tag defined for the application.

Parameters:: tagName - Mandatory string. The name of the tag, as defined in the invocation of WL.Client.Push.onReadyToSubscribe .; options - Optional. A standard options object.

Example:

if (WL.Client.Push.isPushSupported()){ 
WL.Client.Push.subscribeTag( 'Tag1', {onFailure : notificationSubscriptionError});
}

function notificationSubscriptionError(response) {
alert("Error registering for push notifications. " + response.errorMsg);
}

unsubscribe

unsubscribe(alias, options)

Unsubscribe from an event source. Unsubscribes the user from the event source with the specified alias

Parameters:: alias - Mandatory string. The event source alias, as defined in the invocation of WL.Client.Push.onReadyToSubscribe .; options - Optional. A standard options object. Custom subscription parameters that are supported by the event source in the adapter can also be included in this options object.

unsubscribeSMS

unsubscribeSMS(alias, options)

Unsubscribe from an SMS event source. Unsubscribes the user from the SMS event source with the specified alias.

Parameters:: alias - Mandatory string. The alias defined when subscribing.; options - Optional. A standard options object. Custom subscription parameters that are supported by the event source in the adapter can also be included in this options object.

unsubscribeTag

unsubscribeTag(tagName, options)

Unsubscribe from a tag. Unsubscribes the device from the specified tag

Parameters:: tagName - Mandatory string. The name of the tag, as defined in the invocation of WL.Client.Push.onReadyToSubscribe .; options - Optional. A standard options object.