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

2 About Using the WebRTC Session Controller JavaScript API

This chapter presents a general overview of the Oracle Communications WebRTC Session Controller JavaScript application programming interface (API) library for the use of web application developers.

Note:

This document assumes that you have experience with developing applications using HTML5 features designed for WebRTC-enabled browsers. Its focus is restricted to how you can use the WebRTC Session Controller JavaScript API library to manage real-time communication featuring media stream and data transfers.

This chapter covers the following topics:

For information on error codes used by this API library, see "WebRTC Session Controller JavaScript API Error Codes and Errors".

For information on the Service Provider Interface (SPI) functions supported by this API library, see "Extending Your Applications Using WebRTC Session Controller JavaScript API".

Note:

Creating and implementing the design of the application's page, the appearance of its user interface and display elements are beyond the scope of this document.

See WebRTC Session Controller JavaScript API Reference for more information on the individual WebRTC Session Controller JavaScript API classes.

About the wsc Namespace

The wsc namespace exposes the WebRTC Session Controller JavaScript API library so that you can extend specific objects or methods in your applications.

About Using the WebRTC Session Controller JavaScript API Library

The WebRTC Session Controller JavaScript API library enables you to set up and manage real-time communication-related functionality associated with a call session, for example, audio and video call management, file transfers, message notifications, and so on.

About the API Used for General Tasks

The following WebRTC Session Controller JavaScript API classes are used to perform general tasks in your application:

In addition, your application needs to verify the media streaming capabilities of the browser. See "Verifying Browser Capabilities".

About the API Used for Call-Related Tasks

The following WebRTC Session Controller JavaScript API classes are used to perform call-related tasks in your application:

About the API Used for Message-Related Tasks

The WebRTC Session Controller JavaScript API classes used to perform message and notification-related tasks in your application are described in "Setting Up Message Alert Notifications".

About Extending WebRTC Session Controller JavaScript API

The ways in which you can extend your applications by extending WebRTC Session Controller JavaScript API classes are described in "Extending Your Applications Using WebRTC Session Controller JavaScript API".

Managing Sessions with wsc.Session

Manage the WebSocket connection between your application and WebRTC Session Controller by using the wsc.Session class. It represents a persistent association required for the exchange of information between your application and WebRTC Session Controller Signaling Engine. All the media streams, data transfers, and message alert notifications in your application take place within the scope of wsc.Session.

When your application page loads and the user logs in to your application, you first create an instance of the Session class such as wscSession, before you use any of the other WebRTC Session Controller JavaScript API objects associated with calls, data transfers, or message notifications.

Provide the following information when you create your application's session object:

  • The user's name

  • The WebSocket URI

  • The callback function in your application that should be invoked when the session is created

  • The callback function in your application that should be invoked when there is an error in creating the session

See "Setting Up the Session Object" for more information.

Your application's session object is associated with a unique session identifier. If you are creating the session object for the first time, WebRTC Session Controller Signaling Engine assigns the session identifier. You can use this identifier to refresh the session, for example, when the application page reloads. When the session has been successfully created, provide the settings to manage the connection. See "About Monitoring Your Application WebSocket Connection".

Your application's session may have many changes in its state. See "Handling Session State Changes" for information on session states and how your application can manage session state changes.

Authenticating Users with wsc.AuthHandler

Authenticate your application users with the wsc.AuthHandler class. This class enables your application to ensure that the user credentials are appropriate and will not disrupt message flow during the life of the session.

For example, based on your user's action, your application may send a request to a target Uniform Resource Locator (URL). WebRTC Session Controller Signaling Engine forwards the request to the target URL. The SIP proxy or registrar server may not allow that request to go further in the target environment if it does not have enough user credential information to do so. When this happens, the server sends back a challenge to WebRTC Session Controller Signaling Engine asking for more credential information.

On receiving the challenge from the SIP server, Traversal Using Relays around Network address translation (TURN) server, or proxy or registrar server, WebRTC Session Controller Signaling Engine forwards the challenge to the WebRTC Session Controller JavaScript API library. The WebRTC Session Controller JavaScript API library invokes the refresh event in your application's authentication handler. Your application can respond to such a challenge by retrieving the user credentials and returning that information as a JSON object. On receiving this information, WebRTC Session Controller Signaling Engine can then send your application's response to the SIP proxy/registrar server.

