Skip to content

Latest commit

 

History

History
245 lines (153 loc) · 12.5 KB

README.md

File metadata and controls

245 lines (153 loc) · 12.5 KB
Raw

logo

OpenTok Wealth Management Solution
Version 0.1

The Wealth Management Solution widget makes it easy to embed one-to-one communications in a website:

  • Video
  • Audio
  • Text
  • Screen sharing

Requirements

Review the requirements for OpenTok.

The widget supports the following browsers:

  • Chrome 47 or later
  • Firefox 43 or later
  • Internet Explorer 11 (See Known Issues)

Known issues

Number Description
WMS-161 Internet Explorer 11 clients cannot share their screens.

About the contents of the widget ZIP file

Since you are reading this, we assume you have succeeded in obtaining and extracting the widget ZIP file. If you do not have the package and would like it, feel free to reach out to us. This section discusses the contents of the package.

  • sample-app: Contains a sample implementation of the widget.

  • images: Contains image files that the widget needs for its user interface.

  • templates: Contains a base.html file. The widget uses this file for various prompts to the end user.

  • css: Contains a wms-min.css and a themes.css file. See Customizing the widget styles for more information.

  • LICENSE: Contains important legal information describing the terms under which you can use and/or redistribute the widget.

  • demo.html: Use this to get started very quickly or just to view the minimum HTML that the widget needs.

  • wms-min.js: A minified file containing the widget and the libraries that it depends on such as jQuery and Underscore.

Prerequisites

Before continuing further, make sure you have the following:

  • A secure web server: The page containing the widget must be served over HTTPS to allow screen sharing and support clients running Chrome 47 or later. Browser security limitations prevent you from publishing video using a file:// path, as discussed in the OpenTok.js Release Notes. If you do not already have a secure web server, you can use MAMP, XAMPP, or a free cloud service like Heroku.

  • API Key: You can get this by signing up for an OpenTok developer account. It's free for thirty days, no credit card required.

  • Session ID & token: During the test and development phases, you can generate these manually from the OpenTok Developer Dashboard. Before you go into production, you must deploy one of the OpenTok server SDKs to generate these values dynamically. If you do not want to use one of the server SDKs that we provide, you can make calls directly against the OpenTok REST API.

Deploying the widget

Take the following from the ZIP package and upload them to your web server:

  • wms-min.js file
  • wms-min.css file
  • templates directory (contains the file base.html)
  • images directory

Quick start

This procedure will get you a working widget very quickly but you do need Firefox. Before you begin, make sure you have completed the steps in Deploying the widget.

  1. Open the demo.html file using your choice of editor.

  2. Modify the file as indicated in the comments to include the following values:

    • Path to the wms-min.css file
    • Path to the wms-min.js file
    • API key
    • Session ID
    • Token

    NOTE: See the Prerequisites section for more information on these values.

  3. Leave extensionID and extensionPathFF blank.

  4. Save the file and upload it to your web server.

  5. Open a Firefox browser.

  6. Type about:config in the address box.

  7. Click past the warning.

  8. Find the media.getusermedia.screensharing.allowed_domains key.

  9. Add the domain that your widget is hosted on.

    PRO TIP: Prefatory wildcards are supported, e.g., *.tokbox.com

  10. Now visit your hosted demo.html file to see the widget in action!

Enabling production screen sharing

To enable actual users to share screens using the widget, follow the steps discussed in the OpenTok Developer Center.

Adding the widget to an existing web page

  1. Add a script tag to load the wms-min.js file.

    <script src="path/wms-min.js"></script>

  2. Add a link tag to load the wms-min.css file.

    <link rel="stylesheet" href="path/wms-min.css">

  3. Define a container for the widget.

    <div class="container">
<div id="widget_container" style="width:380px; margin:50px auto 0;"></div>
</div>

Initializing the widget

Before you can use the widget, you must initialize it. The widget's init function accepts a single argument: an options object. The options object must contain the following name-value pairs.

