Embedding with the Viewer SDK

Installation

npm install @upscopeio/viewer-sdk

React 18 (react and react-dom) are peer dependencies.

Getting a Viewer Token

The SDK authenticates with a viewer token generated by the viewer token endpoint. The token must be requested by your server (the REST API key must never reach the browser) and handed to the browser right before connecting: tokens are short lived, and requesting one creates the Session.

// On your server
const response = await fetch(`https://api.upscope.io/v1.4/visitors/${visitorId}/viewer_token`, {
  body: JSON.stringify({
    viewer: { id: "123", name: "Joe Smith" },
  }),
  headers: {
    "Authorization": `Bearer ${UPSCOPE_API_KEY}`,
    "Content-Type": "application/json",
  },
  method: "POST",
});

// Pass token, endpoint, region and short_id to your frontend
const { endpoint, region, short_id, token } = await response.json();

The response fields map directly onto the ViewerProvider props below. For on-premise accounts, endpoint points at your own on-premise server.

Rendering the Viewer

Wrap your viewer UI in a ViewerProvider, and render the Visitor's screen with the Content component:

import { Content, ViewerProvider, useUpscopeViewer } from "@upscopeio/viewer-sdk";

function CobrowsingViewer({ endpoint, region, shortId, token }) {
  return (
    <ViewerProvider endpoint={endpoint} idleDisconnectSeconds={600} region={region} shortId={shortId} token={token}>
      <Screen />
    </ViewerProvider>
  );
}

function Screen() {
  const { connected, endSession, sessionStatus } = useUpscopeViewer();

  return (
    <div>
      {sessionStatus !== "active" && <p>Waiting for the visitor to accept...</p>}
      <Content color="red" controlTool="cursor" maxHeight={1200} maxWidth={1200} />
      {connected && endSession && <button onClick={() => endSession()}>End session</button>}
    </div>
  );
}

Controlling the Session

Handling Errors

Register an error handler to react to connection and remote control problems:

const { setErrorHandler } = useUpscopeViewer();

useEffect(() => {
  setErrorHandler((error) => {
    if (error === "connection:expired") {
      // Fetch a new viewer token and remount the ViewerProvider
    }
  });
}, [setErrorHandler]);

Audio and Video Calls

Audio and video calls are managed by the AudioProvider and VideoProvider components. Nest them inside the ViewerProvider and use the useAudio and useVideo hooks from components inside them.

Calls are subject to the permissions the token was generated with (allow_audio and allow_video), and video is also configured through the Visitor's SDK, which controls whether it is two way or one way. Audio calls are not available on premise, and viewer tokens for on-premise accounts currently have video calls disabled as well.

import { AudioProvider, CallRingingHandler, VideoFrame, VideoProvider, ViewerProvider } from "@upscopeio/viewer-sdk";

function CobrowsingViewer({ endpoint, region, shortId, token }) {
  return (
    <ViewerProvider endpoint={endpoint} idleDisconnectSeconds={600} region={region} shortId={shortId} token={token}>
      <AudioProvider>
        <VideoProvider i18n={{ requestVideo: "Request video" }}>
          <CallRingingHandler onAudioRinging={promptForCall} onVideoRinging={promptForCall} />
          <VideoFrame />
          <Screen />
        </VideoProvider>
      </AudioProvider>
    </ViewerProvider>
  );
}

import { CallRingingHandler, OnRinging } from "@upscopeio/viewer-sdk";

const promptForCall: OnRinging = (accept) => {
  const dismissPrompt = showIncomingCallPrompt({
    onAccept: () => accept(true),
    onRefuse: () => accept(false),
  });

  return dismissPrompt;
};