ManageXR React Streaming SDK

This package allows organizations managing XR devices with ManageXR to embed the ManageXR web console's streaming functionality in their own React apps. Devices must be actively enrolled with ManageXR in order to stream.

Usage

Step 1: Generate an SDK token for the device(s) you want to stream

See our API Docs for instructions on authenticating API requests.

The API key used in the request must have access to every device specified. The returned token will authenticate the SDK to stream only those devices. To stream additional devices, request a new token.

Request:

curl --request POST \
  --url https://managexrapi.com/v1/devices/generate-streaming-sdk-token \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '{ "deviceIds": ["device_id_1", "device_id_2"] }'

Response:

{ "token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }

Step 2: Render an instance of useDeviceStream for each device

The connection process will start as soon as the hook is rendered. To end the stream, simply stop rendering the component that contains the hook.

import { useDeviceStream } from '@managexr/react-streaming'

const StreamingComponent = ({ deviceId, token }) => {
   const { videoRef } = useDeviceStream(deviceId, token)

   return (
      <div>
         <video ref={videoRef} />
      </div>
   )
}

API

useDeviceStream(deviceId: string, token: string, options?: DeviceStreamOptions) => DeviceStream

| Argument | Description | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------- | | deviceId | The id (serial) of the device to stream from. This device must be registered with ManageXR and have the ManageXR Admin App installed. | | token | An authentication token returned by the generate-streaming-sdk-token endpoint. The token must include the provided deviceId. | | options | See DeviceStreamOptions |

Returns DeviceStream

DeviceStreamOptions

| Option | Default | Description | | ----------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | endOtherStreamAutomatically | false | When true, if the requested device is already streaming to another computer, that stream will be ended automatically. The error_already_streaming status will not be emitted. |

DeviceStream

| Property | Description | | ---------------- | ------------------------------------------------------------------------------------------------------------------------ | | videoRef | Set this as the ref of the <video> element that should display the stream. | | status | The current status of the stream. See DeviceStreamStatus for info about each status. | | reloadVideo | To change which <video> element is displaying the stream, call this after setting ref={videoRef} on the new element. | | retryStream | Call this to restart the stream if it encounters an error status other than error_already_streaming. | | endOtherStream | Call this when the error_already_streaming status is encountered to end any active streams for the current device. |

DeviceStreamStatus

| Status | Description | | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | pending_online | Device is currently offline. The connection process will start once the device is online. | | pending_permission | The in-headset user has been prompted to allow ManageXR to capture the screen. The connection process will continue once permission is granted. | | pending_connection | Screen capture permission has been granted and the connection process is underway. | | connected | The stream is connected. If videoRef has been set correctly, the stream is now visible. | | reconnecting | The stream has disconnected due to a network issue and is attempting to reconnect automatically. | | error_request_failed | The device did not acknowledge the request to start a stream. | | error_permission_dismissed | The in-headset user dismissed the prompt to allow screen capture. | | error_permission_denied | The in-headset user denied screen capture permission. | | error_failed_to_start | Screen capture permission was granted, but the stream failed to start. | | error_terminated_on_device | The stream was successfully connected but then ended by the in-headset user. | | error_connection | The stream was successfully connected but a network issue caused it to end early. | | error_already_streaming | Another computer is already streaming this device. A device can't stream to more than one computer at a time. | | error_oem_permission_required | The device manufacturer suppressed the stream. |