When you create an instance of the wsc.AuthHandler class in your application, set up a callback function to handle the AuthHandler.refresh event. In the following example, an application creates an authentication handler called authHandler and assigns a callback function called refreshAuth to its refresh event:

 // Create the session.
 // Here, userName is null. WSC can determine it by the cookie of the request.
 wscSession = new wsc.Session(null, webSocketUri, sessionSuccessHandler, sessionErrorHandler);
 // Register a wsc.AuthHandler with the session.  
 // It provides customized authentication info, such as username/password.
 var authHandler = new wsc.AuthHandler(wscSession);
 authHandler.refresh = refreshAuth;

The callback function has two parameters, authType and authHeaders. The authType entry indicates the authentication type and is one of the following entries:

  • wsc.AUTHTYPE.TURN: The type of authentication that allows for the client to authenticate with a TURN server. Turn servers facilitate clients behind a network address translator (NAT) or Firewall to communicate with each other in certain network topologies.

  • wsc.AUTHTYPE.SERVICE: The type of authentication when a back-end SIP application, such as the proxy/registrar, requires user authentication.

Use the value in authType to obtain the authentication information from the authHeaders and return it as a JSON object, as shown in Example 4-8.

Handling Session State Changes

Session state values are constants, such as CLOSED or CONNECTED. Session states are defined in the wsc.SESSIONSTATE enumerator.

If wscSession is your application's session object, you can set up a callback function and assign that function to your application's Session.onSessionStateChange event handler. Whenever the state of your application's session changes, the WebRTC Session Controller JavaScript API library invokes your application's Session.onSessionStateChange event handler and provides the new state.

In the callback function, you can check the new session state against the defined constants and set up appropriate actions to respond to the new state. For example, a change in the value of wsc.SESSIONSTATE from RECONNECTING to CONNECTED indicates that the attempt to reconnect succeeded and that the application can proceed. Or if the state changes from RECONNECTING to FAILED, the attempt to reconnect failed. In each case, your application may need to take appropriate action with respect to the user.

For a more information on the wsc.SESSIONSTATE enumerator, see Web Session Controller JavaScript API Reference.

Debugging Your Application with wsc.LOGLEVEL

Use the wsc.LOGLEVEL enumerator object to set up the type of records your application must log. The supported log levels are indicated by the data constants DEBUG (0), INFO (1), WARN (2), ERROR (3), and OFF (4).

To set up the log level for debugging, input the constant at the start of your JavaScript application:

wsc.setLogLevel(wsc.LOGLEVEL.DEBUG);

Alternatively, you can input the value (0):

wsc.setLogLevel(0);

See "Sample Setup of Global Variables and WebSocket URI".

Managing Calls with wsc.CallPackage

Use the wsc.CallPackage class to manage audio or video communication and/or data transfers in calls made from or received by your application. When you create an instance of wsc.CallPackage class, the WebRTC Session Controller JavaScript API library handles the messaging and call flow for all calls created through that object for that application session.

In the following example code, an application creates an instance of wsc.CallPackage called callPackage. Here, wscSession is the application's session with WebRTC Session Controller Signaling Engine.

var callPackage;
...
callPackage = new wsc.CallPackage(wscSession);

After creating an instance of the CallPackage class in your application, assign a callback function to handle each of the following events:

  • An incoming call, using the onIncomingCall event handler.

    In this callback function, implement the logic to process the incoming call, such as filtering to reject calls from blacklisted numbers or responding when the user accepts or declines the call. For information on how the default CallPackage class can be used in your applications, see "Setting Up Audio Calls in Your Applications".

  • A reconnected call, using the onResurrect event handler.

    In this callback function, implement the logic to handle the call that was dropped momentarily. See "Reconnecting Dropped Calls" for more information.

You use your application's CallPackage object to create outgoing calls. See "Managing a Call with wsc.Call".

See "Extending and Overriding WebRTC Session Controller JavaScript API Object Methods" for more information on extending the Call and CallPackage API classes.

Managing a Call with wsc.Call

Manage all audio, video streams, or data transfers that are associated with a single call session, by using the wsc.Call class. The wsc.Call object represents a single call and is used within a call package.

You can set up your application's Call object in the following ways:

  • When your application user initiates a call, create the call object using the CallPackage.createCall method and provide your application's call configuration.

  • When your application accepts an incoming call, use the incoming call object and the remote call configuration for the resulting call session. The WebRTC Session Controller JavaScript API library invokes the CallPackage.onIncomingCall event handler and provides the incoming call object and the caller's call configuration, as shown in Example 4-13.

Manage changes in the state of the call and its associated audio, media or data channel with the event handlers of the wsc.Call class, by implementing the logic in the callback function you assign for each event. For:

Specifying the Configuration for Calls with wsc.CallConfig

Specify the audio, video, and data channel capability for calls made from your application, with the wsc.CallConfig class.

When you create an instance of the wsc.CallConfig class in your application, set up the direction of the audio and video elements in the local media stream. Use the wsc.MEDIADIRECTION enumerator to specify the direction of the local media stream as one of the following:

  • wsc.MEDIADIRECTION.SENDRECV which indicates that the local media stream can send and receive the media stream.

  • wsc.MEDIADIRECTION.SENDONLY which indicates that the local media stream can send the media stream.

  • wsc.MEDIADIRECTION.RECVONLY which indicates that the local media stream can receive the media stream.

  • wsc.MEDIADIRECTION.NONE which indicates that media is not supported.

Set up the configuration for the data transfers in the dataChannelConfig parameter with key-value pairs in JSON format. Input the settings for the media stream and data transfers when you create the call configuration object in your application.

In the following example, an application sets up the local media stream to send and receive audio calls only:

var audioMediaDirection = wsc.MEDIADIRECTION.SENDRECV;
var videoMediaDirection = wsc.MEDIADIRECTION.NONE;

The application sets up the configuration for data transfers in dtConfigs with:

var dtConfigs = new Array();
dtConfigs[0] = {"label":"DataLabel", "reliable" : false };

Finally, the application uses these parameters to create a call configuration object called callConfig:

var callConfig = new wsc.CallConfig(audioMediaDirection,videoMediaDirection, dtConfigs);

See "Verifying Browser Capabilities" for information on how to verify the browser support for media streams.

Handling Changes in Call States

Your application needs to respond to the changes in the state of a call. The fields of the wsc.CALLSTATE enumerator object hold the various states of a call, such as STARTED, RESPONSED, and ENDED. For more information on the wsc.CALLSTATE enumerator, see Web Session Controller JavaScript API Reference.

The WebRTC Session Controller JavaScript API library also provides the wsc.CallState class which represents the state of the call. To process changes to the current call within the callback function you assign to your application's Call.onCallStateChange event handler, use the wsc.Callstate#status class and determine the call state status, the code for the current state, and the reason for the current state.

See "Setting Up the Event Handler for Call State Changes".

Handling Changes in Media Stream States

The media stream associated with your application is made up of two media components, local (in your application's browser) and remote (the other party's browser).

Your application needs to respond to changes in the media stream states of the call, whether it is voice or video. The WebRTC Session Controller JavaScript API library provides the wsc.MEDIASTREAMEVENT enumerator which defines the following three states each for the local and remote streams.

  • Added (LOCAL_STREAM_ADDED or REMOTE_STREAM_ADDED)

  • Removed (LOCAL_STREAM_REMOVED or REMOTE_STREAM_REMOVED)

  • In error (LOCAL_STREAM_ERROR or REMOTE_STREAM_ERROR)

See "Setting Up the Event Handler for the Media Streams" for information on how to use the wsc.MEDIASTREAMEVENT enumerator.

For a more information on the wsc.MEDIASTREAMEVENT enumerator, see Web Session Controller JavaScript API Reference.

Transferring Data With wsc.DataTransfer

If your application supports features such as gaming, text messaging, chat sessions, and file transfers, you can set up data transfer objects to manage the corresponding data channels in your application. Additionally, you can use the data channels with or without the audio or video streams.

The wsc.DataTransfer class manages a data channel between two peers. Each data transfer has a label. See "Specifying the Configuration for Calls with wsc.CallConfig" for information on dataChannelConfig, the data channel configuration parameter in your application's CallConfig object.

