Spark Base Widget (@ciscospark/spark-widget-base)

This base React component does the initial React, Spark authentication, and Redux setup for all Spark widgets.

Usage

There are a number of ways to use our spark-widget-base repo to begin developing your own widget on the Cisco Spark platform.

IMPORTANT NOTE: In order to authenticate to Spark, the resulting components require an accessToken or guestToken prop that you must provide when instantiating your widget. Please see the Authentication Section

Quick Start

To automatically setup Cisco Spark connections, and register your widget into the global browser store, you can use the sparkWidgetBase enhancer like so:

import sparkWidgetBase from '@ciscospark/spark-widget-base';

function MyWidget(props) {
  return <div>My Widget</div>;
}


export default sparkWidgetBase('myWidget', MyWidget);

Widgets using Redux

If you are also using redux for state management and want to provide your own reducers, import and use the constructSparkEnhancer higher order component instead:

import React, {Component} from 'react';
import {constructSparkEnhancer} from '@ciscospark/spark-widget-base';

import reducers from './reducer';

class MyWidget extends Component {
  render() {
    return <div>My Widget's name is {this.props.displayName}</div>
  }
}

export default constructSparkEnhancer({
  name: 'myWidget',
  reducers
})(MyWidget);

By constructing your component like this, the constructor will combine your reducers with internal spark reducers and update your store with a react-redux <Provider />. This will allow you to connect() any child components and gain access to the store.

Authentication

In order to authenticate to Spark, you must provide the resulting React Components with an accessToken prop. This can be done programatically like so:

import MyWidget from './MyWidget';

class MyApp extends Component {
  render() {
    return <MyWidget accessToken={this.getState().accessToken} />;
  }
}

The widgets also support guest tokens in the form of JWT. To provide a guest token to authenticate, use the guestToken prop.

SDK Instance

In addition to accessToken or guestToken, the widgets can accept the property sdkInstance. This is a Webex SDK instance that has already been created and authenticated. The SDK requires certain plugins to be loaded in order for the widgets to function properly:

• authorization
• logger
• meetings
• people
• phone
• rooms
• internal.conversation
• internal.feature
• internal.flag
• internal.mercury
• internal.presence
• internal.search
• internal.team

Advance Usage

When your widget instantiates, it will get receive props from our main store. Some of the data and functions you will have access to:

• sparkState: an object that will provide you with device registration and authentication states
• sparkInstance: the spark object that is provided by the Webex JS SDK. You can use this object to interact with Webex APIs as the authenticated user.

Additional Enhancers

This package also provides some additional enhancers to make your widget setup a bit easier:

• withInitialState (default): Establishes widget initial states with Redux and injects the React-Redux store Provider component
• withBrowserGlobals (default): Enables widgets to be instantiated globally using window.ciscospark.widget(el).widgetName (usage example)
• withDataAPI (default): Enables widgets to be instantiated using a data API (usage example)
• withIntl: A helper for enabling react-intl in your widget. You can pass a config object that will make intl available to you: {locale: 'en', messages}

To use any of these enhancers you can apply them directly to a Component: withIntl(MyComponent). Or you can compose them using a libary like recompose:

import {compose} from 'recompose';
import {
  withIntl
} from '@ciscospark/spark-widget-base';
import {MyWidget} from './MyWidget';

const MyWrappedWidget = compose(
  withIntl()
)(MyWidget);