Installation and Integration with Maestro Web SDK

This section will walk you through the process of installing and integrating the Maestro Web SDK into your web application.

Prerequisites

Before you begin, ensure you have:

• Your Maestro siteID and the pageId of the page you want to load.
• A web application where you want to integrate the SDK.
• React 16+ and react-dom available in your app — they are peer dependencies of the SDK.
• A device or browser the SDK supports — see Device & Browser Support.

Finding your siteID and pageId

Your siteID identifies your Maestro site, and a pageId identifies a specific page within it. Both are available in the Maestro admin UI on maestro.io. If you can't locate them, reach out to our support team.

Device & Browser Support

The published SDK is compiled for the browser engines used by current connected-TV platforms and modern desktop browsers.

Target	Supported versions	Engine
Samsung Tizen	2015 models and newer	Chromium 47+
LG webOS	3.0 and newer	Chromium 38+
Vizio SmartCast	Current SmartCast models	Chromium-based
Android TV / Google TV	Android 5 and newer	Chrome / Android System WebView
Amazon Fire TV	Fire OS 5 and newer	Chromium-based WebView
Desktop browsers	Chrome 30+, Safari 5.1+, Firefox 27+, Edge 18+	Blink / WebKit / Gecko
Build browserslist floor	safari >= 5.1, chrome >= 30, firefox >= 27, edge >= 18	Targets the SDK build compiles down to
react / react-dom (peer deps)	16, 17, 18, 19	Provided by your application

Bundle the SDK — don't load it straight from a <script> tag

To support React 19, the SDK needs a dynamic import('react-dom/client'), and that one line of modern syntax stays in the published files. In practice this doesn't affect you: if you're building with modern bundlers (webpack, Next.js, or Vite), as every supported setup does, your bundler handles that syntax and compiles it down for whatever browsers you target. The device support above applies as normal.

Polyfills for older engines

The SDK bundles no polyfills. It relies on ES6+ built-in APIs at runtime — Promise, Symbol, Object.assign, Map/Set, Array.from, Object.entries, and fetch. Browsers that predate native support for these (roughly below Chrome 45 / Safari 10 / Firefox 45) will need host-provided polyfills (e.g. core-js) or the SDK will throw at runtime. Most host apps already polyfill these for their own code; if you target one of these older engines, ensure your polyfills load before the SDK.

Installation

Add the Maestro Web SDK to your project:

npm install @maestro_io/maestro-web-sdk

or with yarn:

yarn add @maestro_io/maestro-web-sdk

Peer dependencies

react and react-dom are peer dependencies — the SDK does not bundle them and expects your application to provide them. React 16, 17, 18, and 19 are supported. If your app doesn't already depend on them, install them alongside the SDK:

npm install react react-dom

Basic Integration Steps

1. Import the SDK

The Maestro Web SDK follows a singleton pattern, providing a single instance that you can import and use throughout your application:

import SDK from "@maestro_io/maestro-web-sdk";

2. Configure the SDK

SDK.configure({
  siteID: "your-site-id",
});

3. Initialize Event

MaestroEventDelegate below is your own class implementing the IMaestroEventDelegate interface — the SDK exports the interface, not a ready-made delegate, so you provide the implementation that handles SDK callbacks (playback, auth, analytics, etc.).

const delegate = new MaestroEventDelegate(); // Your implementation of IMaestroEventDelegate

const event = await SDK.userDidStartWatchingEvent({
  pageId: "YOUR_PAGE_ID", // Your Maestro Site's page ID to load the config from.
  delegate,
});

For a complete example of integration, refer to our Example Repo for the Maestro Web SDK.