In this training module, the developer will learn about the API and usage of SMS notifications with respect to Hybrid applications.
Topics covered, are:
- What are SMS notifications?
- Device support
- Notification architecture
- Subscription management
- SMS Notification API
- Subscribe SMS servlet
What are SMS notifications?
SMS notification is the ability of a mobile device to receive notifications as SMS messages that are pushed from a server. Notifications are received regardless of whether the application is running.
IBM MobileFirst Platform Foundation supports SMS notifications on iOS, Android, Windows Phone, and BlackBerry devices that support SMS functions.
- Event source: A notification channel to which mobile applications can subscribe.
- User ID: A unique identifier for a MobileFirst user
- Application ID: MobileFirst application ID
-An event source is defined within a MobileFirst adapter.
-A user ID is obtained through authentication or through another unique identifier such as a persistent cookie.
-This ID identifies a specific MobileFirst application on the mobile market.
To start receiving SMS notifications, an application must first subscribe to an SMS notification event source. An event source is declared in the MobileFirst adapter that is used by the application for SMS notification services. To subscribe to SMS notifications, the user supplies a mobile phone number and approves the notification subscription. A subscription request is sent to the MobileFirst Server upon receipt of the user approval.
MobileFirst provides a unified push notification API. With the adapter API, you can:
- Manage subscriptions
- Push and poll notifications from back-end systems
- Send push notifications to devices
With the application API, you can subscribe to, and unsubscribe from, push notification event sources. To send a notification, you must first retrieve it from the back-end system. An event source can either poll notifications from the back-end system, or wait for the back-end system to explicitly push a new notification. When a notification is retrieved by the adapter, it is processed and sent through a preconfigured SMS gateway. Extra custom logic can be added to the adapter to preprocess notifications. The SMS gateway receives the notification and sends it to a device.
1. Notifications are retrieved by the MobileFirst adapter eventsource, by either poll or push from the back-end system.
2. A MobileFirst adapter processes the notification and sends it to an SMS gateway.
3. The SMS gateway sends a push notification to the device.
4. The device processes the push notification as an SMS message.
- User subscription
An entity that contains a user ID, device ID, and event source ID. It represents the intent of the user to receive notifications from a specific event source.
The user subscription for an event source is created when the user subscribes to that event source for the first time from any device.
A user subscription is deleted when the user unsubscribes from that event source from all of their devices.
While the user subscription exists, the MobileFirst Server can produce notifications for the subscribed user. These notifications can be delivered by the adapter code to some or all of the subscribed devices.
A device subscription belongs to a user subscription, and exists in the scope of a specific user and event source. A user subscription can have several device subscriptions. The device subscription is created when the application on a device calls
WL.Client.Push.subscribeSMS API. The mobile phone number is an input parameter. The device subscription is deleted either when an application calls
WL.Client.Push.unsubscribeSMS API, or when the administrator unsubscribes the user through the MobileFirst Console.
SMS Notification API
Start by creating an event source:
- name–name by which the event source is referenced
- onDeviceSubscribe–adapter function that is called when the user subscription request is received
- onDeviceUnsubscribe–adapter function that is called when the user unsubscription request is received
- securityTest–security test from authenticationConfig.xml that is used to protect the event source
- poll–method that is used for notification retrieval, with the following required parameters:
-Interval: polling interval in seconds
-onPoll: polling implementation: an adapter function to be invoked at specified intervals
Send a notification:
Notifications can be either polled from or pushed by the back-end system. In this example, a
sendSMS()adapter function is called by a back-end system as an external API to send notifications.
Retrieve the active user and use it to get the user subscription data.
Obtain notification data: The
sendSMS() method takes the user ID to send the notification to, and the SMS text as arguments.
These arguments are provided by the back-end system that calls this function.
A user subscription object contains the information about all the user subscriptions. Each user subscription can have several device subscriptions. If the user has no subscriptions for the specified event source, a null object is returned.
By using the
getDeviceSubscriptionsAPI, you can obtain separate subscription data for each user device. Send notification to the user devices:
WL.Server.notifyAllDevices API sends notification to all the subscribed user devices.
To send notifications, the following APIs are used:
WL.Server.notifyAllDevices(userSubscription, options): to send notification to all user devices (see previous slide)
WL.Server.notifyDevice(userSubscription, device, options): to send notification to a specific device for a specific user subscription
WL.Server.notifyDeviceSubscription(deviceSubscription, options): to send notification to a specific device
Subscribing or un-subscribing to eventsources can be achieved only upon authenticating first.
WL.Client.Push.subscribeSMS() has the following parameters:
- An alias to identify the subscription
- An adapter name where the event source is defined
- An event source name to which the client is subscribing
- A user mobile phone number where notifications are sent
- Optional onSuccesscallback
- Optional onFailurecallback
WL.Client.Push.unsubscribeSMS has the following parameters:
- An alias -the same as that defined in WL.Client.Push.subscribeSMS
- Optional onSuccesscallback
- Optional onFailurecallback
Callbacks receive a response object if one is required.
Additional client side API:
WL.Client.Push.isPushSMSSupported(): returns true if SMS notifications are supported by the platform, false otherwise.
WL.Client.Push.isSMSSubscribed(alias): returns true if the currently logged-in user is subscribed to a specified event source alias, false otherwise.
Subscribe SMS servlet
Subscribing to SMS notifications can be achieved using a Subscribe SMS servlet. Subscribing to SMS notifications can be achieved without an application on the device, by making HTTP GET calls to the servlet.
The Subscribe SMS servlet supports both subscribe and unsubscribe options. An application and event source within an adapter must be deployed to the MobileFirst Server before making the servlet call.
|option||Optional. The default value is subscribe. For any non-blank string other than subscribe, the unsubscribe action is performed.|
|event source||Mandatory. AdapterName.EventSourceName|
|alias||Optional. A short ID defining the event source name.|
|phone number||Mandatory. The number to which the SMS notifications are sent.|
|user name||Optional. If no value is provided, the phone number is used as the user name.|
|app ID||Mandatory. The ID of the application that contains SMS gateway definition. For exampe: SMSPushApp-android-1.0.|
Subscriptions that are made by using the Subscribe SMS servlet are independent of subscriptions that are created from a device. Unsubscribing by using SMS servlet does not remove subscriptions that are made from device.
By default, the Subscribe SMS servlet is protected as a static resource. By default, the authenticationConfig.xml file is configured to reject all requests to the Subscribe SMS servlet by using a rejecting login module. To allow access to the Subscribe SMS servlet, an administrator must modify the authenticationConfig.xml file with appropriate authenticator and login modules.
By default, authenticationConfig.xml is configured to reject all requests to the Subscribe SMS servlet:
An administrator can change authenticationConfig.xml to allow access to the Subscribe SMS servlet:
To send SMS notifications, define in the SMSConfig.xml file the third-party gateway services that are supported by the MobileFirst Server.
For an application to use SMS notifications, specify the SMS gateway to use by adding an
The gateway ID in the SMSConfig.xml file must correspond to the SMS gateway ID in the application-descriptor.xml file.
The sample for this training module comes with a back-end system emulator that you can use to simulate SMS notification submission by a back-end system.
To run the back-end system emulator:
1. Open a command prompt.
2. Go to the SMSBackendEmulatorfolder of the sample project.
3. Enter the following command to run the supplied SMSBackendEmulator.jar file:
java –jar SMSBackendEmulator.jar
where 'userID' is the user name that you used to log into the sample application.
The back-end system emulator tries to connect to a MobileFirst Server and call the sendSMS()adapter procedure. It then produces the invocation result to a command prompt console.▲