Webex Teams Space Widget (@ciscospark/widget-space)

The Webex Teams Space Widget allows developers to easily incorporate Cisco Webex Teams (formerly Cisco Spark) activities into an application.

Background

This widget handles coordination between your application and the Webex Teams APIs, and provides components of the Webex Teams space experience without having to build all of the front end UI yourself.

Our widget is built using React, Redux, and the Webex Teams JavaScript SDK.

This widget supports:

1 on 1 and group space messaging
1 on 1 and group space video calling
Space Roster list and @mentions
Dialing by email address or SIP address
Inline Markdown
Sharing of files and documents
Previewing and downloading of files and documents
Flagging messages for follow up

Install

Depending on how comfortable you are with these frameworks, there are are a number of ways you can "install" our code.

Webex for Developers

If you haven't already, go to Cisco Webex for Developers (https://developer.webex.com) and sign up for an account. Once you've created an account you can get your developer access here.

When you want to eventually create an integration and have your own users take advantage of the widget, you'll need to create an integration with the spark:all scope.

Head over to the Webex for Developers Documentation for more information about how to setup OAuth for your app: https://developer.webex.com/authentication.html

CDN

Using our CDN requires the least amount of work to get started. Add the following into your HTML file:

<!-- Latest compiled and minified CSS -->
<link rel="stylesheet" href="https://code.s4d.io/widget-space/production/main.css">

<!-- Latest compiled and minified JavaScript -->
<script src="https://code.s4d.io/widget-space/production/bundle.js"></script>

For the latest builds that are pulled from the head of the master branch:

<!-- Latest compiled and minified CSS -->
<link rel="stylesheet" href="https://code.s4d.io/widget-space/latest/main.css">

<!-- Latest compiled and minified JavaScript -->
<script src="https://code.s4d.io/widget-space/latest/bundle.js"></script>

Build from Source

Follow these instructions to checkout and build the react-ciscospark repo https://github.com/webex/react-ciscospark/blob/master/README.md
To build the Space Widget, run the following from the root directory:

npm run build:package widget-space

Usage

Quick Start

If you would just like to get running immediately, follow these instructions to get a webpack-dev-server running with the widget.

Create a .env file in the root of the React project with the following lines, replacing the Xs with the appropriate value:
```
CISCOSPARK_ACCESS_TOKEN=XXXXXXXXXXXXXXX
SPACE_ID=XXXXXXXXXXXXXXX
TO_PERSON_EMAIL=XXXXX@XXXXXXXXX
```
From the root directory run: npm run start:package widget-space

Configuration

When loading the widgets there are some configuration options you can provide:

Authentication methods:

Name	Data API	Description
`accessToken`	`data-access-token`	Access token for the user account initiating the messaging session. For testing purposes you can use a developer access token from https://developer.webex.com.
`guestToken`	`data-guest-token`	Guest Access token for the user account initiating the messaging session. A guest issuer application is required to generate a guest token. https://developer.webex.com/guest-issuer.html. Currently in restricted access

Widget destination:

Name	Data API	Description
`destinationId`	`data-destination-id`	Space ID/email/user id of the space you want to open.
`destinationType`	`data-destination-type`	Type of space destination, one of: `email`, `userId`, `spaceId`, `sip`

Optional configurations:

Name	Data API	Description
`initialActivity`	`data-initial-activity`	(default: `message`) Activity view to open with the widget. Available options: `message`: Message view `meet`: Meet view
`startCall`	`data-start-call`	(default: `false`) When present, widget will start in Meet view and initiate a call with the toPerson immediately.
`logLevel`	`data-log-level`	(default: `silent`) When present, widget will log debug information to console. This can be set to: `error`, `warn`, `debug`, `info`, `trace`, or `silent`
`spaceActivities`	N/A: global only feature	(default: `spaceActivities: {files: true, meet: true, message: true, people: true}`). When present and a property is set to false, that activity will be disabled in the activities menu. Disabling the initial activity will result in an error.

These properties have been deprecated:

Name	Data API	Description
`spaceId`	`data-space-id`	ID of the space you want to open.
`toPersonEmail`	`data-to-person-email`	Email of the message recipient
`toPersonId`	`data-to-person-id`	User Id of the message recipient

HTML

The easiest way to get the Webex Teams Space Widget into your web site is to add the built resources and attach data attributes to your a container.

If you're using our CDN, skip to the next section.

Copy the resources in the dist directory to own project.
Add a <script /> tag to your page to include the bundle.js
Add a <link /> tag to include main.css

Browser

Create an Express web application to serve the Space Widget. This is the preferred method to enable CORS.

