This chapter shows how you can use the Oracle Communications WebRTC Session Controller JavaScript Adobe Flash application programming interface (API) library to develop real time Web communications applications that will work in Microsoft Internet Explorer.
Microsoft Internet Explorer (IE) provides no support for WebRTC protocols. For many enterprise customers, however, IE remains integral to their business operations. In order to allow IE to utilize WebRTC functionality, WebRTC Session Controller provides an extension leveraging the near ubiquitous Adobe Flash plug-in.
The following sections describe the minimum system requirements for the WebRTC Session Controller Flash extension.
The Adobe Flash plug-in, version 17 or greater, is required for the WebRTC Session Controller Flash extension to function in client browsers.
The Adobe Flash plug-in can be downloaded from https://get.adobe.com/flashplayer/
Note:
Google Chrome has a built-in Flash implementation.The WebRTC Session Controller Flash extension supports IE versions 8 through 11. In addition, the Flash extension will also work with Firefox version 33.1 and above, and Chrome version 40.0.2214.95 and above.
Note:
A third-party WebSockets solution is required for IE versions 8 and 9, and is not a part of the WebRTC Session Controller Flash extension.The WebRTC Session Controller Flash extension supports the following audio and video codecs:
Video (no transcoding support)
H.264/MPEG-4
Audio (transcoding supported)
Speex
G.711 u-law (pcmu)
G.711 a-law (pcma)
Note:
If a non-IE Web browser is initiating a WebRTC call to an IE Web browser, only audio is supported. The reverse is also true, unless the non-IE browser answers the call using the WebRTC Session Controller Flash extension itself.The WebRTC Session Controller Flash interface extension consists of the following two JavaScript libraries:
wsc-flash.js
wsc-ie-adapter.js
The wsc-flash.js library contains two classes, FlashCall and FlashCallPackage which are subclasses of Call and CallPackage respectively, and which seamlessly handle Flash audio and video call functions. The wsc-ie-adapter.js library contains various IE support functions.
In addition, a new Groovy package, flash, has been added with additional Flash call processing logic.
The following sections describe the detailed steps necessary to download and install the Flash extension support for both WebRTC Session Controller Signalling Engine and Media Engine.
To access and download the Flash extension patch, you need a My Oracle Support account. If you do not have one, you can register here, https://profile.oracle.com/myprofile/account/create-account.jspx?nextURL=https%3A//support.oracle.com.
To download the Flash extension patch:
Go to https://support.oracle.com and sign in using your Oracle account credentials.
Select the Dashboard tab if it is not already selected.
In the Knowledge Base pane, select the Search & Browse tab and select Oracle Communications WebRTC Session Controller from the Select a product or product line drop down list.
Enter the patch number, 212208789 in the Enter search terms text box and click the Search button.
In the KM Search Results page underneath Recommended Links click the entry, WebRTC Session Controller Flash Support.
In the right pane, click the Download button and save and extract the patch archive, p21208789_71000_Generic.zip to the local file system of your WebRTC Session Controller installation.
Follow the OPatch utility instructions described in README.txt to apply the Signalling Engine system patch.
Note:
The OPatch installation is required for Flash extension support but is distinct from the Flash extension configuration described in the following sections.To install the Flash extension on Signalling Engine:
Make sure that your WebRTC Session Controller administration server is running. For instructions on starting WebRTC Session Controller, see Oracle Communications WebRTC Session Controller System Administrator's Guide.
Run the following commands to set your environment:
cd WebLogic_home/user_projects/domains/My_domain/ source bin/setDomainEnv.sh
Note:
Replace My_domain with the name of your WebRTC Session Controller Domain.Enter the following command to initialize the WebLogic Scripting Tool (WLST) console:
java weblogic.WLST
Enter the following command to connect to the WebRTC Session Controller administration server:
connect()
Note:
You will be prompted to enter the user name, password and server URL for your administration server. You can safely ignore any "insecure protocol" warnings.Enter the following command:
execfile("Absolute_path/212208789/custom/scripts/wsc_extension_for_flash_7.1.py")
Note:
Replace Absolute_path with the full and complete path to the extracted patch archive.You should see the following output from the wsc_extension_for_flash_7.1.py script:
Starting WebRTC Session Controller configuration extension ...
>>>>>> Create new [flash] package
Creating FROM_APP/start/request script ...
Creating FROM_NET/INVITE/request script ...
Creating FROM_APP/start/response script ...
Creating FROM_APP/start/error script ...
Creating FROM_NET/INVITE/response script ...
Creating FROM_APP/complete/message script ...
Creating FROM_NET/ACK/request script ...
Creating FROM_APP/shutdown/message script ...
Creating FROM_NET/BYE/request script ...
Creating FROM_NET/CANCEL/request script ...
>>>>>> Update register package to add capability registration
[Warning] : FROM_APP/connect/request script does not need to be updated again !
>>>>>> Update ScriptLibrary
Updating resolveProcessingParameters method ...
[Warning] : resolvePackageType has already been updated !
WebRTC Session Controller configuration successfully updated.
Disconnected from weblogic server: AdminServer
wls:/offline>
Enter the following command to disconnect from the WLST console:
exit("quit")
Log in to the WebRTC Session Controller console at http://host:port/wsc-console, where host:port represents the server URL and port number of your administration server.
Note:
The default WebRTC Session Controller administration server port is 7001.Enter the Username and Password for the Administration Server and click Login.
Select the Packages tab and verify that flash appears under Package Name in the Packages pane.
Note:
You may need to clear the IE browser cache if you do not see the flash package.To grant a WebRTC Session Controller Application access to the Flash extension:
Log in to the WebRTC Session Controller console at http://host:port/wsc-console, where host:port represents the server URL and port number of your administration server.
Note:
The default WebRTC Session Controller administration server port is 7001.Enter the Username and Password for the Administration Server and click Login.
Select the Applications tab.
Click the Edit button.
For the application to which you want to add the WebRTC Session Controller Flash extension, double-click its cell in the Packages column.
In the Package mapping dialog, check the box adjacent the flash entry in the Name column and click OK.
Click the Save button.
This section describes how to configure the WebRTC Session Media Engine (ME) for Flash extension support.
Note:
Flash extension support requires ME version 370m3p3.There are three components to configuring the ME for Flash support. You must configure the type of Real-Time Media Protocol (RTMP) to use, create a multimedia-streaming-config server, and then create a named session-config to support Flash calls.
The ME supports the following types of RTMP:
RTMP: Unencrypted RTMP.
RTMPS: Encrypted RTMP through a TLS connection.
RTMPT: Unencrypted RTMP tunneled through HTTP.
To configure RTMP:
Select the Configuration tab and click the cluster > box > interface > ip object.
Click Configure next to media-server.
Click Add rtmp.
port: Specify a TCP port. Oracle recommends using the default port, 1935.
Click Create.
app-name: Specify a unique app-name for this server. Oracle recommends using the default app-name, live.
Click Set.
Select the vsp object.
Click Configure next to multimedia-streaming-config.
Click Add server.
name: Enter a unique name for this server.
host: Enter the RTMP server's IP address or FQDN. The RTMP server can be an external RTMP server or the local ME can act as the RTMP server. If the local ME is acting as the RTMP server, this value should be set to the IP address of the interface on which the media-server is configured.
port: Enter the server port. Oracle recommends using the default RTMP port, 1935.
protocol: Specify the rtmp protocol.
Click Create. Update and save the configuration.
Example 9-1 shows a CLI sample of RTMP configuration:
This section describes configuring RTMPS on the ME. RTMPS can be used with or without an HTTP proxy to provide secure RTMP traffic. If an HTTP proxy is required, the proxy must be configured to allow SSL connections to traverse the HTTP proxy using the CONNECT method.
RTMPS is RTMP encrypted within TLS. For secure RTMP on the ME, you must copy and configure a certificate to be used for the TLS connection between the RTMP server and the Flash endpoint. If the Flash endpoint is a browser, the you also must import the certificate's root authority into the browser as a "trusted root certification authority".
To configure the certificate:
Copy the TLS certificate into the ME's /cxc/certs directory.
Select the Configuration tab and click the vsp > tls object.
Click Add certificate.
name: Enter a name for the certificate.
Click Create.
The certificate screen appears.
certificate-file: Browse to the certificate in the /cxc/certs directory.
passphrase-tag: Enter a name to associate with the passphrase associated with the certificate file. Use this if the certificate file is encrypted to have its private key information protected. This passphrase must match the string that the certificate was encrypted with.
Click Set. Update and save the configuration.
Example 9-2 shows a CLI sample of the certificate configuration.
Use the secret action to set the certificate secret.
For more information on the secret action, see the Oracle Communications WebRTC Session Controller Media Engine Object Reference guide.
Example 9-3 shows a CLI sample of the secret action:
secret set <tag> password: <password or passphrase> confirm: <password or passphrase>
To configure RTMPS:
Select the Configuration tab and click the cluster > box > interface > ip object.
Click Configure next to media-server.
Click Add rtmps.
port: Specify a TCP port.
Click Create.
app-name: Specify a unique app-name for this server. Oracle recommends using the default app-name, live.
certificate: Select the TLS certificate you configured.
Click Set.
Click Add rtmp.
port: Specify a TCP port. Oracle recommends using the default port 1935.
Click Create.
app-name: Specify a unique app-name for this server. Oracle recommends using the default app-name, live.
Click Set.
Select the vsp object.
Click Configure next to multimedia-streaming-config.
Click Add server.
name: Enter a unique name for this server.
host: Enter the RTMP server's IP address or FQDN. The RTMP server can be an external RTMP server or the local ME can act as the RTMP server. If the local ME is acting as the RTMP server, set this value to the IP address of the interface on which the media-server is configured.
port: Enter the server port.
protocol: Specify the RTMPS protocol.
Click Create. Update and save the configuration.
Example 9-4 shows a sample RTMPS CLI configuration.
Example 9-4 RTMPS CLI Configuration
config box interface <eth-x> ip <ip-name>
config media-server
config rtmp 1935
return
config rtmps <port-number>
set certificate vsp\tls\certificate <certificate-name>
set passphrase-tag <tag>
return
return
return
config vsp
config multimedia-streaming-config
config server rtmps
set protocol rtmps
set host <rtmp-server>
set port <port-number>
return
return
return
This section describes configuring RTMPT on the ME. RTMPT can be used to tunnel unencrypted RTMP traffic through an HTTP proxy by tunneling the RTMP traffic inside HTTP.
To configure RTMPT:
Select the Configuration tab and click the cluster > box > interface > ip object.
Click Configure next to media-server.
Click Add rtmpt.
port: Specify a TCP port.
Click Create.
app-name: Specify a unique app-name for this server. Oracle recommends using the default app-name, live.
Click Set.
Click Add rtmp.
port: Specify a TCP port. Oracle recommends using the default port 1935.
Click Create
app-name: Specify a unique app-name for this server. Oracle recommends using the default app-name, live.
Select the vsp object.
Click Configure next to multimedia-streaming-config.
Click Add server.
name: Enter a unique name for this server.
host: Enter the RTMP server's IP address or FQDN. The RTMP server can be an external RTMP server or the local ME can act as the RTMP server. If the local ME is acting as the RTMP server, set this value to the IP address of the interface on which the media-server is configured.
port: Enter the server port.
protocol: Specify the RTMPT protocol.
Click Create. Update and save the configuration.
Example 9-5 shows a sample RTMPT CLI configuration.
Example 9-5 RTMPT CLI Configuration
config box interface <eth-x> ip <ip-name>
config media-server
config rtmp 1935
return
config rtmpt <port-number>
return
return
return
config vsp
config multimedia-streaming-config
config server rtmpt
set protocol rtmpt
set host <rtmp-server>
set port <port-number>
return
return
return
Once you have configured RTMP, you must create a session-config to refer to the multimedia-streaming-config.
To create a session-config:
Select the Configuration tab and click the vsp > session-config-pool object.
Click Add entry.
name: Specify the name flash for this session-config.
Click Create.
The session-config-pool > entry screen appears.
Click Configure next to peer.
type: Select streamer from the drop-down list.
streamer: Select the vsp\multimedia-streaming-config\server <server-name> you created from the drop-down list.
Click Create and return to the session-config-pool > entry screen.
Click Configure next to media.
anchor: Set to enabled.
Click Configure next to nat-traversal.
symmetricRTP: Set to true.
Click Set
Return to the session-config-pool > entry screen.
Click Configure next to sip-directive.
directive: Set to allow and click Set.
Click Set. Update and save your configuration.
Example 9-6 shows a sample session-config CLI configuration.
Example 9-6 Session-Config CLI Configuration
config vsp
config session-config-pool
config entry flash
config peer
set value streamer "vsp\multimedia-streaming-config\server <server-name>"
return
config media
set anchor enabled
config nat-traversal
set symmetricRTP true
return
return
config sip-directive
set directive allow
return
return
return
The WebRTC Session Controller JavaScript API has been expanded with additional functionality that lets you add seamless real time Web application audio and video call support for IE browser clients.
This section describes the steps necessary to add the required JavaScript libraries and place and receive WebRTC calls using the Flash extension.
To add Flash support to your Web application, you complete the following general steps:
Download the Google SWFObject JavaScript support library.
Reference the WebRTC Session Controller Flash JavaScript extension files and the Google SWFObject JavaScript support library in your Web application.
Initialize the WebRTC Session Controller Flash extension.
Retrieve WebRTC/Flash browser support information so you can handle calls as required.
Pass the WebRTC/Flash browser support information to the WebRTC Session Controller Session so that the Groovy script library can relay the support to other callees.
Initiate a Flash audio/video call.
Terminate the Flash audio/video call.
Additional sections discuss answering incoming Flash-based calls as well as determining whether a particular call was initiated from the Flash extension.
The WebRTC Session Controller Flash extension requires the use of a third-party JavaScript library from Google, SWFObject. Download swfobject_2_2.zip from https://code.google.com/p/swfobject/downloads/list, and extract swfobject.js to the same location as your other JavaScript libraries.
Update the JavaScript library references in your WebRTC Session Controller application, including the Flash extension wsc-ie-adapter.js library before any other WebRTC Session Controller JavaScript libraries, and then the Google swfobject.js library before the Flash extension wsc-flash.js library.
Figure 9-0 shows the required ordering.
Example 9-7 Flash Extension JavaScript Library References
<script type="text/javascript" src="js/wsc-ie-adapter.js"></script> ... Include any other WebRTC Session Controller libraries in the ... <script type="text/javascript" src="JavaScript_path/wsc-common.js"></script> <script type="text/javascript" src="JavaScript_path/wsc-call.js"></script> <script type="text/javascript" src="JavaScript_path/swfobject.js"></script> <script type="text/javascript" src="JavaScript_path/wsc-flash.js"></script> ... Include your own JavaScript libraries here...
For more information on WebRTC Session Controller JavaScript libraries, see "WebRTC Session Controller Support Libraries."
You must call wsc_flash.wscFlash.init(0) to initialize WebRTC Session Controller Flash support after all the required JavaScript libraries are loaded.
Figure 9-0 shows the required initialization logic.
In your WebRTC application, you can use the WebRTC Session Controller Flash extension JavaScript function getMediaOptions() to determine whether WebRTC, Flash, or both are supported by the browser.
Example 9-9 shows how you can analyze the return values from getMediaOptions() to determine WebRTC/Flash support in a client browser.
Example 9-9 Determining Flash/WebRTC Support in a Client Browser
var mediaOptions = getMediaOptions(); if (mediaOptions.webrtc && mediaOptions.flash) { console.log ("Both Flash and WebRTC are supported."); } else if (mediaOptions.webrtc) { console.log ("Only WebRTC is supported."); } else if (mediaOptions.flash) { console.log ("Only Flash is supported."); } else { console.log ("Neither Flash nor WebRTC support detected."); }
If the client browser is IE, only Flash support is available. If the client browser is Firefox, both WebRTC support and Flash support are available if a Flash plug-in is installed. Since Google Chrome includes its own Flash engine, it always returns support for both WebRTC and Flash.
The WebRTC/Flash support information returned by getMediaOptions() should be provided to a newly instantiated WebRTC Session Controller session using the extension header, X-MediaOptions. X-MediaOptions are stored in the sessionStore and are used to resolve the incoming call package type (CallPackage or FlashCallPackage). The Flash Groovy code will use information in the sessionStore to determine if the browser supports Flash, WebRTC or both.
Figure 9-0 illustrates passing media options for WebRTC session initialization.
Example 9-10 Determining Flash Browser Support
var mediaOptions = getMediaOptions(); var sessionId = sessionStorage.getItem("sessionId"); // Create a new WebRTC Session Controller session including the mediaOptions... if (sessionId) { wscSession = new wsc.Session(userName, wsUri, onSessionSuccess, onSessionError, sessionId, {'X-MediaOptions': mediaOptions}); } else { wscSession = new wsc.Session(userName, wsUri, onSessionSuccess, onSessionError, undefined, {'X-MediaOptions': mediaOptions}); }
Figure 9-0 illustrates how to make an audio/video call using the Flash extension. Note that the only significant difference is that the FlashCallPackage's createCall method is called rather than CallPackage's.
Example 9-11 Initiating a Call Using the Flash Extension
function makeFlashVideoCall() {
var callee = "alice@example.com";
var audioMediaDirection = wsc.MEDIADIRECTION.SENDRECV;
var videoMediaDirection = wsc.MEDIADIRECTION.SENDRECV;
var callConfig = new wsc.CallConfig(audioMediaDirection,
videoMediaDirection,
undefined);
// The FlashCallPackage is initiated when the Call session is created...
wscCall = flashCallPackage.createCall(callee,
callConfig,
onCallError);
console.log("Initiating a Flash extension audio/video call...");
initWscCall(wscCall);
wscCall.start();
// Update the HTML page's UI as required...
}
function initWscCall(call) {
wscCall = call;
call.onCallStateChange = function(newState) {
onCallStateChange(call, newState);
};
call.onUpdate = function(callConfig) {
onCallUpdate(call, callConfig);
};
call.onMediaStreamEvent= onMediaStreamEvent;
}
Note:
If a non-IE Web browser is initiating a WebRTC call to an IE Web browser, only audio is supported. The reverse is also true, unless the non-IE browser answers the call using the Flash extension itself.For more information on handling outgoing audio calls, see Chapter 4, "Setting Up Audio Calls in Your Applications." For more information on handling outgoing video calls, see Chapter 5, "Setting Up Video Calls in Your Applications."
Figure 9-0 shows a Flash extension call terminated using FlashCall's end() method. There is no functional difference in call termination between a regular WebRTC call and a Flash call.
In your WebRTC application, when handling an incoming call the JavaScript event handler, onMediaStreamEvent, must support the following events:
wsc.MEDIASTREAMEVENT.LOCAL_STREAM_ADDED
wsc.MEDIASTREAMEVENT.REMOTE_STREAM_ADDED
Example 9-13 shows the basic logic for handling Flash-based media streams in the onMediaStreamEvent event handler.
Example 9-13 Handling Flash Media Events
function onMediaStreamEvent (mediaEvent, stream) { console.log ("onMediaStreamEvent: " + mediaEvent.toString ()); if (mediaEvent == wsc.MEDIASTREAMEVENT.LOCAL_STREAM_ADDED) { console.log ("Handling local stream added event..."); if (typeof flashCallPackage != 'undefined' && stream && stream instanceof wsc_flash.wscFlash.FlashMediaStream) { console.log ("Local flash video stream added..."); // Set up the application UI as required... } } else if (mediaEvent == wsc.MEDIASTREAMEVENT.REMOTE_STREAM_ADDED) { console.log ("Handling remote stream added event..."); if (typeof flashCallPackage != 'undefined' && stream && stream instanceof wsc_flash.wscFlash.FlashMediaStream) { console.log (Remote flash video stream added..."); // Set up the application UI as required... } } }
Note:
If a non-IE Web browser is initiating a WebRTC call to an IE Web browser, only audio is supported. The reverse is also true, unless the non-IE browser answers the call using the Flash extension itself.For more information on handling incoming audio calls, see Chapter 4, "Setting Up Audio Calls in Your Applications." For more information on handling incoming video calls, see Chapter 5, "Setting Up Video Calls in Your Applications."
Example 9-14 shows a simple function that returns whether a call is a Flash-based call by examining the CallPackage's packageType instance variable.