API

Updating the SDK

It is essential to stay on the latest version of the Loom SDK. The latest version of the SDK can be found here.

Methods

`setup for StandardSDK`

The SDK uses the createInstance function with the following parameters to return the SDK object on versions 3.2.0 and above. The setup function is being deprecated.

Type signature
type SetupFunction = (a: {
  mode: "standard";
  publicAppId: string;
  environment?: Environment;
  config?: { insertButtonText: string };
}) => Promise<SDKResult>;

An example setup for the standard SDK:

Example setup
const instance = createInstance({
  mode: "standard",
  publicAppId: "abcde12345",
  config: { insertButtonText: "hello world" }
});

`setup for CustomSDK`

warning

CustomSDK is no longer available for new SDK instances. If you have an existing instance, you may continue to use it, but we no longer develop this type of SDK.

Type signature
type SetupFunction = (a: {
  mode: "custom";
  jws: string;
  environment?: Environment;
  config?: { insertButtonText: string; };
}) => Promise<SDKResult>;

An example setup for the custom SDK:

Example setup
const instance = createInstance({
  mode: "custom",
  jws: "<token-value>",
  config: { insertButtonText: "hello world" }
});

Description:

Enables the execution of the recordSDK.

Arguments:

Key	Description
`mode`	The type of SDK you are implementing
`publicAppId`	The key that provides access to an SDK workspace for the domain from which the record button is served. Only available in StandardSDK
`jws`	The key that provides access to an SDK workspace for the domain from which the record button is served. Only available in CustomSDK
`environment`	An optional param indicating which env the SDK is running. "development", "testbench", "staging", "production"
`config`	A config containing the insert button text for the preview modal.

Response:

An SDKResult object wrapped in a Promise.

`isSupported`

Type signature
isSupported(): Promise<{
    supported: boolean;
    error: SDKUnsupportedReasons | undefined;
}>

Description:

Identifies if the browser that is trying to run the recordSDK has the necessary web APIs required to perform a recording.

(Deprecation Warning) Import method:

With the release of v3.0.0, isSupported can only be imported from its own bundled module at @loomhq/record-sdk/is-supported.

Importing isSupported from @loomhq/record-sdk will be deprecated.

Import Method
// v3.0.0 and after
import { isSupported } from "@loomhq/record-sdk/is-supported";

// Before v3.0.0
import { isSupported } from "@loomhq/record-sdk/is-supported";
// OR
import { isSupported } from "@loomhq/record-sdk";

Arguments:

None

Response:

An object with the following properties:

Key	Description
`supported`	Represents if recordSDK is supported by the browser
`error`	See `SDKUnsupportedReasons`—will be `undefined` if `supported` is `true`

Types

`ButtonFn`

Type signature
type ButtonFn = (a?: {
  element?: HTMLElement;
  hooks?: Hooks;
}) => SDKButtonInterface;

Description:

A function used to connect a specified DOM element to the recordSDK.

Arguments:

Key	Description
`element`	DOM element to attach SDK
`hooks`	DEPRECATED Use `ButtonEmitterEvents` in place of `hooks`

Response:

An SDKButtonInterface object.

`ButtonEmitterEvents`

Type signature
interface ButtonEmitterEvents {
  "bubble-drag-end": (pos: Position) => void;
  "bubble-drag-start": (pos: Position) => void;
  "bubble-move": (pos: Position) => void;
  cancel: () => void;
  complete: () => void;
  "insert-click": (video: LoomVideo) => void;
  "lifecycle-update": (state: SDKState) => void;
  "recording-complete": (video: LoomVideo) => void;
  "recording-start": () => void;
  start: () => void;
  "upload-complete": (video: LoomVideo) => void;
}

Description:

Events that can be listened to when registered on an SDKButtonInterface instance. See Adding event listeners to see example of usage.

Properties:

Key	Description
`bubble-drag-end`	Event emitted when camera bubble dragging has ended—`pos` arg is Position of bubble
`bubble-drag-start`	Event emitted when camera bubble dragging has begun—`pos` arg is initial Position of bubble
`bubble-move`	Event emitted when camera bubble is moved-`pos` arg is Position of bubble
`cancel`	Event emitted when recording is cancelled
`complete`	Event emitted when user has selected finish recording
`insert-click`	Event emitted when insert CTA has been selected—`video` arg is `LoomVideo` available after recording
`lifecycle-update`	Event emitted when lifecycle state change with `SDKState` as arg
`recording-complete`	Event emitted when recording is ended (video upload may be in progress)—`video` arg is `LoomVideo`
`recording-start`	Event emitted when video capture has begun (after 3..2..1 countdown)
`start`	Event emitted when user has selected start recording
`upload-complete`	Event emitted when the recording has finished uploading to Loom—`video` arg is `LoomVideo`

`LoomVideo`

Type signature
interface LoomVideo {
  id: string;
  title: string;
  height: number;
  width: number;
  sharedUrl: string;
  embedUrl: string;
  thumbnailHeight?: number;
  thumbnailWidth?: number;
  thumbnailUrl?: string;
  duration?: number;
  providerUrl: string;
  autoTitleStatus?: IntelligenceAvailableStatusType;
  autoDescriptionStatus?: IntelligenceAvailableStatusType;
  description?: string;
  autoChaptersStatus?: AutoChapterStatusesType;
  autoChaptersCount?: number;
  chapters?: string;
}