You can retrieve the following from your application's DataTransfer object:

  • The sender of the data transfer as an instance of wsc.DataSender class, by using the getSender method.

  • The receiver of the data transfer as an instance of wsc.DataReceiver class, by using the getReceiver method.

  • The state of the data transfer, by using the getState method.

To manage the open, closed, and error states of a data transfer, use the onOpen, onClose, and onError event handlers associated with your application's DataTransfer object.

See "Setting Up Data Transfers in Your Applications" for more information on how you can create applications that support data transfers.

Sending Data Using wsc.DataSender

The wsc.DataSender API works in connection with wsc.DataTransfer and wsc.DataReceiver API class objects.

If your application supports the sending of raw data, it can send a raw data object in the data channel of a data transfer as a string or a binary large object (BLOB) in your application's DataTransfer object. You can retrieve the identity of the sender by using the getSender() method of your application's DataSender object. Set up the data object that is to be sent and send it using the send method of the DataSender object in your application. See "Sample Send Function" for more information.

Receiving Data Using wsc.DataReceiver

The wsc.DataReceiver class works in connection with wsc.DataTransfer and wsc.DataSender classes.

If your application supports receiving raw data, and receiver is the instance of wsc.DataReceiver in your application, set up a callback function for the application's receiver.onMessage event handler. In that callback function, retrieve and handle the retrieved data as required by your application. For example:

receiver.onMessage = function(evt) {
    var rcvdDataElm = document.getElementById("rcvData");
    rcvdDataElm.value = evt.data;
 ...
}

Here, evt is the raw data in its entirety such as a text string, BLOBs, or array data.

About the Code Segments Displayed in This Guide

The example code segments shown in this guide focus on the features of the WebRTC Session Controller JavaScript API library and use minimal HTML5 elements for display aspects such as messages and control buttons. Any description of the display aspects of your applications and their CSS elements are beyond the scope of this guide.

The sample applications described in this guide show the use of the console.log method for displaying debug messages. When you create your applications, use the JavaScript Console API methods supported in your application's web browser to assist you in your application development process.

About the Application HTML File

This section describes the following aspects of your application's HTML file:

Note:

Each of the examples used in this document was written up as a single application html file with wsc.js as the sole supporting library.

About Web Applications Using WebRTC Session Controller JavaScript API

Every web application that uses audio, media stream, or data transfer (such as chat sessions) does so because of a call or a subscription associated with the application user. For web applications using the WebRTC Session Controller JavaScript API library, the Call object or the Subscription object is the critical element for providing communication functionality.

General Call Logic of Your Applications

