opentok-react

React components for OpenTok.js

Contents

• Pre-Requisites
• Install
• Example App
• Usage
  • Importing opentok-react
  • Example with OTSession Component
  • Example with createSession Helper
• API Reference
  • OTSession Component
  • OTPublisher Component
  • OTStreams Component
  • OTSubscriber Component
  • createSession Helper
  • preloadScript Higher-Order Component
• Custom Build
• Contributing
• Tests

Pre-Requisites

1. NodeJS
2. Register a TokBox account: https://tokbox.com/account/user/signup

Install

Add opentok-react as a dependency of your application:

yarn add opentok-react

Or if you're still using npm:

npm install --save opentok-react

Then include opentok.js before your application:

Alternatively, wrap your top-level component using OpenTok with the preloadScript HOC. The HOC will take care of loading opentok.js for you before rendering.

Example App

There is an example application provided in example/ and you can run it with the following steps:

1. git clone https://github.com/opentok/opentok-react.git
2. cd opentok-react/example/
3. cp config.template.js config.js
4. Edit config.js:
5. Add your OpenTok API key, Session ID and Token (https://tokbox.com/account/)
6. Add your Chrome Extension ID (https://tokbox.com/developer/guides/screen-sharing/js/)
7. cd ..
8. yarn (or npm install)
9. npm run example
10. Visit https://localhost:8000 in your browser

Refer to the App.js, Publisher.js and Subscriber.js files in example/components/ for library usage.

Usage

The following sections explains how to import and use opentok-react in your React application.

Importing opentok-react

Import the opentok-react components into your React application:

import { OTSession, OTPublisher, OTStreams, OTSubscriber } from 'opentok-react';

Or require it if you need to use CommonJS modules:

const { OTSession, OTPublisher, OTStreams, OTSubscriber } = require('opentok-react');

Example with OTSession Component

class MyApp extends React.Component {
  render() {
    return (
      
        
        
          
        
      
    );
  }
}

Example with createSession Helper

class MyApp extends React.Component {
  constructor(props) {
    super(props);
    this.state = { streams: [] };
  }

  componentWillMount() {
    this.sessionHelper = createSession({
      apiKey: 'your-api-key',
      sessionId: 'your-session-id',
      token: 'your-session-token',
      onStreamsUpdated: streams => { this.setState({ streams }); }
    });
  }

  componentWillUnmount() {
    this.sessionHelper.disconnect();
  }

  render() {
    return (
      <div>
        

        {this.state.streams.map(stream =&gt; {
          return (
            
          );
        })}
      </div>
    );
  }
}

API Reference

The opentok-react library comprises of:

• OTSession Component
• OTPublisher Component
• OTStreams Component
• OTSubscriber Component
• createSession Helper
• preloadScript Higher-Order Component

OTSession Component

The OTSession component manages the connection to an OpenTok Session. It passes the Session instance as the session prop to its child components. It is recommended that you nest OTPublisher and OTStreams inside OTSession:

OTPublisher Component

The OTPublisher component will initialise a publisher and publish to a specified session upon mounting. It will also ensure the Publisher video element is attached to the DOM inside the component rather than appending to the body (which is the Publisher's default behaviour).

If you are not using OTSession then you must specify a Session object using the session prop.

Use the properties prop to specify a properties object for OT.initPublisher and the eventHandlers prop to specify an object of event handlers for Publisher#on.

class MyApp extends React.Component {
  constructor(props) {
    super(props);

    this.publisherProperties = {
      audioFallbackEnabled: false,
      showControls: false
    };

    this.publisherEventHandlers = {
      streamCreated: event => {
        console.log('Publisher stream created!');
      },
      streamDestroyed: event => {
        console.log('Publisher stream destroyed!');
      }
    };
  }

  render() {
    return (
      
        
      
    );
  }
}

The properties prop is used for initial set up of the Publisher and making changes to it will not update the Publisher, you will instead need to invoke Publisher methods. To facilitate this the Publisher instance is exposed via the getPublisher() component method. You should always call this method to get the latest Publisher instance instead of keeping a reference to it as it's possible for the Publisher instance to change, leaving you with a stale reference.

However, for convenience the OTPublisher does watch for changes on a few keys of the properties object and makes the necessary changes. Currently these are:

There are plans to support more Publisher properties but for now you will have to call getPublisher() to retrieve the Publisher instance and make the necessary changes yourself.

You can also get access to the publisher object by calling the getPublisher method using a Ref. For example:

class MyApp extends React.Component {
  constructor(props) {
    super(props);
    this.state = {
      publisher: null,
    };
    this.otPublisher = React.createRef();
  }

  componentDidMount() {
    this.getPublisher();
  }

  getPublisher() {
    if (this.otPublisher) {
      this.setState({
        publisher: this.otPublisher.current.getPublisher(),
      });
    }
  }

  render() {
    return (
      
        
      
    );
  }
}

OTStreams Component

OTSubscriber Component

The OTSubscriber component will subscribe to a specified stream from a specified session upon mounting. It will also ensure the Subscriber video element is attached to the DOM inside the component rather than appending to the body (which is the Subscriber's default behaviour).

If you are not using OTStreams then you must provide a Stream object using the stream prop and a Session object using the session prop.

{this.sessionHelper.streams.map(stream => (
  
))}

Use the properties prop to specify a properties object for session.subscribe and the eventHandlers prop to specify an object of event handlers for Subscriber#on.

class MyApp extends React.Component {
  constructor(props) {
    super(props);

    this.subscriberProperties = {
      preferredFrameRate: 15,
      showControls: false
    };

    this.subscriberEventHandlers = {
      videoDisabled: event => {
        console.log('Subscriber video disabled!');
      },
      videoEnabled: event => {
        console.log('Subscriber video enabled!');
      }
    };
  }

  render() {
    return (
      
        
          
        
      
    );
  }
}

The properties prop is used for initial set up of the Subscriber and making changes to it will not update the Subscriber, you will instead need to invoke Subscriber methods. To facilitate this the Subscriber instance is exposed via the getSubscriber() component method. You should always call this method to get the latest Subscriber instance instead of keeping a reference to it as it's possible for the Subscriber instance to change, leaving you with a stale reference.

However, for convenience the OTSubscriber does watch for changes on a few keys of the properties object and makes the necessary changes. Currently these are:

There are plans to support more Subscriber properties but for now you will have to call getSubscriber() to retrieve the Subscriber instance and make the necessary changes yourself.

You can also get access to the subscriber object by calling the getSubscriber method using a Ref. For example:

class MyApp extends React.Component {
  constructor(props) {
    super(props);
    this.state = {
      subscriber: null,
    };
    this.otSubscriber = React.createRef();
  }

  componentDidMount() {
    this.getSubscriber();
  }

  getSubscriber() {
    if (this.otSubscriber) {
      this.setState({
        subscriber: this.otSubscriber.current.getSubscriber(),
      });
    }
  }

  render() {
    return (
      
        
          
        
      
    );
  }
}

createSession Helper

The createSession helper has been provided to easily create a session and monitor the current list of subscriber streams.

class MyApp extends React.Component {
  componentWillMount() {
    this.sessionHelper = createSession({
      apiKey: 'your-api-key',
      sessionId: 'your-session-id',
      token: 'your-session-token',
      onStreamsUpdated: streams => {
        console.log('Current subscriber streams:', streams);
      }
    });
  }

  componentWillUnmount() {
    this.sessionHelper.disconnect();
  }
}

The createSession helper returns an object with the following properties:

• session - The Session instance.
• streams - An up-to-date array of Stream instances.
• disconnect - A clean up function. Call this when your component unmounts.

Use of this helper is optional and you can instead use the OTSession component or directly call OT.initSession and listen to streamCreated events if you prefer.

preloadScript Higher-Order Component

In larger applications, one might not want to load the opentok.js client with a `