Browser SDK

anchorFeatures
anchor
  • Audio and/or video 1:1 calling
  • Group space calling new
  • Dial by email address, SIP address, or PSTN number new
  • Call and event controls
  • Audio and video call control
  • Maximum bandwidth controls new
  • View shared content new
  • Share screen from Firefox new
  • Share application from Firefox new
anchorGetting Started
anchor

In this example, we'll use Node.js to create a simple JavaScript web app that will make a single party call using Webex Teams.

If you're interested in interfacing with Webex Teams from your backend Node.js applications, check out the Node.js SDK.

In this guide, we'll create a Node.js project with the Browser SDK and make a Webex Teams call.

Requirements
  • Node.js LTS 6.x and later, npm 3.x and later
  • Optionally: nvm to manage Node.js versions
  • Supported Desktop Browsers: Chrome (latest), Firefox (latest), and Safari (latest)
Step 1: Create the New Project & Install the SDK
  1. First, create the project directory and change directories into it, as shown below:

     mkdir sample-browser-single-party-call
     cd sample-browser-single-party-call
  2. Next, create a new project by using the node package manager (npm) to create a package.json file for your project:

     npm init

    You'll be asked several questions to initially configure the project. The npm init command will create a package.json file based on the options you select. The default settings will usually be good enough.

  3. Install ciscospark and save it to your package.json file, as shown below:

     npm install --save ciscospark
Step 2: Bundle/Compile the SDK

In this example we'll use Browserify to build the SDK and bundle it for use in our web app. We'll link the SDK via a <script> tag in our app.

First, let's add Browserify to our project:

npm install --save-dev browserify

Next, let's create the a JavaScript file in our app to load the SDK: index.js. At the top of the file, require the ciscospark module:

window.ciscospark = require('ciscospark');

To use the SDK in our web app, we'll need to bundle it into a file that can be used via a <script> tag in our app. Use the bundle command to include the SDK in a file called bundle.js. We'll include this file in our web app to use the SDK.

./node_modules/.bin/browserify index.js > bundle.js
Step 3: Create HTML for App

For this app, we'll create a very simple HTML file to load the SDK, provide a form to specify who we'll call, and buttons to dial and hangup. We'll wire up this form in JavaScript to make a call! Create a file called index.html in the root of the project directory with the following contents:

<!DOCTYPE html>
<html>
  <title>Webex Teams Call Quick Start</title>
  <body>
    <h1>Calling Quick Start</h1>
    <p>This sample demonstrates how to place a call using Webex Teams in the browser.</p>

    <form id="dialer">
      <input
        id="invitee"
        name="invitee"
        placeholder="Person ID or Email Address or SIP URI or Room ID"
        type="text">
        <input title="dial" type="submit" value="dial">
    </form>

    <div style="display: flex">
      <video style="width:50%" id="self-view" muted autoplay></video>
      <video style="width:50%" id="remote-view" autoplay></video>
    </div>

    <button id="hangup" title="hangup" type="button">cancel/hangup</button>

    <!-- /bundle.js is the bundled Webex Teams Browser SDK -->
    <script src="/bundle.js"></script>
    <!-- app.js is your application code -->
    <script src="app.js"></script>
  </body>
</html>
Step 4: Authenticate App with Webex Teams

For this example, we'll use your personal access token which can be found in Getting Started if you're logged in. This token provides access to your account for testing purposes, and shouldn't be used for anything other than testing. If you don't already have a Webex Teams account, click Sign Up at the top of this page to create a new account.

Authenticate with Webex Teams

Create a new file called app.js. This file will have the main application logic for the web app. At the top, add this code to authenticate with Webex Teams, replacing YOUR_ACCESS_TOKEN with your development token:

spark = ciscospark.init({
  credentials: {
    access_token: `YOUR_ACCESS_TOKEN`
  }
});
Step 5: Create JavaScript App

All of the calling functionality for this app will live in our app's main JavaScript file, app.js. We'll wire it up to our HTML file to make the call.

Register with Webex Teams Cloud

We'll need to register with the Webex Teams Cloud before attempting to make a call. Add the following code to your app.js file:

