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 about the individual WebRTC Session Controller JavaScript API classes.When your application creates a session, a call or message alert package, starts 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 the signaling messages for all the resulting default commands.
In order to broaden or extend your application logic, 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 more communication-related services in audio, video, and data transfer flows. For example:
Custom calls
You can implement logic to prepare custom calls. Set 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 can 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 that extends 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 employ 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 10-1 creates the wsc.CallExtension object which extends the wsc.Call object.
Example 10-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);
Here, 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. To access and retrieve information about a subsession, use the methods in wsc.ExtensibleSession. To do so, use its identifier (sessionId), retrieve a specific package by its type and manage the object. You can also 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 tasks:
If your application logic uses extended call sessions, set up the required actions in a callback function for the CallPackage.onMessage event handler in the application. When call-related messages come in to your application, this callback function is called, 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, the 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 insert the call in the flow 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. To do so, extend the Call object. 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 call the methods that support extension headers. See "Handling Extra 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 the 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 the MessageAlertPackage object in your application manages an array of subscriptions, then, when a notification comes to your application, the MessageAlertPackage.onMessage event handler is called. In the callback function you assign to this event handler, you can process the incoming message notification to identify the subscription object and call 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".
You can set up your application to send or receive extra data in the form of an extra header field.
Some methods in the Call and CallPackage class objects can accept an extra argument, as long as it is a JSON object. This extra 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, your application page is designed for an auto dealership. Your application has gathered data on the preferences that a customer has for the make, model, and deal preferences, such as carMaker, Convertible), and Lease.
When the customer 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 called 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 displays the information for the dealer.
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 Oracle Communications 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.
To start the call, place the JSON object as the last parameter when your application calls the start method of the outgoing call object.
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 the CallPackage.onIncomingCall event handler. The extension header is in JSON format.
Perform any actions based on the extra data in the extension header.
If the call is accepted, do the following:
Set up the extension header as a JSON object.
To start the call, include the JSON object when your application calls the start method of the outgoing call object.
For example, if call is the call object, callConfig the local media stream and the 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 a callee declines the call, do the following:
Obtain the reason why the callee declined the call.
Set up the extension header as a JSON object.
Include the JSON object when your application calls the decline method of the outgoing call object.
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)
Set up your application to handle incoming messages and set up outgoing messages associated with the following events. In each case, set up the extension header and place it as the last parameter when you call the associated function for the extended call.
The caller or callee ends the call.
Set up the extension header as described earlier and include it when you call the end method for the extended call.
The call is updated.
If the caller or callee:
Requests the update.
Set up the extension header as described earlier and include it when you call 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 call 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 extra data as the extension header in the method for the outgoing call.
Your applications can use custom session objects to enable customers to subscribe to the presence of, chat with, or set up calls that can be transferred to other individuals. 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 WebSocket 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 in your application, use the following objects:
The ExtensibleSession:
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 the ExtensibleSession object.
Saving session data to the sessionStorage object of the web browser by using the saveToStorage method of the ExtensibleSession object.
For more information about subsessions, see Oracle Communications WebRTC Session Controller JavaScript API Reference.
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 the ExtensibleSession object.
Retrieving the package by its type by using the getPackage method of the 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 the ExtensibleSession object.
Handling an incoming message using the Call.onMessage method in the ExtensibleSession object.
Generating a correlation ID for the message using the genNewCorrelationId method of the ExtensibleSession object.
The generated correlation ID is based on the current outbound sequence number sequence of this session. For information about sequence, see Oracle Communications WebRTC Session Controller Extension Developer's Guide.
The message flow as required by the requirements of the extended session. See "Sending And Receiving Custom Messages".
The subsession of the ExtensibleSession in your application by:
Retrieving the session ID of the subsession using getSubSessionId of the ExtensibleSession object.
Retrieving all subsessions that belong to a specific package using getSubSessionsByPackageType method of the ExtensibleSession object.
Placing a subsession object into the session with putSubSession method of the ExtensibleSession object.
Removing subsession object giving its ID using removeSubSession method of the 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.
To handle the data associated with custom sessions or subsessions, save the corresponding data in the HTML SessionStorage area using the ExtensibleSession.saveToStorage method. Store the session data in JSON format. To maintain the session's current state for use in dealing with connectivity issues, ensure that your application captures the necessary changes.
Important:
When your application uses a custom package or subsession object, save the subsession state to support rehydration. Monitor the change in the subsession state and call the ExtensibleSession.saveToStorage() method to save the data.At times you create messages independent of the default call or message alert package. Set up logic to handle the flow of such custom messages and the resulting actions in your application.
You can send custom messages within a subsession by providing a Message object as an argument when you call the ExtensibleSession#sendMessage method. Ensure that the 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 Oracle Communications WebRTC Session Controller JavaScript API Reference.
To create custom packages and use custom message flows in your applications, use the following objects:
Note:
For information about 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 10-2 shows the header sections of a message object which starts a WebSocket connection:
Example 10-2 The Header Sections of a Message Object
{
"control": {
"type":"request",
"sequence":"1",
"version":"1.0"
},
"header": {
"action":"connect",
"initiator":"bob@someCompany.com",
}
}
Note:
To create messages independent of the default call or message alert package, use the wsc.Message object. 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 about the headers supported in the Control section, see Oracle Communications WebRTC Session Controller JavaScript API Reference and Oracle Communications 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 launched the request, for whom it is intended, and so on. Your application can add extra headers to this section. A gateway server can map such headers to a SIP header or a parameter. For information about the headers supported in the Header section, see Oracle Communications WebRTC Session Controller JavaScript API Reference and Oracle Communications 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 contains the presence information.
To send and receive messages for custom flows 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 the ExtensibleSession object in your application.
To take further action, monitor the message flow.
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".
You can customize your application by extending the default call and message alert package API objects in WebRTC Session Controller JavaScript API library.
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 10-3 Creating an Extended Call Package
var CallPackageExtension = function() {
//sub-class must call the constructor of the superclass
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 an extended CallPackage. extcallPackage = new CallPackageExtension(wscSession);
Call objects created from this extended call package can handle extra 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 calls 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 10-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 10-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 he objects.
//The objects initialized in the constructor code for the parent are 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 it 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.
//A CallExtension object must be 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 calls 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.
To handle the overridden onMessage event handler of the extended MessageAlertPackage object, assign a callback function. 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 stores 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 about the new notification messages.