Skip to main content

Architecture

Overview#

The recordSDK consists of two parts:

  • A JavaScript module (compiled from TypeScript) which provides the entry point for you to configure the SDK, along with all UI elements enabling an end-user to trigger recording
  • A background iFrame, served by loom.com, which provides all business logic

The Loom UI elements are injected into a shadow DOM on your webpage. The iFrame is completely hidden from the end-user’s experience and is purely meant as a proxy to loom.com APIs.

This bi-modal architecture enables Loom to continually roll out improvements to business logic without requiring you to update your own code. The @loomhq/loom-sdk package itself will only need to be updated if the interface for initialization and configuration changes, or if there are changes to the end-user experience.

In the approximately six months of the recordSDK Alpha and Beta programs, there has been only one breaking change (converting a sync method to async) and a single required upgrade (to account for Chrome security policy updates).

Diagram of recordSDK

Workflow components#

The recordSDK manages its own lifecycle and provides hooks for key events with which you can interact. The major components of the recording workflow are the following:

Pre-recording panel#

  • User authentication and signup
  • Media device selection
  • Kick off recording

Mid-recording components#

  • Camera bubble and bubble resizer
  • Recording controls—stop, pause, etc.

Post-recording preview#

  • Modal containing the completed recording
  • Recording can be inserted onto page, have URL copied, deleted, or redone

Browser compatibility#

The recordSDK is dependent on the MediaRecorder API which limits availability to ~89% of global audience. The isSupported method prevents activation if it detects that it is being invoked in an environment in which the MediaRecorder API is not supported. See Can I use MediaRecorder API.

Browser compatibility of recordSDK

The current browser matrix support (subject to change as more browsers get added to the list and as performance is tuned) is as follows:

  • Google Chrome v90+
  • Microsoft Edge v90+
  • Brave v1.22+

Firefox is currently unsupported because even though the MediaRecorder API is supported, performance does not meet our quality bar. We will continue to evaluate Firefox support for future inclusion.

Safari recently made MediaRecorder support GA, and we will look to add Safari support soon.

Error handling#

The recordSDK will swallow errors and prevent them from cascading to the containing application. The setup method will return an error if initialization of the recordSDK fails. The isSupported method is meant to prevent loading the SDK in environments which prevent a successful recording. These methods exist to allow you to hide the recordSDK UI in your application as appropriate. If for whatever reason the recordSDK experiences a failure even after these checks, the UI will update to show an error state to the end-user.

Referrer header#

Your API key is associated with an allow list of domains. Attempts to instantiate the recordSDK will compare the provided API key with the Referrer header on the request to loom.com (as part of the setup call, described below).

If you encounter a 403 when attempting to load the recordSDK, please inspect the Referrer header on the request to Loom to ensure it matches a domain in your allow list. Also note that a strict referrer policy in your web app may prevent sending the Referrer header for iFrames with a different origin.

Eval safe bundle#

The default bundle includes a globalThis polyfill that falls back to Function('return this')() in some cases. If your runtime environment has a strict CSP that doesn’t allow unsafe-eval then there is a separate bundle available which avoids the polyfill. The bundle can be imported directly from the @loomhq/loom-sdk package’s dist folder.

import {/* ... */} from '@loomhq/loom-sdk/dist/cjs/safe';