spark.phone.register()
.catch((err) => {
  console.error(err);
  alert(err);
  throw err;
});

Set up Event Listeners for Call Events

When we make a call, the SDK will generate several events to keep us informed about the call's progress such as media stream changes, hangups, etc. Let's watch for these events by adding this code:

function bindCallEvents(call) {
  call.on(`error`, (err) => {
    console.error(err);
    alert(err);
  });

  call.once(`localMediaStream:change`, () => {
    document.getElementById(`self-view`).srcObject = call.localMediaStream;
  });

  call.once(`remoteMediaStream:change`, () => {
    document.getElementById(`remote-view`).srcObject = call.remoteMediaStream;
  });

  call.on(`disconnected`, () => {
    document.getElementById(`self-view`).srcObject = document.getElementById(`remote-view`).srcObject = undefined;
    call = undefined;
  });

We'll also want to know if we click the hangup button. Add a listener for the hangup button:

document.getElementById(`hangup`).addEventListener(`click`, () => {
  call.hangup();
});
}

Set up Event Listener for the Dial Button

In our simple HTML page, we added a form with a few buttons to start and end the call. Let's add an event listener to initiate the call when the dial button is clicked:

document.getElementById(`dialer`).addEventListener(`submit`, (event) => {
  event.preventDefault();

  const call = spark.phone.dial(document.getElementById(`invitee`).value);

  bindCallEvents(call);
});

Now, when we click dial, we'll use the SDK's phone.dial instance method to start the call.

Step 6: Load the Web App

Let's load the web app in our browser to make a call! First, install and start a simple web server (httpster) to serve our web app.

npm install -g httpster
httpster

By default, httpster will listen on port 3333. Open the app (http://localhost:3333) in your browser to use your new web app! Enter the Person ID or email address of who you want to call and click the dial button. Congratulations, you've made your first call in the browser using Webex Teams's Browser SDK!

To see the full example code we have used here to place a single party call, check out the sample app in GitHub.

anchorSamples
anchor

We've put together several samples of the Browser SDK in action. All of the sample code is available in GitHub. Take the SDK for a spin with a live demo and check out the sample code:

SampleDescriptionLive DemoSample Code
Single Party CallMake or receive 1:1 video calls with another Webex Teams userDemoJS | HTML
Single Party Call with MuteMake or receive 1:1 video calls with another Webex Teams user, with the option to mute your audio and/or video streamsDemoJS | HTML
Multi Party CallStart or join a Webex Teams video call with multiple participantsDemoJS | HTML
Call with Content SharingMake or receive video calls with the ability to share your screen or an application (Firefox only)DemoJS | HTML
Authentication - Implicit Grant FlowAuthenticate as a Webex Teams user with the Implicit Grant FlowDemoJS | HTML
Authentication - Guest IssuerAuthenticate as a Webex Teams guest user with a Guest Issuer tokenDemoJS | HTML
anchorTroubleshooting
anchor

If you're having trouble with the Browser SDK, here's some more information to help troubleshoot the issue.

SDK Requirements

Review the following SDK requirements to make sure you're using the correct minimum versions of Node.js, npm, etc.:

  • Node.js LTS 6.x and later
  • npm 3.x and later
  • Optionally: nvm to manage Node.js versions
  • Supported Desktop Browsers: Chrome (latest), Firefox (latest), and Safari (latest)
  • A Webex Teams account and an integration with the necessary scopes
Additional Logging

You can add additional logging to your application to help narrow down any issues with the SDK.

Change the Log Level Within Your App

Set the log level to info to see more logging to help troubleshoot the issue:

spark.config.logger.level = `info`;

To see even more logging, set the log level to debug.

Firewall Ports

The Browser SDK makes use of several network protocols and ports. If you're encountering connection or connectivity issues, make sure there aren't any firewalls blocking or preventing communication with any Webex Teams endpoints. For more information about the network and web security requirements for Webex Teams services, please see this Webex Teams help article.

Getting Support

If you're stumped, contact the Webex Developer Support team for more help with the SDK.

Last updated: November 15, 2018