Initialization

Loading Web SDK from CDN

Before Web SDK can be used it should be loaded and initialized. Since Web SDK is a javascript library it can be loaded using standard HTML code for embedding javascript library into a web page (usually it's added somewhere before closing HEAD tag):

<script type="text/javascript" src="//cdn.voximplant.com/voximplant.min.js"></script>

Getting started with VoxImplant.Client singleton

VoxImplant.Client is a Singleton class and the main class of the SDK that provides access to VoxImplant's functions, getInstance function is used to receive its instance as shown below:

var voximplant = VoxImplant.getInstance();

After VoxImplant javascript library has been loaded it should be initialized using init function before any other function of the SDK can be used. VoxImplant.Config instance can be passed to the init function as an optional parameter. It lets you specify some of the SDK settings. VoxImplant.Events.SDKReady event will be dispatched after the SDK has been successfully initialized. Please see the following example:

  1. var voximplant = VoxImplant.getInstance();
  2. voximplant.addEventListener(VoxImplant.Events.SDKReady, handleSDKReady);
  3. function handleSDKReady() {
  4. // SDK initialized, connect function can be used now for a connection to the VoxImplant Cloud
  5. voximplant.connect();
  6. }
  7. voximplant.init();

Connect function is used in SDKReady handler to establish data connection between browser and the VoxImplant Cloud. In the similar manner developer should add the following event listeners: VoxImplant.Events.ConnectionEstablished , VoxImplant.Events.ConnectionFailed , and VoxImplant.Events.ConnectionClosed to handle connection events.

  1. voximplant.addEventListener(VoxImplant.Events.ConnectionEstablished, onConnectionEstablished);
  2. voximplant.addEventListener(VoxImplant.Events.ConnectionFailed, onConnectionFailed);
  3. voximplant.addEventListener(VoxImplant.Events.ConnectionClosed, onConnectionClosed);
  4. function onConnectionEstablished() {
  5. // connection was established successfully
  6. }
  7. function onConnectionFailed() {
  8. // connection failed
  9. }
  10. function onConnectionClosed() {
  11. // connection was closed
  12. }

The last thing that should be done before call functions become available after the connection has been established is authorization: the Application User's username and password should be passed to login function. VoxImplant.Events.AuthResult event is used to notify about the login result.

  1. voximplant.addEventListener(VoxImplant.Events.AuthResult, onAuthResult);
  2. function onAuthResult(event) {
  3. if (event.result) {
  4. // Successful authorization
  5. } else {
  6. // Authorization failed
  7. }
  8. }

Using VoxImplant.Config to specify SDK settings during the initialization

There are number of settings that can be specified while the SDK initialization, let's review them all one-by-one:

  • useFlashOnly - force SDK to use Flash mode even if WebRTC is available. In some scenarios you want to use Flash instead of WebRTC even in the browsers that support WebRTC and setting useFlashOnly to true will do the trick.
  • useRTCOnly - same, as previous setting, but to force WebRTC mode. If WebRTC is not available SDK will throw the exception.
  • micRequired - if set to true, SDK will show microphone access dialog right after the initialization of the SDK. VoxImplant.Events.MicAccessResult event will be dispatched after user allowed or denied access to the microphone.
  • videoSupport - can be used to enable video calls support (for Flash mode only for now)
  • swfContainer - lets developer specify the Id of HTMLElement that will be used as container for Flash component of SDK (Mic/cam access dialog will appear in the container). If micRequired set to true element should have size not less than 215x138 (px) for access dialog to be shown. Be default, if swfContainer isn't specified, Flash component will be in the HTMLElement with id "voximplantcontainer".
  • progressToneCounry - Country code in ISO format for progress tone generated automatically if progressTone set to true. Has "US" value by default.
  • progressTone - Automatically plays progress tone by means of SDK according to specified progressToneCountry if set to true.

    Please note that SDK currently supports only US and Russian progress tones generated automatically. We will add other countries soon. Meanwhile you can use browser-based audio playback capabilities for that purpose.

The following example shows how the settings can be passed to init function:

voximplant.init({ micRequired: true, progressTone: true, progressToneCountry: "US" });