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 to false, 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 to true, 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

• Demo
• Code

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 to true, the SDK will use the staging environment.

Codesandbox

• Demo
• Code

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/sdk@1.0.0/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 to true, 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 the detail 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 the detail object:
  • captureId: The ID of the recording that was previously completed and now has been deleted.

Codesandbox

• Demo
• Code

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/sdk@1.0.0/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 to true, the SDK will use the staging environment.

Codesandbox

• Demo
• Code

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.