Package Exports

react-use-opentok

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (react-use-opentok) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

react-use-opentok

React Hook for conveniently use @opentok/client SDK.

Pre-requirement

Demo

See our demo site: react-use-opentok

react-use-opentok

Installation

Install it with npm:

npm i @opentok/client@2.x react-use-opentok

Or with yarn:

yarn add @opentok/client@2.x react-use-opentok

NOTE: remember to install the peer dependency of @opentok/client

Getting Started

Get utilities from useOpenTok hook
Fetch apiKey, sessionId, and token from server
Connect to session with token

import React, { useEffect } from 'react';
import useOpenTok from 'react-use-opentok';

const Component = () => {
  // STEP 1: get utilities from useOpenTok;
  const [opentokProps, opentokMethods] = useOpenTok();

  const {
    // connection info
    connectionId,
    isSessionConnected,

    // connected data
    session,
    connections,
    streams,
    subscribers,
    publisher,
  } = opentokProps;

  const {
    initSessionAndConnect,
    disconnectSession,
    publish,
    unpublish,
    subscribe,
    unsubscribe,
    sendSignal,
  } = opentokMethods;

  // STEP 2: Mockup fetching apiKey, sessionId, and token from server
  useEffect(() => {
    fetch('<get credentials from server>').then(
      ({ apiKey, sessionId, token }) => {
        initSessionAndConnect({
          apiKey,
          sessionId,
          token,
        });
      }
    );
  }, [initSessionAndConnect]);

  return <div>...</div>;
};

export default Component;

Guide

Get all utilities from useOpenTok Hook

You can get all utilities from useOpenTok hook.

const [opentokProps, opentokMethods] = useOpenTok();

const {
  // connection info
  connectionId,
  isSessionConnected,

  // connected data
  session,
  connections,
  streams,
  subscribers,
  publisher,
} = opentokProps;

const {
  initSessionAndConnect,
  disconnectSession,
  publish,
  unpublish,
  subscribe,
  unsubscribe,
  sendSignal,
} = opentokMethods;

Connect and disconnect to session

Before starting use openTok session object, remember to initialize session with apiKey and sessionId by initSessionAndConnect method:

const [opentokProps, opentokMethods] = useOpenTok();
const { initSessionAndConnect } = opentokMethods;

// apiKey, sessionId, and token could get from your server or tokbox dashboard
initSessionAndConnect({
  apiKey,
  sessionId,
  token,
});

After connect to session, you can get the session, connectionId , isSessionConnected, and connections properties from opentokProps:

session: a session object from OT.initSession()
connectionId: your own connectionId
isSessionConnected: whether you are connected to the session
connections: all connections in the session

const [opentokProps, opentokMethods] = useOpenTok();
const { session, connectionId, isSessionConnected, connections } = opentokProps;

By disconnectSession, you can disconnect from the session:

const [opentokProps, opentokMethods] = useOpenTok();
const { disconnectSession } = opentokMethods;

disconnectSession();

Publish and unpublished stream to the session

You can publish stream from camera or screen to session through the publish method.

name: should be unique every time you invoke publish method which is for unpublish stream later.
element: should be a DOM element or the id attribute of the existing DOM element.
options: (optional) other optional properties which will pass into OT.initPublisher.

const [opentokProps, opentokMethods] = useOpenTok();
const { publish } = opentokMethods;

// publish stream from the camera
publish({
  name: 'camera',
  element: 'camera',
});

// publish stream from screen sharing
publish({
  name: 'screen',
  element: 'screen',
  options: {
    insertMode: 'append',
    width: '100%',
    height: '100%',
    videoSource: 'screen',
  },
});

According to the name you publish, you could use the same name to unpublish it:

const [opentokProps, opentokMethods] = useOpenTok();
const { unpublish } = opentokMethods;

// unpublish stream from the name 'camera'
unpublish({ name: 'camera' }

You can get all streams in the session through streams property in opentokProps. After finding the stream for subscribing, use the subscribe method to subscribe to the stream:

stream: the Stream Object wanted to subscribe
element: should be a DOM element or the id attribute of the existing DOM element.

const [opentokProps, opentokMethods] = useOpenTok();
const { streams } = opentokProps;
const { subscribe } = opentokMethods;

const streamToSubscribe = streams[0];
subscribe({ stream: streamToSubscribe, element: 'subscriber' });

For each stream be subscribed, a subscriber object will be created and save as subscribers in opentokProps:

const [opentokProps, opentokMethods] = useOpenTok();
const { streams, subscribers } = opentokProps;

You can stop subscribing the stream with unsubscribe method:

const [opentokProps, opentokMethods] = useOpenTok();
const { unsubscribe } = opentokMethods;

const streamToUnsubscribe = streams[0];
unsubscribe({ stream: streamToUnsubscribe });

Send signal

You can send signal in session with sendSignal method:

const [opentokProps, opentokMethods] = useOpenTok();
const { sendSignal } = opentokMethods;

sendSignal({
  type: 'foo',
  data: 'bar',
});

Register session events

You could register all valid session events on session object. Take registering signal event, as an example, use the session object in opentokProps, register the session event with on, and unregister the event with off:

const [opentokProps, opentokMethods] = useOpenTok();
const { session } = opentokProps;

const handleSignal = useCallback(e => {
  console.log('handleSignal', e);
}, []);

useEffect(() => {
  if (!isSessionConnected) {
    return;
  }

  session.on('signal', handleSignal);
  return () => {
    session.off('signal', handleSignal);
  };
}, [handleSignal, isSessionConnected, session]);

NOTICE: for sessionDisconnected event, you can you session.once('sessionDisconnected', <eventHandler>)

Development

for react-use-opentok package

$ npm install
$ npm start         # rollup will watch the files change
$ npm build         # rollup will build the package
$ npm test

for example site

$ cd site
$ npm install
$ npm start         # start gatsby develop server

Contributors

Thanks goes to these wonderful people (emoji key):

_andyyou
💻 🎨 💡 🚧 🤔 👀

_PJCHENder
💻 📖 ⚠️ 💡 🚧 👀

This project follows the all-contributors specification. Contributions of any kind welcome!

LICENSE

MIT