Cisco Spark

SDK for Browsers

Integrate Cisco Spark calling into your client-side JavaScript applications quickly

Features

Integrate the Browser SDK in client-side JavaScript applications. Place and receive video calls via the SDK:

  • 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
Getting Started Guide

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

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

Overview

  • Create a Node.js project with the Browser SDK
  • Make a Cisco Spark call

Requirements

  • Node.js LTS 6.x and later, npm 3.x and later
  • Optionally: nvm to manage Node.js versions

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. npm 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.

Install Browserify

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');

Bundle the SDK

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.

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>Spark Call Quick Start</title>
  <body>
    <h1>Calling Quick Start</h1>
    <p>This sample demonstrates how to place a call using Spark 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 CiscoSpark 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 Cisco Spark

For this example, we'll use your personal OAuth development token from the Spark for Developers portal. This token provides access to your account for testing purposes, and shouldn't be used for anything other than testing. If you're logged into this site, you can see your token by clicking on your avatar in the top right corner of this page. If you don't already have a Cisco Spark account, click Sign Up to create an account.

Authenticate with Cisco Spark

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 Cisco Spark, 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 Cisco Spark Cloud

We'll need to register with the Cisco Spark 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 Cisco Spark's Browser SDK!

To view the entire example of the code we have used here to place a single party call, see our Cisco Spark GitHub page.

Browser SDK Samples

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:

Sample Description Live Demo Sample Code
Single Party Call Make or receive 1:1 video calls with another Cisco Spark user Demo JS | HTML
Troubleshooting the Browser SDK

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
  • A Cisco Spark 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 Cisco Spark's endpoints. For more information about the network and web security requirements for Cisco Spark services, please see this Cisco Spark help article.

Getting Support

If you're stumped, contact Cisco Spark's DevSupport team for more help with the SDK.