@vaam/sdk
v2.0.0
Published
The Vaam SDK lets you record and play [Vaams](https://vaam.io) from your web application. It has two parts, a recorder and a player. Read on about each of them in the relevant section below.
Downloads
88
Readme
Vaam SDK
The Vaam SDK lets you record and play Vaams from your web application. It has two parts, a recorder and a player. Read on about each of them in the relevant section below.
The SDK is available as React components and as web components.
Using the SDK
Before using the SDK, you need your Vaam API key. Note that you have different API keys for the staging and production environments. You decide which of the environments you use by setting the testEnv
flag at the approproiate place. If you don't set a testEnv
flag, the SDK will use the production environment.
React
The React components are written using React 18.0.x, but any React version > 16.8 (when hooks were introduced) is supported. Before you start the implementing the SDK in your codebase, make sure that you've installed it.
npm install --save @vaam/sdk
or yarn add @vaam/sdk
Recorder
Import the Recorder package
import { Recorder } from '@vaam/sdk/react/Recorder'
and implement it in your React component. Recorder
takes the following props:
apiKey
(required): You Vaam API key.handleRecordingFinished
(required): A function that will be called when the recording is done. It is called with the following arguments:captureId (string)
: The id of the completed recording.waitingToUpload (boolean)
: A flag indicating that the recording is still uploading. This can happen if the streaming of the recording failed and the component has fallen back to a non-streaming mode.
handleRecordingRestarted
(required): A function that will be called when the user chooses to restart the recording. It is called with the following arguments:captureId (string)
: The ID of the recording that was previously completed and now has been deleted.
startInactive
(optional, default: true): If set tofalse
, the recorder will start immediately after the component is mounted. This means that the user will be asked to grant access permissions to the camera and microphone. Without it, the recorder will start only after the user clicks the "Record an introduction" button.testEnv
(optional, default: false): If set totrue
, the SDK will use the staging environment.title
(optional, default: ''): The title of the recording.recordScreen
(optional, default: false): Record the screen of the user's computer.
Codesandbox
Player
Import the Player package
import { Player } from '@vaam/sdk/react/Player'
and implement it in your React component. Player
takes the following props:
apiKey
(required): You Vaam API key.captureId
(required): The id of the Vaam to play.testEnv
(optional, default: false): If set totrue
, the SDK will use the staging environment.
Codesandbox
Web
If you don't run a bundle step for your application, you can also use the Vaam SDK as a web component.
Recorder
Include the following script tag in your HTML file:
<script src="https://unpkg.com/@vaam/sdk/web/recorder.js"></script>
If you want to pin the version of the SDK, append the version to the source URL:
<script src="https://unpkg.com/@vaam/[email protected]/web/recorder.js"></script>
The script will register the vaam-recorder
component as a custom element on your page. When it is ready to initiate, it will emit a vaam-recorder-ready
event. Listen for that event, and then call the window.Vaam.Recorder.init()
method to initialize the recorder. The init method takes the following arguments.
apiKey
(required): You Vaam API key.containerElement
(optional, default:document.body
): The element in which the recorder will be rendered.testEnv
(optional, default: false): If set totrue
, the SDK will use the staging environment.title
(optional, default: ''): The title of the recording.
The component will emit the following events:
recording-finished
: Emitted when the recording is finished. The event will contain the following properties in thedetail
object:captureId
: The id of the completed recording.waitingToUpload
: A flag indicating that the recording is still uploading. This can happen if the streaming of the recording failed and the component has fallen back to a non-streaming mode.
recording-restarted
: Emitted when the user chooses to restart the recording. The event will contain the following properties in thedetail
object:captureId
: The ID of the recording that was previously completed and now has been deleted.
Codesandbox
Player
Include the following script tag in your HTML file:
<script src="https://unpkg.com/@vaam/sdk/web/player.js"></script>
If you want to pin the version of the SDK, append the version to the source URL:
<script src="https://unpkg.com/@vaam/[email protected]/web/player.js"></script>
The script will register the vaam-player
component as a custom element on your page. When it is ready to initiate, it will emit a vaam-player-ready
event. Listen for that event, and then call the window.Vaam.Player.init()
method to initialize the recorder. The init method takes the following arguments.
captureId
(required): The id of the Vaam to play.containerElement
(optional, default:document.body
): The element in which the recorder will be rendered.testEnv
(optional, default: false): If set totrue
, the SDK will use the staging environment.
Codesandbox
Utilities
The SDK contains a utility belt to help you with various operations. To use it, import and initialize the utility package as below. The initialization will return the available utility functions.
import initVaamUtils from '@vaam/sdk/utils';
const apiKey = '6d7bb00d-6b4d-4665-8409-5ba89f70b56d';
const useTestEnv = true;
const vaamUtils = initVaamUtils(apiKey, useTestEnv);
Available utility functions
Get video urls
function getVideoUrls(captureId: string) => Promise<{
hls: string | undefined;
mp4: string | undefined;
webm: string | undefined;
}>;
Call this function with a captureId
representing a capture that has been created using the same API key. It will return a promise that will resolve to an object containing the URLs of the videos. If the thumnbails are still being generated, any of they keys can be undefined. webm files are only available on platforms that support them, notably Chromium based browsers.
Get thumnbail urls
function getThumbnailUrls(captureId: string) => Promise<{
gif: string | undefined;
gifWithPlayButton: string | undefined;
jpg: string | undefined;
}>;
Call this function with a captureId
representing a capture that has been created using the same API key. It will return a promise that will resolve to an object containing the URLs of the thumbnails. If the thumnbails are still being generated, any of they keys can be undefined.