| Oracle® Communications WebRTC Session Controller Web Application Developer's Guide Release 7.0 E40978-01 |
|
|
PDF · Mobi · ePub |
| Oracle® Communications WebRTC Session Controller Web Application Developer's Guide Release 7.0 E40978-01 |
|
|
PDF · Mobi · ePub |
This chapter shows how you can use the Oracle Communications WebRTC Session Controller JavaScript application programming interface (API) library to enable your application users to subscribe to and receive message alert notifications from your applications.
Note:
See WebRTC Session Controller JavaScript API Reference for more information on the individual WebRTC Session Controller JavaScript API classes.Message alert notifications consist of text, pager, fax, voice, and multimedia message notifications that are useful ways to enable users to access and retrieve such communication at a later time. These messages could be stored on designated message servers for a configurable time to be accessed by the respective recipients.
You can use WebRTC Session Controller JavaScript API to enable your application users to subscribe to notifications.
Note:
The web user interface aspects required to enable the user to subscribe to or to retrieve notifications are beyond the scope of this document.
All other aspects of a stored message service system such as creating the message, storing it, accessing the message server, retrieving the message, and forwarding, storing or destroying the message are dependent on the environment where your application is deployed.
To handle message alert notifications, the logic in your application must accomplish the following tasks:
Enable a user to subscribe to receiving notifications.
To do so, in your application:
Provide the interface elements necessary for the user to specify the service target.
Set up the subscription when the service target is received from the subscriber.
Enable the user to access and process the received notifications.
To do so, in your application:
Set up the elements necessary to receive the incoming notification.
Process the information and display it for the user.
Set up the logic to respond to the user's actions on the subscriptions.
Respond to the end of a subscription resulting from the following events:
The user stops the current subscription to notifications.
The provider of the notification ends the notifications to this subscriber. The WebRTC Session Controller JavaScript API library invokes the event handler which indicates to your application that the subscription has ended.
In addition to the general WebRTC Session Controller JavaScript API objects, the following API objects are used to manage message alert notifications in your applications:
wsc.MessageAlertPackage to enable message alert notifications. See "Managing Message Alert Notifications with wsc.MessageAlertPackage".
wsc.Notification to manage notifications. See "Handling Notifications with wsc.Notification".
wsc.Subscription to manage subscriptions. See "Subscribing to Notifications with wsc.Subscription".
wsc.MessageSummary to obtain message summary information. See "Getting Message Summary Information".
wsc.MessageCounts to obtain the number of messages by the type of message. See "Retrieving Message Counts from Message-Summary Notifications".
See "Extending Your Applications Using WebRTC Session Controller JavaScript API" for information on extending these objects.
Manage messaging alert notifications for pending voice mails, fax messages, and so on during the specified session with an instance of the wsc.MessageAlertPackage class. This object enables message alert notification applications. Use it to create new subscriptions for notifications, manage active subscriptions, and handle received message notifications. When you use wsc.MessageAlertPackage, the WebRTC Session Controller JavaScript API library handles the messaging flow for the notifications.
Create an instance of wsc.MessageAlertPackage, such as messageAlertPackage, using your application's Session object. You can create an array of subscriptions in your application and use the messageAlertPackage object to manage the user's alert and message notifications for each subscription.
If the web page reloads, set up the logic to restore failed subscriptions. To do so, assign a callback function to your application's MessageAlertPackage.onResurrect event handler. The WebRTC Session Controller JavaScript API library provides the rehydrated subscription data as a parameter to the callback function assigned to your application's MessageAlertPackage.onResurrect event handler.
See "Extending and Overriding WebRTC Session Controller JavaScript API Object Methods" for more information on extending the MessageAlertPackage API.
Use the wsc.Notification class to obtain the information associated with a notification, such as the identity of the sender, the content of the notification, and the identity of the receiver.
If your application receives a message notification for a subscription, the WebRTC Session Controller JavaScript API library provides the notification when it invokes the onNotification event handler for your application's Subscription object.
Inspect the incoming notification in the callback function you assigned to your application's Subscription.onNotification event handler to process the information using:
The wsc.MessageSummary class, derived from the wsc.Notification class.
It holds the message summary of the incoming notification.
The wsc.MessageCounts class which holds the number of new and old messages retrieved from the message summary, grouped as regular or urgent.
You can retrieve the following information:
The number of a specific type of message, such as the number of new and/or old voice message messages in your application's MessageSummary object.
To retrieve the number of a specific type of message, call the getMessageCounts method of your application's MessageSummary object and input the type of message as msgClassType.
The message content in the incoming notification, by using the getContent method of your application's Notification object. The message content is returned as a JavaScript Object Notation (JSON) object.
The identity of the receiver of the incoming notification, by using the getReceiver method of your application's Notification object.
The identity of the sender of the incoming notification, by using the getSender method of your application's Notification object.
The wsc.Subscription class can be used to enable your application users to subscribe to notifications.
When your application user provides the service target such as voice_mail@example.com, you can create a Subscription object (for example, subscription) using the MessageAlertPackage.createNewSubscription method. The service target voice_mail@example.com represents a service in the telecommunication network that can send message alert notifications for such a subscription. Note that, WebRTC Session Controller must be configured in order to route the subscription requests to such a service.
Manage subscriptions by providing logic for the following:
The Subscription.onNotification event handler
Assign and set up the callback function for your application's Subscription.onNotification event handler to handle incoming message notifications for the current subscription.
The Subscription.onEnd event handler
Assign and set up the callback function for your application's Subscription.onEnd event handler to handle the end message for a subscription.
The validity of a subscription
Use the Subscription.isValid method to check and take action based on the validity of the current subscription.
The ending of the current subscription
Use the Subscription.end method to stop the current subscription and end message notifications for it.
The wsc.MessageSummary class is extended from wsc.Notification. When the WebRTC Session Controller JavaScript API library receives a notification whose event type is message-summary, the MessageAlertPackage API creates an instance of the MessageSummary object. It provides the MessageSummary object as input to the callback function you assigned to your application's Subscription.onNotification event handler.
In the callback function, you can use the following methods:
MessageSummary.getMessageAccount
Use the MessageSummary.getMessageAccount method to retrieve the message account for the current message summary notification in a String format.
MessageSummary.getMessageCounts(msgClassType)
where msgClassType represents the message class type. The count of the number of msgClassType messages is returned to your application in an instance of the wsc.MessageCounts object. Use the methods of wsc.MessageCounts to get more details on the notification.
For example, input the string "voice_message" or "fax_summary" to retrieve the count of the number of voice or fax messages for this subscription. This message class type corresponds to the Session Initiation Protocol (SIP) notification message class type.
MessageSummary.isMessageWaiting
If there is a message waiting in the incoming notification, the MessageSummary.isMessageWaiting method returns the boolean value true.
The wsc.MessageCounts class contains the number of msgClassType messages in a message-summary type of notification.
To obtain the message count when your application receives a message-summary notification as a MessageSummary object (for example, msgSummary, do the following in your application:
Retrieve the message count by invoking the MessageSummary.getMessageCounts method.
This method returns the message counts as an instance of wsc.MessageCounts, for example, msgCounts.
Retrieve the messages by age and urgency. Use:
MessageCounts.getUrgentNew to retrieve the urgent messages that are new
MessageCounts.getNew to retrieve the normal messages that are new
MessageCounts.getUrgentOld to retrieve the urgent messages that are old
MessageCounts.getOld to retrieve the normal messages that are old
Provide the information to the user as required.
In Example 7-1, an application uses a callback function called onNotify to process an incoming notification called incomingNotification. If the instance of the MessageCounts object retrieved from incomingNotification is not null, the function retrieves the number of normal and urgent messages that are new in newnormal and newurgent.
Example 7-1 Obtaining Number of Messages by Type
function onNotify(incomingNotification) { var msgCount = incomingNotification.getMessageCounts("voice_message"); if(msgCount != null){ // Deal with the New and Old normal and Urgent messages var newurgent = msgCount.getNewUrgent(); var newnormal = msgCount.getNew(); ... }; }
The application in the above example can then update the display for the device for example, update the audio or visual display for the message-waiting indicator on the browser page.
Managing user subscriptions to notifications in your applications consists of the following tasks:
To enable your application user to subscribe to notifications:
Set up your application's message alert notification package using your application's session. In the following example, an application sets up a message alert notification package called MsgAlertHandler with reference its application session, wscSession.
MsgAlertHandler = new wsc.MessageAlertPackage(wscSession);
Set up the interface for the user to enter the information on the service target.
Define the logic in the callback functions to respond to the user's actions.
To implement the logic to support subscriptions, your application needs to create a subscription when the user enters a target for a subscription service. The target could be for an identity of a service or an account. It should be in the format user@domain. WebRTC Session Controller adds sip: to the target from a web subscribe user (for example, sip:user@domain), if that target is determined to be a SIP notification application. Your application can then notify the user whenever there is a change in the message status for the account.
Use the MessageAlertPackage.createNewSubscription method to create a new subscription. The syntax for the method is:
createNewSubscription(target, subscriber, onSuccess, onError, onNotification, onEnd, extheaders)
Where:
target is the service target you obtained from the user, the device or the service the user wishes to monitor.
subscriber is the user identity of this subscriber.
onSuccess is the event handler called when the application creates the subscription.
onError is the event handler called when the application fails to create the subscription.
onNotification is the event handler for a notify message.
onEnd is the event handler called when the provider of the notification notifies Signaling Engine that this subscription has ended.
extHeaders is extension header. Extension headers are inserted into the JSON message.
Example 7-2 Creating a Subscription
// Create a message alert package.
msgAlertHandler = new wsc.MessageAlertPackage(wscSession);
...
// Create a new subscription for this target.
subscription = msgAlertHandler.createNewSubscription(target,
userIdentity,onSubscribeSuccess,onSubscribeError,onNotify,onEnd);
// Assign the onNotification event handler for the subscription.
subscription.onNotification = onNotify;
...
If the application user subscribes to notifications from multiple targets such as phones and voice mail storage devices, set up the subscriptions and store the information on the service targets accordingly. Implement the logic to verify and deliver the incoming notification to the appropriate subscription.
You can optionally include extension headers as the last parameter extHeaders when you invoke the MessageAlertPackage.createNewSubscription method shown in Example 7-2. The extHeaders you input must be in JSON format to be inserted in the outgoing message. Here is an example of an extension header:
{'customerKey1':'value1','customerKey2':'value2'}
When you include the extension header as the last parameter in the MessageAlertPackage.createNewSubscription method, it is placed in the header section of the message in the following way:
{ "control" : {}, "header" : {...,'customerKey1':'value1','customerKey2':'value2'}, "payload" : {}}
Set up the functions to handle the following scenarios:
The user ends the current subscription.
Use the Subscription.end method to stop the current subscription. If your application uses extension headers, input them when you call this method.
The WebRTC Session Controller JavaScript API library invokes the Subscription.onEnd event handler in your application.
The WebRTC Session Controller JavaScript API library invokes this event handler when it is notified about the end of that specific subscription for the user. Assign a callback function to the Subscription.onEnd event handler. Set up the logic within this function to inform the user appropriately and take action accordingly.
When a subscription has been recovered, the WebRTC Session Controller JavaScript API library invokes your application's MessageAlertPackage.onResurrect event handler with the rehydrated subscription as the parameter. Your application can call the Subscription.isValid method and take further action. If the user prefers to end the subscription, use the Subscription.end method.
Important:
If you create a custom message alert package, be sure to implement the appropriate logic to resume your application operation and restore subscription operations.In Example 7-3, an application resets the callback functions to the rehydrated subscription object and proceeds with its actions.
Example 7-3 Sample onResurrect Function for a Subscription
subscribeHandler = new wsc.MessageAlertPackage(wscSession);
if (subscribeHandler) {
subscribeHandler.onResurrect = onResurrect;
}
...
function onResurrect(rehydratedSubscription) {
...
// Reset related callback functions
subscription = rehydratedSubscription;
subscription.onSuccess = onSubscribeSuccess;
subscription.onError = onSubscribeError;
subscription.onNotification = onNotification;
subscription.onShutdown = onShutdown;
// Initialize other parts of the application, such as page
...
}
Your application needs to set up the logic required to support the message alert notifications for the event types that must be supported in the environment in which your application is deployed.
In order to do so, implement and extend the wsc.Notification class to handle the notifications for the required event types. Process the incoming notification to update the information on the message counts (for example, how many new and old) and process it to identify the identity of the person or service providing the notification and subscriber of the service and take action accordingly.
To handle an incoming notification that is not a message summary, set up the callback function to retrieve the message content and the identities of the sender and receiver:
Notification.getContent
Use the Notification.getContent method to retrieve the contents of the notification as a JSON object.
Notification.getSender
Use the Notification.getSender method to retrieve the identity of the sender (service) of the notification as a string object.
Notification.getReceiver
Use the Notification.getRetriever method to retrieve the identity of the receiver of the notification as a string object.
Set up the logic to retrieve handle the information as necessary.
See "Handling Custom Message Notifications" for information on how to handle custom message notifications in your web applications.
|
 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|