The general logic associated with calls in web applications comprises the following:

  • Enabling a user who is logged in to your application to place a call.

    To do so, your application:

    • Sets up the logic necessary to obtain information on the recipient of the call (the callee's identifier).

    • On receiving the number to call from the user, performs the actions necessary to establish the call session between the caller and callee.

  • Enabling a user to accept or decline an audio or video call invitation.

    To do so, your application:

    • Sets up the necessary elements to respond to the incoming call request and perhaps filters the incoming call.

    • If necessary, provides the controls for the callee to accept or decline the audio or video call invitation from the caller.

    • If the callee accepts the call, completes the steps to establish the call session.

    • If the callee declines the call, takes appropriate steps.

    • If the caller cancels the call before it is established, takes appropriate steps.

  • Monitoring the established call session until one of the parties ends the call.

    To do so, your application:

    • Provides the logic necessary to end the call.

    • Takes appropriate action based on whether the call was ended or a party logged out (thus ending the session).

General Notifications Logic of Your Applications

The general logic associated with message alert notifications in web applications comprises the following:

  • Enabling a user who is logged in to subscribe to receiving notifications.

    To do so, your application:

    • Sets up the elements necessary for the user to subscribe for notifications.

    • On receiving the subscription target from the subscriber, sets up the subscriptions.

  • Enabling the user to access and process the received notifications.

    To do so, your application:

    • Sets up the elements necessary to receive the incoming notification and displays it for the user.

    • Sets up the logic to respond to the user's actions on his subscriptions.

Supporting Libraries

The wsc.js file contains the WebRTC Session Controller JavaScript API library. Reference the wsc.js file at the start of your HTML5 application code along with all other JavaScript files used by your application.

Example 2-1 Referencing the WSC.js Library

<script type="text/JavaScript" src="wsc_context_root/api/wsc.js"></script>

In Example 2-1, wsc_context_root represents the HTTP location where the WebRTC Session Controller is provisioned.

Ensure that all the supporting libraries used by your application are referenced appropriately.

Verifying Browser Capabilities

At the start of your application logic, check your browser's capabilities to access local media including audio and/or video media. If your browser does not appear to support the streaming needs of your application, enable your application to perform a graceful exit. If your browser can access the local media and your application obtains the media stream, your application can attach the media stream to the video/audio HTML5 media element, as appropriate.

In the following example, an application checks its browser to see if it can access the local media. If it cannot, the application calls a local function to perform a graceful exit.

if (!navigator.mozGetUserMedia && !navigator.webkitGetUserMedia) {
      // Cannot access media. Call function to exit gracefully.
      reptBrowserIssue();
     };

Below, the same application employs a utility function named attachMediaStream to attach a media stream to a video/audio element, when necessary:

var attachMediaStream = null;
attachMediaStream = function(element, stream) {
    element.src = URL.createObjectURL(stream);
    }

About Monitoring Your Application WebSocket Connection

The state of the application session depends on the state of the WebSocket connection between your application and WebRTC Session Controller Signaling Engine. The WebRTC Session Controller JavaScript API library monitors this connection.

When you instantiate your session object, you configure how the functionality in WebRTC Session Controller JavaScript API library checks your application's WebSocket connection. Monitor the state of the connection, by setting the following values in your application's Session object:

  • How often the WebRTC Session Controller JavaScript API library must ping the WebRTC Session Controller Signaling Engine:

    • Session.busyPingInterval, when there are subsessions inside the session. The default is 3,000 milliseconds (ms).

    • Session.idlePingInterval, when there are no subsessions inside the session. The default is 10,000 ms.

  • Session.reconnectInterval, which specifies the interval between attempts to reconnect to the WebRTC Session Controller Signaling Engine. The default is 2000 ms.

  • Session.retryCount which specifies the number of retry attempts to check the ping-pong time out after which the WebRTC Session Controller JavaScript API library reconnects to the WebRTC Session Controller Signaling Engine.

  • Session.reconnectTime, which specifies the maximum time for the interval during which the WebRTC Session Controller JavaScript API library should attempt to reconnect to the server. If the specified time is reached and the connection still fails, no further attempt is made to reconnect to the WebRTC Session Controller Signaling Engine. Instead, the session failureCallback event handler is invoked in your application. The default value is 60,000 ms.

    Note:

    Verify that the Session.reconnectTime value does not exceed the value configured for "WebSocket Disconnect Time Limit" in WebRTC Session Controller.

When your application is active, these values are used to check the state of the web socket connection.

About Handling Events in the Application Environment

Your application may be affected by the following events in your deployment environment, if the application is in operation when the events occur:

  • Client rehydration

    At times, the local application page state may be reinitialized if your application user reloaded the page or because the application reloaded itself (perhaps to update to a new version). See "Managing the Sessions in Your Application".

  • Network switch over

    A network switch over takes place when the end-user's IP address changes for example, when the end-user's device switches from a WIFI network to 4G network. Issues may arise when there is a switch over in the network environment. When a network switch over takes place, the WebRTC Session Controller JavaScript API library reconnects your application's session with WebRTC Session Controller Signaling Engine and tries to resurrect all the subsessions inside your application's Session object, such as the call and the subscription.

    For information on handling a call after a network switch over, see "Restoring a Call Session". For information on handling a subscription after a network switch over, see "Restoring a Subscription Session".

  • Clustered server shut down

    If the WebRTC Session Controller runs in a cluster environment, the server to which your application browser web browser is connected may shut down. In this scenario, the WebRTC Session Controller JavaScript API library tries to reconnect your application's session to the corresponding fail-over server. If the connection is reestablished, the WebRTC Session Controller JavaScript API library attempts to resurrect all the subsessions inside your application's Session object.

    For information on handling a call after a server fail over, see "Restoring a Call Session". For information on handling a subscription after a server fail over, see "Restoring a Subscription Session".

Managing the Sessions in Your Application

When you use the WebRTC Session Controller JavaScript API library in your application, your application can create an instance of the Session object and its subsessions, such as a call session or a subscription session. This section describes how the WebRTC Session Controller JavaScript API library manages the session and subsession information.

Note:

Any discussion on the management of arbitrary session or subsession data is beyond the scope of this document.

How Your Application Saves Session Information

By default, when your application uses the WebRTC Session Controller JavaScript API libraary and your application's session changes, the WebRTC Session Controller JavaScript API library saves all of the session information associated with the following objects in your application's session:

  • CallPackage

  • Call

  • MessageAlertPackage

  • Subscription

The WebRTC Session Controller JavaScript API library stores this application data in JSON format in the browser's sessionStorage object.

Note:

If you extend any WebRTC Session Controller JavaScript API class object, save the session identifier (sessionId) for use when you attempt to create the current session after your application page reloads.

Recreating the Session Using the Session ID

When your application page reloads, if you have saved the session identifier for the previously created session in your application, use that session identifier to recreate the Session object.

In Example 2-2, an application uses the isPageReload variable to set up the session as necessary. If the value in isPageReload indicates that the page has been reloaded, the application attempts to create the current session by providing the sessionId it had previously stored. Otherwise, it creates a new session.

In this application:

  • userName is the user name.

  • webSocketUri is the WebSocket connection defined earlier. See "Sample Setup of Global Variables and WebSocket URI".

  • successCallback is the function to call if the session object was created successfully.

  • failureCallback is the function to call if the session object was not created.

  • sessionId is the Session ID stored by the application.

Example 2-2 Recreating the Session Using SessionId Example




var isPageReload = false;
var sessionId = null;
...
...
// Create the session. If the page is reloaded, recreate the current session.
if (isPageReload) {
    // Aplication page reload scenario. Input the saved sessionId.
    wseSession = new wse.Session(userName, webSocketUri, successCallback, failureCallback, sessionId);
    } else {
    // This is a new session. Save sessionId if you have extended any API.
        wseSession = new wse.Session( userName, webSocketUri, successCallback, failureCallback);
        }
...



In addition, this application uses the following functions:


    

  • 

    The onPageLoad function sets the isPageLoad variable to true if the application page is the result of a page reload.
    

    function onPageLoad() {
    if (getSavedPageInfo()) {
        isPageReload = true;
        register();
       }
    }

    • 

  • 

    The savePageInfo function saves the sessionId in the HTML sessionStorage object.
    

    function savePageInfo() {
    sessionStorage.setItem("sessionId", wseSession.getSessionId());
    }

    • 

  • 

    The getSavedPageInfo function attempts to retrieve the sessionId from the HTML sessionStorage object.
    

    function getSavedPageInfo() {
    sessionId = sessionStorage.getItem("sessionId");
    if (sessionId != null) {
        return true;
    }
    return null;
    }

    • 

  • 

    The successCallback function invoked when the session is created successfully is not shown here. This function calls the savePageInfo function.
    

    • 








How WebRTC Session Controller JavaScript API Library Restores Application Data


When there is a client rehydration, a network switch over, or a clustered server shut down, the WebRTC Session Controller JavaScript API library attempts to restore your application using the sessionId you provide when you attempt to recreate your current application session. It uses sessionId as the key and loads the saved session data from browser's sessionStorage. It then sends a reconnect message to the WebRTC Session controller Signaling Engine.


If the reconnection request receives a success response from WebRTC Session Controller Signaling Engine, your application's session state goes from wsc.SESSIONSTATE.RECONNECTING to wsc.SESSIONSTATE.CONNECTED. Monitor this change in the callback function you assign to the Session.onSessionStateChange event handler.


When the session regains its wsc.SESSIONSTATE.CONNECTED state, the WebRTC Session Controller JavaScript API library provides the following to your application:



If the WebRTC Session Controller JavaScript API library fails to load data, it invokes the failureCallback function associated with the session creation step.








Restoring Your Application Package Data After Your Application Pages Reload


After your application pages successfully reload and the WebSocket connection has been successfully restored, your application can repopulate the data associated with its WebRTC Session Controller JavaScript API objects by doing the following:






Restoring CallPackage Data After Pages Reload


To restore the call package data after your application pages successfully reload, set up appropriate actions within the callback function assigned to your application's CallPackage.onRehydration event handler. This callback function has one parameter, rehydratedData, which contains the data about the call stored in the sessionStorage object of the web browser. Within the callback function you can define the actions with respect to the recovered call. See "Restoring a Call Session".


When you extend the CallPackage object in your application, you can override its onRehydration event handler. See "Extending Objects Using the wsc.extend Method" for more information.








Restoring Extended MessageAlertPackage Data After Pages Reload


To handle the subscription session data after your application pages successfully reload, set up appropriate actions within the callback function assigned to your application's MessageAlertPackage.onRehydration event handler. This callback function has one parameter, rehydratedData which contains the data about the subscription stored in the sessionStorage object of the web browser. Within the callback function you can define the actions with respect to the recovered subscription. See "Restoring a Subscription Session".


When you extend the MesageAlertPackage object, you can override its onRehydration event handler and use this function to refresh the current subscription with the recovered data. See "Extending Objects Using the wsc.extend Method" for more information.










Restoring a Call Session


If a call is recovered following a page reload, network switch over or server fail over, the WebRTC Session Controller JavaScript API library invokes the CallPackage.onResurrect event handler in your application. The resurrected call is provided as the parameter to the callback function. Use the callback function to perform the actions required on the rehydrated call and resume the rehydrated call. See "Resuming Your Application Operation".


In Example 2-3, an application sets up callHandler as an instance of the CallPackage class object and assigns onResurrect as the callback function for its CallPackage.onResurrect event handler. The onResurrect callback function uses the rehydratedCall object.




Example 2-3 Sample onResurrect Function for a CallPackage


callHandler = new wsc.CallPackage(wscSession);
if(callHandler){
  callHandler.onResurrect = onResurrect;
}
...
function onResurrect(rehydratedCall) {
  // set callback for call state changed
  rehydratedCall.onCallStateChange = function(newState) {
    ...
  }
  // set callback for media state changed
  rehydratedCall.onMediaStreamEvent= function(mediaStreamEvent, stream) {
    ...
  }
  // resume the call with setting related callback functions.
  rehydratedCall.resume(onResumeCallSuccess, doCallError);
}









Restoring a Subscription Session


If your application user's subscription is recovered following a page reload, network switch over or server fail over, the WebRTC Session Controller JavaScript API library invokes your application's MessageAlertPackage.onResurrect event handler. The rehydrated subscription is provided as the parameter to the callback function. Use the corresponding callback function to perform any action it requires. See "Resuming Your Application Operation".


In Example 2-4, an application sets up subscribeHandler as an instance of the MessageAlertPackage class object and assigns onResurrect as the callback function for its MessageAlertPackage.onResurrect event handler. The onResurrect callback function uses the rehydratedSubscription object to restore the application's current Subscription object.




Example 2-4 Sample onResurrect Function for a MessageAlertPackage


subscribeHandler = new wsc.MessageAlertPackage(wscSession);
if (subscribeHandler) {
    subscribeHandler.onResurrect = onResurrect;
}
...
function onResurrect(rehydratedSubscription) {
    // reset related callback functions
    subscription = rehydratedSubscription;
    subscription.onNotification = onNotification;
    subscription.onEnd = onEnd;
    // initialize other information on page ...
}









Resuming Your Application Operation


To resume your application operation following a page reload, a network switch over, or a server fail over:


    

  • 

    For calls: Resume the current call by invoking its resume method. See "Reconnecting Dropped Calls".
    

    • 

  • 

    For subscriptions: Call the subscription's isValid method and take further action. If the user prefers to end the subscription, use the subscription's end method to do so. See "Restoring a Subscription".
    

    • 





Important:

If you create a custom package, be sure to implement the appropriate logic to resume its call or subscription operation.



























Go to previous page

Previous		
Go to next page

Next		











Go to Documentation Home

Home		
Go to Table of Contents

Contents		
Go to Feedback page

Contact Us