react-use-opentok v2.3.1

react-use-opentok

React Hook for conveniently use @opentok/client SDK.

Pre-requirement

• Register Opentok to get authentication.

Demo

See our demo site: 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

1. Get utilities from useOpenTok hook
2. Fetch apiKey, sessionId, and token from server
3. 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
    isSessionInitialized,
    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
  isSessionInitialized,
  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,
});

This methods will first initialize the session object, and continue connected to the session.

After session initialized, the value of isSessionInitialized will be `true.

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

If you want to control the process of session initialization and connect to session on your own, check the method initSession({ apiKey, sessionId, sessionOptions }) and connectSession({token, sessionToConnect }).

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

// publish support Promise way to catch errors
publish({
  name: 'camera',
  element: 'camera',
}).catch((ex) => {
  console.log(ex);
});

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' }

Subscribe and Unsubscribe

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

(Optional) Preview Solution

You may want to split OT.initPublisher and session.publish and invoke it in different stage. To solve the requirement you can use initPublisher and publishPublisher instead. If you need to cancel preview you can use removePublisher as well.

NOTE:

• initPublisher - Same with OT.initPublisher but support state which means you can access publisher.
• removePublisher - The method can only remove publisher without publish. Once you publish the publisher you should use unpublish instead.
• publishPublisher - Publish for initPublisher.

initPublisher + publishPublisher = publish

For example:

const Component = () => {
  const [opentokProps, opentokMethods] = useOpenTok();

  const {
    initPublisher,
    publishPublisher,
    removePublisher,
  } = opentokMethods;

  // ...

  const onInitPublisher = () => {
    initPublisher({
      name: 'guest',
      element: 'guest',
      options: {
        insertMode: 'append',
        width: '480px',
        height: '360px',
      },
    });
  };
  const onPublishPublisher = () => {
    publishPublisher({
      name: 'guest',
    });
  };
  const onRemovePublisher = () => {
    removePublisher({
      name: 'guest',
    });
  };

  return (
    <div>
      <div id="guest"></div>
      <div>
        <button onClick={onInitPublisher}>Init Publisher without publish</button>
        <button onClick={onRemovePublisher}>Remove Publisher before publish</button>
        <button onClick={onPublishPublisher}>Publish Publisher</button>
      </div>
    </div>
  );
}

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):

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

LICENSE

MIT