Oracle® Communications WebRTC Session Controller Web Application Developer's Guide Release 7.0 E40978-01 |
|
|
PDF · Mobi · ePub |
This chapter describes how you can extend the Oracle Communications WebRTC Session Controller JavaScript application programming interface (API) library.
Note:
See WebRTC Session Controller JavaScript API Reference for more information on the individual WebRTC Session Controller JavaScript API classes.When your application needs to perform an action such as creating a session, a call or message alert package, starting a call or responding to a notification, it sends a JavaScript message associated with that action to the WebRTC Session Controller JavaScript API library. For its part, the WebRTC Session Controller JavaScript API library converts these messages (for example, Call.start) into signaling messages using a protocol based on JavaScript Object Notation (JSON). For more information, see WebRTC Session Controller Extension Developer's Guide.
The WebRTC Session Controller JavaScript API library contains classes and methods that have a default behavior and others that can be extended. When you use the default classes and methods, the WebRTC Session Controller JavaScript API library handles all of the signaling messages for all the resulting default commands.
When you need to broaden or extend your application logic, you may need to extend the JavaScript message sent by your application. To do so, use those objects and methods in the WebRTC Session Controller JavaScript API that are extensible.
Your applications can support additional communication-related services in audio, video, and data transfer flows. For example:
Custom calls
In order to handle custom call flows you can implement logic to prepare the calls, setting up the logic to accept prepared calls, and manage the sequence of messages associated with the prepared calls.
Custom packages
To support custom services in calls of custom call flows, your application may need to extend the application session.
The WebRTC Session Controller JavaScript API library provides the following objects and functions for this purpose:
wsc.extend. See "Extending Objects Using the wsc.extend Method".
wsc.ExtensibleSession. See "Extending Sessions with wsc.ExtensibleSession Class".
Other extensible methods. See "Extending and Overriding WebRTC Session Controller JavaScript API Object Methods".
Note:
WebRTC Session Controller JavaScript API Reference uses the term "For extensibility" to identify such extensible objects and methods.The wsc.extend method is a utility you use when you wish to extend a WebRTC Session Controller JavaScript API class object exposed through wsc namespace. The wsc.extend method takes two parameters, child and parent, in that order. The syntax is:
wsc.extend(child, parent);
When you call the wsc.extend method, the constructor of the child object calls the constructor of the parent. All the members that are attached to the prototype object of the parent entry are copied to the prototype object of the child entry. The objects initialized in the parent's constructor code become available and the child can now make use of the objects in the parent class object. You can then override any function in the child object without impacting the parent.
The code sample in Example 8-1 creates the wsc.CallExtension object which extends the wsc.Call object.
Example 8-1 Creating CallExtension from the Call Object
function CallExtension() { //chain constructor CallExtension.superclass.constructor.apply(this, arguments) } //The following statement makes the CallExtension object a child of wsc.Call wsc.extend(CallExtension, wsc.Call);
At this point, the inherited members of CallExtension can be overridden without affecting the corresponding members in the parent Call object.
See "Working with Extended Calls" for a description of how the onMessage function is overridden in this newly-created CallExtension class object.
The wsc.ExtensibleSession class object provides many critical functions required to extend packages. Use the methods in wsc.ExtensibleSession to access and retrieve information about a subsession using its identifier (sessionId), retrieve a specific package by its type and manage it, and configure custom packages in your application to handle specific set of tasks. See "Creating Custom Packages Using the ExtensibleSession Object".
You can override and extend methods in WebRTC Session Controller JavaScript API objects to do the following:
If your application logic uses extended call sessions, set up the required actions in a callback function for the application's CallPackage.onMessage event handler. When call-related messages come in to your application, this callback function will be invoked enabling you to inspect the incoming message and take further action on the call.
When you extend the CallPackage object, you can override the CallPackage.onMessage event handler. See "Extending Objects Using the wsc.extend Method" for more information.
By default, your application's Call object is created with reference to the default Session object.
The CallPackage.prepareCall method is a Service Provider interface function which prepares a call with reference to a session. For example:
mycall = callPackage.prepareCall(mysession,CallConfig, caller, callee);
Here, an application has set up the caller, callee, and callConfig objects and uses the CallPackage.prepareCall method to prepare a call called mycall with reference to a specific session, mysession.
Use the CallPackage.putCall method to place a prepared call object in a specific point in the flow for that call session. To do so, you need:
The subsession Id (id) for the call session
The prepared call object.
You can now place the call with the following statement:
putCall(id, call);
Process custom message content that your application receives for the current call by using the Call.onMessage method. Extend the Call object to do so. See "Working with Extended Calls".
When you use an extension header in a call session, set up the extension header in the following JavaScript format:
{'label1':'value1','label2':'value2'}
Place the extension header as the last parameter when you invoke the methods that support extension headers. See "Handling Additional Headers" for the complete of objects and methods that support extension headers.
If the received notification message is not a message summary, your application receives a wsc.Notification object as the parameter to its Subscription.onNotification event handler.
In the callback function you assign to your application's Subscription.onNotification event handler, use this incoming notification to instantiate an extended wsc.Notification class object. Use the methods of the extended class object to parse the supported types of notification messages.
If your application's MessageAlertPackage object manages an array of subscriptions, then, when a notification comes to your application, the MessageAlertPackage.onMessage event handler is invoked. In the callback function you assign to this event handler, you can process the incoming message notification to identify the subscription object and invoke the appropriate Subscription.onNotification event handler for further processing of that notification.
The MessageAlertPackage.onMessage function can be overridden to handle custom message events. See "Working with Extended CallPackage Objects".
Your application may need to allow users to send or receive additional data in the form of an extra header field.
Some methods in the Call and CallPackage class objects can accept an additional argument, as long as it is a JSON object. This additional data is sent as an extension header in the message and received as an extra parameter by the event handler of the incoming call.
For example, when a user navigates your application page designed for an auto dealership, your application may have gathered data on the user's preferences for the make, model, and deal preferences, such as carMaker, Convertible), and Lease.
When the user calls the dealership from your page, your application can pass this information to the dealer in the call. Your application sets up this information as a JSON object.
{'custprefKey1':'BMW','custprefKey2':'Convertible', 'custprefKey2':'Lease'}
This JSON object is now sent in the message as:
{ "control" : {}, "header" : {'custprefKey1':'BMW','custprefKey2':'Convertible', 'custprefKey2':'Lease'}, "payload" : {}, }
At the dealership, when the dealer receives the call, the appropriate function is invoked with the extra information as the last argument, for example,
callObj.accept(callConfig, null, extheader);
In that function, your application takes this extheader JSON object, retrieves the information and takes the actions necessary to display the information for the dealer's use.
The WebRTC Session Controller JavaScript API library supports extension headers as the parameter in the following:
Call Methods:
Call.accept
Call.decline
Call.end
Call.start
Call.update
Event Handlers:
CallPackage.onIncomingCall
Call.onCallStateChange
Call.onUpdate
See the discussion on customizing messages for new Session Initialization Protocol (SIP) or JSON data in WebRTC Session Controller Extension Developer's Guide.
The Call API object can be used to send or receive an extension header in its call flow.
For your application to start a call with extension headers:
Set up the extension header as a JSON object.
Place the JSON object as the last parameter when your application invokes the outgoing call object's start method to start the call.
For example, if call is the call object, lmedstrm is the local media stream object, and extHeader is the extension header in your application, use the following statement to start the call:
call.start(lmedstrm,extHeader)
When your application receives a request for a call with extension headers:
Retrieve the extension header from your application's CallPackage.onIncomingCall event handler. The extension header is in JSON format.
Perform any actions based on the additional data in the extension header.
If the application user accepts the call, do the following:
Set up the extension header as a JSON object.
Include the JSON object when your application invokes the outgoing call object's start method to start the call.
For example, if call is the call object, callConfig the local media stream and data transfer capability for calls, lmedstrm is the local media stream object, and extHeader is the extension header in your application, use the following statement to accept the call:
call.accept(callConfig, lmedstrm, extHeader)
If the application user declines the call, do the following:
Obtain the reason the call was declined by the user.
Set up the extension header as a JSON object.
Include the JSON object when your application invokes the outgoing call object's decline method.
For example, if extCall is the extended call object, reason the reason the call was declined, and extHeader is the extension header:
extCall.decline(reason,extHeader)
Whether your application user is the caller or the callee, your application may need to handle incoming messages and set up outgoing messages associated with the following events. In each case, set up the extension header as described and place it as the last parameter when you invoke the associated function for the extended call.
Your application user ends the call.
Set up the extension header as described earlier and include it when you invoke the end method for the extended call.
The call is updated.
If your application user:
Requests the update.
Set up the extension header as described earlier and include it when you invoke the update method for the extended call.
Receives the update request.
Process any data in the extension header in the onUpdate event handler. Set up the extension header as described earlier and include it when you invoke the accept or decline method of the extended call object, as appropriate.
The call state changes.
Process any data in the extension header in the Call.onCallStateChange event handler. Set up the additional data as the extension header in the method for the outgoing call.
Your applications can use custom session objects to enable users to subscribe to the presence of other users, chat with SIP users, or set up calls that can be transferred to other users. Configure and manage custom flows in your applications by using the wsc.ExtendedSession object.
To create an extensible session, use the syntax:
wsc.ExtensibleSession(useName, webSocketUri, successCallback, failureCallback, sessionId)
Where:
useName, is the user name.
webSocketUri, the predefined web socket connection.
successCallback, the function to call if the session object was created successfully.
failureCallback, the function to call if the session object was not created.
sessionId, if you are refreshing an existing session.
You can create custom packages in your application to handle specific set of tasks and expand the scope of your application. To add custom packages, your application needs to use the following objects:
The ExtensibleSession:
Use this object to do one or more of the following
Creating an extended session object using the ExtensibleSession method of wsc.
Retrieving all sub-sessions by using the getAllSubSessions method of your application's ExtensibleSession object.
Saving session data to the web browser's sessionStorage by using the saveToStorage method of your application's ExtensibleSession object.
For more information on subsessions, see Oracle Communications WebRTC Session Controller JavaScript Extension Developer's Guide.
The custom package object in the session:
Set up this object by doing the following:
Creating the custom package object.
Registering the package by using the registerPackage method of your application's ExtensibleSession object.
Retrieving the package by its type by using the getPackage method of your application's ExtensibleSession object.
The message object that the custom package sends or receives:
Manage the message object by doing the following:
Defining the message object with wsc.Message
Sending the message using the sendMessage method of your application's ExtensibleSession object.
Handling an incoming message using the Call.onMessage method in your application's ExtensibleSession object.
Generating a correlation ID for the message using the genNewCorrelationId method of your application's ExtensibleSession object.
The generated correlation ID is based on the current outbound sequence number sequence of this session. For information on sequence, see WebRTC Session Controller Extensions Developer Guide.
The message flow as required by the requirements of the extended session. See "Sending And Receiving Custom Messages".
The subsession of the ExtensibleSession by:
Retrieving the session Id of the subsession using getSubSessionId of your application's ExtensibleSession object.
Retrieving all subsessions that belong to a specific package using getSubSessionsByPackageType method of your application's ExtensibleSession object.
Placing a subsession object into the session with putSubSession method of your application's ExtensibleSession object.
Removing subsession object giving its id using removeSubSession method of your application's ExtensibleSession object.
When you create applications using the default or custom behavior of WebRTC Session Controller JavaScript API, the library automatically saves the data for the sessions.
If you need your application to handle the data associated with custom sessions or subsessions, save the corresponding data in the HTML SessionStorage area using the ExtensibleSession.saveToStorage method. Your session data should be stored in JSON format. Ensure that your application saves the session data such that it captures the changes so as to maintain the session's current state for use in dealing with connectivity issues.
Important:
When your application uses a custom package and/or subsession object save the subsession's state to support rehydration. Monitor the change in the subsession's state and call your application's ExtensibleSession.saveToStorage() method to save the data.When you create messages independent of the default call or message alert package, you need to set up logic to handle the flow of such messages and the resulting actions your application needs to take.
You can send custom messages within a sub-session by providing a Message object as an argument when you call your application's ExtensibleSession#sendMessage method. Ensure that your application's Message object has the control, header, and payload blocks. For example, to send INFO messages as part of an ongoing call, your application can extend its Call and CallPackage objects and use them to support sending and receiving INFO messages while delegating all other functionality to the existing Call and CallPackage. See the discussion on extension points in WebRTC Session Controller JavaScript API Reference.
At times, you may need to create you create custom packages and use custom message flows in your applications. Use the following:
Note:
For information on the wsc.Map utility you can use when you set up custom messages, see Oracle Communications WebRTC Session Controller JavaScript API Reference.The wsc.Message class object encapsulates a message and contains two sections of headers and the payload, if necessary. All messages between your application and WebRTC Session Controller are sent in this format. Create the control header, general header and the payload sections of message object in your application. Example 8-2 shows the header sections of a message object which initiates a WebSocket connection:
Example 8-2 The Header Sections of a Message Object
{ "control": { "type":"request", "sequence":"1", "version":"1.0" }, "header": { "action":"connect", "initiator":"bob@someCompany.com", } }
Note:
When you need to create messages independent of the default call or message alert package, use the wsc.Message object and manage the messaging workflow using the wsc.ExtensibleSession object. See "Working with wsc.ExtensibleSession".Use the wsc.Message#control object to define the control header in a message.
A control header contains information required for WebSocket reconnection, reliability, timeouts, error, the state of the message, type of the message, and so on. For information on the headers supported in the Control section, see WebRTC Session Controller JavaScript API Reference and WebRTC Session Controller Extension Developer's Guide.
Use the wsc.Message#header object to specify the specific action involved in the message. For example, for a START request, such information would contain who initiated the request, for whom it is intended, and so on. Your application can add additional headers to the this section. Such headers may be mapped by a gateway server to a SIP header or a parameter. For information on the headers supported in the Header section, see WebRTC Session Controller JavaScript API Reference and WebRTC Session Controller Extension Developer's Guide.
Use the wsc.Message#payload object to specify the payload section of the protocol specific to the "package". For:
CallPackage, the payload contains the offer or answer in Session Description Protocol (SDP)
MessageAlertPackage, the payload contains the exact message alerts in JSON format.
If you create a "Presence" package, the payload for messages associated with this package should contain the presence information.
When you use custom message flows, set up your application with the appropriate logic required to send and receive messages from Signaling Engine. Ensure that the correlation Ids, the sequencing and other details of the outgoing message are appropriate.
Complete the following tasks to send a custom message to Signaling Engine:
Set up the data as "key" : "value" pairs in
wsc.Message#control()
wsc.Message#header()
Set up the payload using wsc.Message#payload
Use JSON.stringify method to set up the message data in msg.
Create the message to be sent using wsc.Message(msg), where msg is message data.
Send the message using the sendMessage method of your application's ExtensibleSession object.
Monitor the message flow to take further action.
Save the session and subsession data, as required. See "Saving Your Custom Session".
Process a custom message that your application receives from Signaling Engine in the following way:
Set up the callback function for the onMessage event handler of the extended CallPackage object in your application. The custom message is provided in the event handler as a wsc.Message object.
Take appropriate action. Set up your application's response in the outgoing message.
Monitor the message flow to take further action.
Save the session and subsession data, as required. See "Saving Your Custom Session".
This section describes how you can customize your application by extending the WebRTC Session Controller JavaScript API library's default call and message alert package API objects.
Working with extended CallPackage objects involves the following:
You can create an extended call package when you instantiate a session, such as wscSession as shown below:
Example 8-3 Creating an Extended Call Package
var CallPackageExtension = function() { //sub-class must invoke the superclass's constructor CallPackageExtension.superclass.constructor.apply(this, arguments); }; CallPackageExtension.prototype.prepareCall = function(wseSession, callConfig, caller, callee) { return new CallExtension(session, callConfig, caller, callee); }; wsc.extend(CallPackageExtension, wsc.CallPackage);
Register the extended call package with the Session object you instantiated. For example:
// Create a extended CallPackage. extcallPackage = new CallPackageExtension(wscSession);
Call objects created from this extended call package can handle additional headers.
When you extend the call package, extend the required methods and event handlers:
prepareCall
putCall
onMessage
onRehydration. Extend this event handler so that your application can re-create the subsession object based on the rehydrated data your application receives through this event handler. When the subsession object is recreated, WebRTC Session Controller JavaScript API library invokes the onResurrect event handler of the call object.
To work with extended calls:
Extend the CallPackage object:
wsc.extend(CallPackageExtension, wsc.CallPackage);
Create an instance of the extended call package CallPackageExtension and register it with the session.
CallPackage = new CallPackageExtension(wscSession);
Use this instance of the call package to expand the way your application handles calls.
The code sample in Example 8-4 adds support to handle INFO messages as part of a call by extending the Call and CallPackage objects. If the incoming message has extra data, the prepareCall function is overridden.
Example 8-4 Extending the Call and CallPackage Objects
//CallExtension is the child object which extends Call object and overrides a function //The constructor of the child object calls the constructor of the parent so that the objects //initialized in the parent's constructor code is available to the child. function CallExtension() { //chain constructor CallExtension.superclass.constructor.apply(this, arguments) } //The following statement makes the CallExtension object as a child of wsc.Call wsc.extend(CallExtension, wsc.Call); //override the method onMessage to support handling INFO messages CallExtension.prototype.onMessage = function (message) { //check if this is an INFO message, if so, handle it here if (this.isInfoMessage(message)) { handleInfoMessage(message); } else { // delegate the handling to the base class CallExtension.superclass.onMessage.call(this, message) } }; CallExtension.prototype.isInfoMessage = function (message) { var action = message.header.action, type = message..control.type; return action === "info" && type === "message"; }; //Extend and CallPackage object and override the prepareCall function such that //A CallExtension object is created instead of the default Call object function CallPackageExtension() { CallPackageExtension.superclass.constructor.apply(this, arguments) } wsc.extend(CallPackageExtension, wsc.CallPackage); //override prepareCall function CallPackageExtension.prototype.prepareCall = function (session, callConfig, caller, callee) { return new CallExtension(session, callConfig, caller, callee); };
Working with extended CallPackage objects involves the following:
Creating an extended message alert package. The process is similar to creating an extended call package. See "Creating an Extended Call Package".
Registering the extended package with the session. The process is similar to registering an extended call package. See "Registering the Extended Package with the Session".
Extending the MessageAlertPackage to Support Other Message Events
When you extend the MessageAlertPackage class object, extend the required methods and event handlers:
onMessage
onRehydration. Extend this event handler so that your application can re-create the subsession object based on the rehydrated data your application receives through this event handler. When the subsession object is recreated, WebRTC Session Controller JavaScript API library invokes the onResurrect event handler of the rehydrated Subscription object.
You can extend the wsc.MessageAlertPackage class object to support other message event types.
To do so:
Use wsc.extend method to set up an extended MessageAlertPackage object.
Override the onMessage event handler of the extended MessageAlertPackage object. Your application can now handle notifications other than the default MessageSummary type.
Assign a callback function to handle the overridden onMessage event handler of the extended MessageAlertPackage object. In this callback function, process the new type of notification message.
Define a custom class extended from the Notification class object. This new type of notification object will store the notification messages made available by the overridden onMessage event handler.
Define a new class similar to MessageCounts and set it up to store the information on the new notification messages.