Name Required? Value(s)
user Only the id value is required A nested object containing the following name-value pairs: `name:"string",id:NNNN,role:"client"
apiKey Yes Your OpenTok API key (see Prerequisites)
sessionId Yes The session ID (see Prerequisites)
token Yes A token value (see Prerequisites)
onWMSStarted No Define the function to call after a successful initialization of the widget and start of the communications session.
onWMSEnded No Define the function to call after the communications session ends.
onWMSError No Define the function to call if there is an error loading the widget or starting the communications session.
el Yes The widget container element. You can use jQuery for this $("#widget_container"), where widget_container is the id of the container element.
extensionID No To allow a Chrome client to share their screen, you must use this parameter to pass the ID of your Chrome extension. (See Enabling production screen sharing.)
extensionPathFF No If you choose to develop a Firefox screen sharing extension, include the path to the XPI file here. If you have chosen to whitelist your domain with Mozilla instead, leave this blank. (See Enabling production screen sharing.)

The widget needs the required values to function. JavaScript will not complain if they are missing, but the widget will. See the Troubleshooting section for more information.

An example follows.

$(document).ready(function() {
   var options = {
      user:{name:"Justin Smith",id:234,role:"client"},
      apiKey: 45307092,
      sessionId: "1_MZ40WTM5KzA2Ln5-MTP0OTY4MkYzMzY5NH5wMmlHWmJDSkolQ3VKT1F4SlNWQ2toNit-fg",
      token: "T1==cGFydG5lcl9pZD00NTM5NzA2MiZzaWc9OTQ0MDViNWQ5YTM1ZGIzZDY0ZWViNjM3M2MwYjZkMmIyN2FiNzI2ODpyb2xlPW1vZGVyYXRvciZzZXNzaW9uX2lkPTFfTVg0ME5UTTVOekEyTW41LU1UUTBPVFk0TWpZek16WTNOSDV3TW1sSFdtSkRTa2hsUTNWS1QxRjRTbE5OTjJ0b05pdC1mZyZjcmVhdGVfdGltZT0xNDQ5NjgyNzM1Jm8vbmNlPTAuMTU0NzExMDg3MjU2MzI4JmV4cGlyZV90aW1lPTT0NTIyNzQ2MjImY29ubmVjeGlvbl9kYXRhPQ==",
      onWMSStarted: function() { // callbacks 
         console.log('Wealth Management Solution widget STARTED');
      },
      onWMSEnded: function() {
         console.log('Wealth Management Solution widget ENDED');
      },
      onWMSError: function(error) {
         console.log('There is an error loading the Wealth Management Solution widget: ' + error.message);
      },
      el: $("#widget_container"),
      extensionID: "dfhbhhbllmpikonnpddcndmnhjfgnmen"
      extensionPathFF: "your-ff-screensharing-extension.xpi"
   };
   wms.init(options);
});

Customizing the widget styles

To change the visual elements of the widget, create a new CSS file that overrides the styles in wms-min.css. We provide an example of such a file in the ZIP package: themes.css. Because the wms-min.css file is quite long, you may find it easier to refer to themes.css and use this as a starting place for your project.

IMPORTANT: Do not modify the wms-min.css file.

Once you have your new CSS file, upload it to the web server. Then add a link rel tag to your web page. The web page should load your CSS file after the wms-min.css file. An example follows.

<link rel="stylesheet" href="path/wms-min.css">
<link rel="stylesheet" href="path/your-css.css">

Troubleshooting

Reviewing error messages and logs

The widget provides log and error messages within the browser console. The procedure for accessing the console varies per browser.

  • Chrome—open Developer Tools and click Console.
  • Firefox—open Developer Tools and select Web Console.
  • Internet Explorer—press F12 and click Console.

Network connection errors

Error Numbers UI Message Console Message Explanation
1010 You are not connected to the Internet. Check your network connection Error starting a call. Check your network connection. or Error sharing the screen. Check your network connection The user tried to start a call, but has no network connection.
500 Your message cannot be sent. Check your network connection Error sending a message. Check your network connection The user tried to send a text message, but has no network connection.

Widget initialization errors

Error Number Message Explanation
100 Error initializing the Wealth Management Solution Widget: exception message The widget could not be initialized. This can be caused by a failure to load the wms-min.js script, to load the base.html file, or an inability to render the widget.

Screen sharing errors

Error Number Message Explanation
200 Error. You need to indicate a screensharing Chrome extensionID or Error. You need to indicate a screensharing extension for Firefox The widget throws this error when a user tries to share their screen but extensionId was left blank in the init(options) object. Refer to Enabling production screen sharing.
1500, 1550, 1551, 1552, 1553, 1601, 2001 Error sharing the screen The user tried to share their screen, but the widget could not accomplish this. These errors come from the OpenTok platform. Refer to the OpenTok Developer Center for more information, especially the session.publish(...) and OT.initPublisher() sections.

Session connection errors

Error Numbers Message Explanation
1004, 1005, 1006, 1026, 2001 "Error starting the Wealth Management Solution Session: OpenTok error message." The widget was unable to connect to a session. These errors come from the OpenTok platform. Refer to the OpenTok Developer Center for more information.

Messaging errors

Error Numbers Message Explanation
400, 404, 413, 500, 2001 Error sending a message The user tried to send a text message, but the widget could not accomplish this. These errors come from the OpenTok platform. Refer to the OpenTok Developer Center for more information.

INFO: The widget uses JavaScript promises to send text messages and throw errors relating to text messages asynchronously.

Call errors

Error Numbers Message Explanation
1013, 1500, 1553, 1554, 1600, 1601, 2001 Error starting a call The user tried to publish or subscribe to a stream, but the widget could not accomplish this. These errors come from the OpenTok platform. Refer to the OpenTok Developer Center for more information.