Description:

Object representing a loom video which becomes available after recording.

Properties:

Key	Description
`id`	Video id
`title`	Video title
`height`	Video height in pixels
`width`	Video width in pixels
`sharedUrl`	URL for sharing video
`embedUrl`	URL for embedding video
`thumbnailHeight`	Height of video thumbnail
`thumbnailWidth`	Width of video thumbnail
`thumbnailUrl`	URL of video thumbnail
`duration`	Video duration
`providerUrl`	URL of video provider
`autoTitleStatus`	The status of an auto generated title
`autoDescriptionStatus`	The status of an auto generated description
`description`	Video description
`autoChaptersStatus`	The status of an auto generated chapters
`autoChaptersCount`	The number of auto generated chapters generated, 0 if disabled
`chapters`	Video chapters

`Position`

Type signature
interface Position {
  x: number;
  y: number;
}

Description:

Position of an element on the screen—specifically used for the camera bubble.

Properties:

Key	Description
`x`	x coordinate in pixels—0 is bottom of the screen
`y`	y coordinate in pixels—0 is left-most side of the screen

`SDKButtonInterface`

Type signature
interface SDKButtonInterface extends EventEmitter<ButtonEmitterEvents> {
  openPreRecordPanel: () => void;
  closePreRecordPanel: () => void;
  moveBubble: (p: Position) => void;
}

Description:

Object containing methods for the SDK to be programmatically interacted with. Fulfills the NodeJS EventEmitter definition and contains methods such as .on which listens to registered ButtonEmitterEvents.

Properties:

Key	Description
`openPreRecordPanel`	Programmatically opens the pre-record panel
`closePreRecordPanel`	Programmatically closes the pre-record panel
`moveBubble`	Programmatically moves the camera bubble—`p` arg is target `Position` of camera bubble

Also contains properties of EventEmitter class.

`SDKState`

Type signature
enum SDKState {
  Closed = "closed",
  PreRecording = "pre-recording",
  ActiveRecording = "active-recording",
  PostRecording = "post-recording",
}

Description:

An enum of the lifecycle state of the recordSDK.

Properties:

Member	Description
`closed`	SDK has loaded but is not being used
`pre-recording`	Pre-recording panel is open
`active-recording`	Recording is in progress (pausing recordings is a part of this state)
`post-recording`	Recording has finished and preview modal is open

`SDKResult`

Type signature
type SDKResult = {
  configureButton: ButtonFn;
  status: () => {
    state: SDKState | undefined;
    success: boolean;
  };
  teardown: () => void;
  updateConfig: ({ config }: { config: SDKConfig }) => void;
};

Description:

An object returned from the createInstance function to configure the recordSDK.

Properties:

Key	Description
`configureButton`	See `ButtonFn`
`status`	Function returning an object with a `success` property—a boolean of whether the SDK successfully loaded—and a `state` property—either an`SDKState` member or `undefined` if `success` is `false`
`teardown`	IMPLEMENTATION IN PROGRESS Cleans up the instantiated SDK in the background and should be called when the button that triggers the SDK is removed from the DOM
`updateConfig`	Function that allows you to update any part of the `SDKConfig` at any point

`SDKUnsupportedReasons`

Type signature
enum SDKUnsupportedReasons {
  IncompatibleBrowser = "incompatible-browser",
  ThirdPartyCookiesDisabled = "third-party-cookies-disabled",
  NoMediaStreamsSupport = "no-media-streams-support",
}

Description:

An enum containing reasons why the recordSDK is not supported on the user’s browser.

Properties:

Member	Description
`incompatible-browser`	Browser is not supported
`third-party-cookies-disabled`	User’s third party cookies are disabled
`no-media-streams-support`	MediaStream functionality is not available

API

Updating the SDK​

Methods​

setup for StandardSDK​

setup for CustomSDK​

warning

Description:​

Arguments:​

Response:​

isSupported​

Description:​

(Deprecation Warning) Import method:​

Arguments:​

Response:​

Types​

ButtonFn​

Description:​

Arguments:​

Response:​

ButtonEmitterEvents​

Description:​

Properties:​

LoomVideo​

Description:​

Properties:​

Position​

Description:​

Properties:​

SDKButtonInterface​

Description:​

Properties:​

SDKState​

Description:​

Properties:​

SDKResult​

Description:​

Properties:​

SDKUnsupportedReasons​

Description:​

Properties:​

Updating the SDK

Methods

`setup for StandardSDK`

`setup for CustomSDK`

Description:

Arguments:

Response:

`isSupported`

Description:

(Deprecation Warning) Import method:

Arguments:

Response:

Types

`ButtonFn`

Description:

Arguments:

Response:

`ButtonEmitterEvents`

Description:

Properties:

`LoomVideo`

Description:

Properties:

`Position`

Description:

Properties:

`SDKButtonInterface`

Description:

Properties:

`SDKState`

Description:

Properties:

`SDKResult`

Description:

Properties:

`SDKUnsupportedReasons`

Description:

Properties: