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?: Partial<SDKConfig>;
}) => Promise<SDKResult>;

An example setup for the standard SDK:

Type signature
const instance = createInstance({
  mode: "standard";
  publicAppId: "abcde12345";
  config: { insertButtonText: "hello world" };
});

`setup for CustomSDK`

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

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 Partial of an `SDKConfig`

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.

`SDKConfig`

Type signature
interface SDKConfig {
  allowedRecordingTypes?: RecordingType[];
  bubbleResizable?: boolean;
  defaultRecordingType?: RecordingType;
  disablePreviewModal?: boolean;
  enableOnboardingTutorial?: boolean;
  enablePictureInPicture?: boolean;
  insertButtonText?: string;
  styles?: SDKStyles;
}

Description:

Properties a user can set to customize the recordSDK experience.

Properties:

Key	Description	Default value
`allowedRecordingTypes`	Allowed recording types for the SDK. For example, if you want to only allow screen and camera recordings, you can specify that here.	["screen_cam", "screen", "cam"]
`bubbleResizable`	Whether a user can update the video bubble size	true
`defaultRecordingType`	The default selection for recording type. If `allowedRecordingTypes` is specified, must include this default type in the list. If unspecified, defaults to Screen and Camera	"screen_cam"
`disablePreviewModal`	Whether the preview modal at the end of the SDK recording should show up or not.	false
`enableOnboardingTutorial`	If the onboarding tutorial should be enabled for the SDK	false
`enablePictureInPicture`	If picture in picture should be enabled	false
`insertButtonText`	The text for the primary CTA in the preview modal	"Insert recording"
`styles`	A Partial of a `SDKStyles`	{}

`SDKStyles`

Type signature
interface SDKStyles {
  fontFamily?: string;
  fontUnitSize?: string;
  recordButtonColor?: string;
  recordButtonHoverColor?: string;
  recordButtonActiveColor?: string;
  primaryColor?: string;
  primaryHoverColor?: string;
  primaryActiveColor?: string;
}

Description:

Override default styles to personalize the recording experience. Each field can take a valid CSS value for the corresponding property.

Properties

Key	Description
`fontFamily`	The font-family used in the record menu
`fontUnitSize`	The base font unit size used to calculate the font size for the text
`recordButtonColor`	The record button background color (default: orange)
`recordButtonHoverColor`	The record button mouse hover color
`recordButtonActiveColor`	The record button active color
`primaryColor`	The primary color (default: blurple) - this will override the 'insert' button background color
`primaryHoverColor`	The primary mouse hover color
`primaryActiveColor`	The primary active color

`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 setup 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​

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:​

SDKConfig​

Description:​

Properties:​

SDKStyles​

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:

`SDKConfig`

Description:

Properties:

`SDKStyles`

Description:

Properties

`SDKState`

Description:

Properties:

`SDKResult`

Description:

Properties:

`SDKUnsupportedReasons`

Description:

Properties: