react-use-opentok

    2.3.1 • Public • Published

    react-use-opentok

    Build status version Coverage Status license All Contributors

    React Hook for conveniently use @opentok/client SDK.

    Pre-requirement

    • Register Opentok to get authentication.

    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

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


    andyyou

    💻 🎨 💡 🚧 🤔 👀

    PJCHENder

    💻 📖 ⚠️ 💡 🚧 👀

    Maximillian Rink

    💻

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

    LICENSE

    MIT

    Install

    npm i react-use-opentok

    DownloadsWeekly Downloads

    262

    Version

    2.3.1

    License

    MIT

    Unpacked Size

    123 kB

    Total Files

    10

    Last publish

    Collaborators

    • andyyou
    • pjchender