API
Methods​
setup
​
type SetupFunction = (a: {
/** @deprecated `apiKey` has been renamed to `publicAppId`, please use that instead */
apiKey?: string;
publicAppId?: string;
environment?: Environment;
jws?: string;
config?: Partial<SDKConfig>;
}) => Promise<SDKResult>;
Description:​
Enables the execution of the recordSDK.
Arguments:​
Key | Description |
---|---|
apiKey | Deprecated - this field has been renamed to publicAppId |
publicAppId | The key that provides access to an SDK workspace for the domain from which the record button is served |
jws | A signed JWT used for key-pair authentication |
config | A Partial of an SDKConfig |
Response:​
An SDKResult
object wrapped in a Promise.
isSupported
​
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.
// 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 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
​
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
​
interface LoomVideo {
id: string;
title: string;
height: number;
width: number;
sharedUrl: string;
embedUrl: string;
thumbnailHeight?: number;
thumbnailWidth?: number;
thumbnailUrl?: string;
duration?: number;
providerUrl: 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 |
Position
​
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
​
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
​
interface SDKConfig {
bubbleResizable: boolean;
insertButtonText: string;
allowedRecordingTypes?: RecordingType[];
defaultRecordingType?: RecordingType;
styles?: SDKStyles;
}
Description:​
Properties a user can set to customize the recordSDK experience.
Properties:​
Key | Description |
---|---|
bubbleResizable | Whether a user can update the video bubble size |
insertButtonText | Overwrites the default "Insert recording" text that appears in the preview modal |
allowedRecordingTypes | Allowed recording types for the SDK. For example, if you want to only allow screen and camera recordings, you can specify that here. |
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 |
SDKStyles
​
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
​
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 SDKResult = {
configureButton: ButtonFn;
status: () => {
state: SDKState | undefined;
success: boolean;
};
teardown: () => 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 anSDKState 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 |
SDKUnsupportedReasons
​
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 |