If you're loading an HTML file directly in the browser, use Firefox or start Chrome with the --allow-file-access-from-files flag. This is not preferred because it introduces a security risk.

open -a "Google Chrome" --args --allow-file-access-from-files

Browser Globals

If you need additional behaviors or need to do additional work before the widget loads, it may be useful for to programmatically instatiate the widget after the intial page loads.

<div id="my-webexteams-widget" />
<script>
  var widgetEl = document.getElementById('my-webexteams-widget');
  // Init a new widget
  ciscospark.widget(widgetEl).spaceWidget({
    accessToken: 'AN_ACCESS_TOKEN',
    destinationType: 'spaceId',
    destinationId: 'XXXXXXXXXXXXXXX'
  });
</script>

my-webexteams-widget is an arbitrary id to illustrate one way to select the DOM element. But please ensure that the widgetEl that you pass to ciscospark.widget() is a DOM element.

You can also attach to an existing widget. Currently this gives you access to events. Other functionality will be added in future releases.

var widgetEl = document.getElementById('webexteams-widget-id');
var widgetObject = ciscospark.widget(widgetEl);

Widget Teardown

When a widget needs to be removed from the page you will want to call the .remove() method. This will close any network connections active and remove the widget from the DOM. You can also pass a callback as a parameter to the .remove() method. The method also returns a Promise that is thenable.

The returned value, removed, is true if a matching widget has been removed, and is false no widget was found.

// Basic remove
ciscospark.widget(widgetEl).remove();

// With callback
ciscospark.widget(widgetEl).remove(function(removed) {
  if (removed) {
    console.log('removed!');
  }
});

// With Promise
ciscospark.widget(widgetEl).remove().then(function(removed) {
  if (removed) {
    console.log('removed!');
  }
});

NOTE: If you are also using the Webex Teams JS SDK on the same page, please be sure to load that before you load the widget scripts.

Data API

If you would like to embed with the widget without any additional behaviors into your page, use this data api. The div containing our data-toggle attribute must exist on the page before our JavaScript bundle loads.

Create a container where you would like to embed the widget and use the configuration options to load the widget. Be sure to include data-toggle="ciscospark-space".

<div
  class="webexteams-widget"
  data-toggle="ciscospark-space"
  data-access-token="AN_ACCESS_TOKEN"
  data-destination-id="XXXXXXXXXXXXXXX"
  data-destination-type="spaceId"
  />

Events

The Space widget exposes a few events for hooking into widget functionality. You can directly add DOM event listener like this:

<div
  class="webexteams-widget"
  data-toggle="ciscospark-space"
  data-access-token="AN_ACCESS_TOKEN"
  data-destination-id="XXXXXXXXXXXXXXX"
  data-destination-type="spaceId"
  />
<script>
  document.getElementById('webexteams-widget').addEventListener('EVENT_NAME', function(event) {
    // Handle the event here
    console.log(event.detail);
  });
</script>

If you are using browser globals, you can provide a callback parameter that will fire whenever any event occurs. You can filter the actions using the name provided like this:

var widgetEl = document.getElementById('my-webexteams-widget');
// Init a new widget
ciscospark.widget(widgetEl).spaceWidget({
  accessToken: 'AN_ACCESS_TOKEN',
  destinationId: 'XXXXXXXXXXXXXXX',
  destinationType: 'spaceId',
  onEvent: callback
});

function callback(name, detail) {
  if (name === 'messages:created') {
    // Perform an action if a new message has been created
  }
}

Or you can use the ampersand-events API to listen to events like this:

var widgetEl = document.getElementById('webexteams-widget');
ciscospark.widget(widgetEl).on('messages:created', function(e) {
  console.log(e.detail);
});

All available events are outlined in our events guide.

Browser Support

This widget has been tested on the following browsers for messaging and meeting:

Current release of Chrome
Current release of Firefox

More Examples

Webex Teams Spark Widgets Samples

Contribute

Please see CONTRIBUTING.md for more details.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Webex Teams Space Widget (@ciscospark/widget-space)

Table of Contents

Background

Install

Webex for Developers

CDN

Build from Source

Usage

Quick Start

Configuration

HTML

Browser

Browser Globals

Widget Teardown

Data API

Events

Browser Support

More Examples

Contribute

License

Files

README.md

Latest commit

History

README.md

File metadata and controls

Webex Teams Space Widget (@ciscospark/widget-space)

Table of Contents

Background

Install

Webex for Developers

CDN

Build from Source

Usage

Quick Start

Configuration

HTML

Browser

Browser Globals

Widget Teardown

Data API

Events

Browser Support

More Examples

Contribute

License