Skip Headers
Oracle® Communications WebRTC Session Controller Web Application Developer's Guide
Release 7.0

E40978-01
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

8 Extending Your Applications Using WebRTC Session Controller JavaScript API

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.

About the Default Messaging Mechanism Used by Your Applications

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.

About Extending the WSC Namespace

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:

Note:

WebRTC Session Controller JavaScript API Reference uses the term "For extensibility" to identify such extensible objects and methods.

Extending Objects Using the wsc.extend Method

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.

Extending Sessions with wsc.ExtensibleSession Class

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".

Extending and Overriding WebRTC Session Controller JavaScript API Object Methods

You can override and extend methods in WebRTC Session Controller JavaScript API objects to do the following:

Handling Extended Call Sessions with CallPackage.onMessage

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.

Preparing Custom Calls with CallPackage.prepareCall

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.

Inserting Calls into a Session with CallPackage.putCall

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);

Processing Custom Messages for a Call with Call.onMessage

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".

Extending Headers in Call Messages

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.

Handling Custom Message Notifications

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.

Handling Extensions to Notifications with MessageAlertPackage.onMessage

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".

Handling Additional Headers in Messages

Your application may need to allow users to send or receive additional data in the form of an extra header field.

About Additional Headers in Messages

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.

Handling Additional Headers

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.

Managing Calls with Additional Headers

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:

  1. Set up the extension header as a JSON object.

  2. 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:

  1. Retrieve the extension header from your application's CallPackage.onIncomingCall event handler. The extension header is in JSON format.

  2. Perform any actions based on the additional data in the extension header.

  3. If the application user accepts the call, do the following:

    1. Set up the extension header as a JSON object.

    2. 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)
      
  4. If the application user declines the call, do the following:

    1. Obtain the reason the call was declined by the user.

    2. Set up the extension header as a JSON object.

    3. 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.

Working with wsc.ExtensibleSession

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.

Creating an Extensible Session in Your Application

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.

Creating Custom Packages Using the ExtensibleSession Object

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.

Saving Your Custom Session

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.

Sending And Receiving Custom Messages

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.

About the API Classes Used to Create Custom Message

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.

wsc.Message

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".

wsc.Message#control

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.

wsc.Message#header

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.

wsc.Message#payload

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.

Managing Custom Message Data Flows

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.

Sending a Custom Message to Signaling Engine

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".

Processing an Incoming Custom Message

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".

Customizing Your Applications by Extending the Package Objects

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

Working with extended CallPackage objects involves the following:

Creating an Extended Call Package

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);

Registering the Extended Package with the Session

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.

Extending the Methods and Event Handlers in the Extended Call Package

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.

Working with Extended Calls

To work with extended calls:

  1. Extend the CallPackage object:

    wsc.extend(CallPackageExtension, wsc.CallPackage);
    
  2. 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 MessageAlertPackage Objects

Working with extended CallPackage objects involves the following:

Extending the Methods and Event Handlers

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.

Extending the MessageAlertPackage to Support Other Message Events

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.