Skip to main content

Architecture

Three things move through the system: your events, Maestro's configuration for each one, and the panels and overlays the SDK renders from it.

  • Event ingestion. Maestro polls the schedule feed you already publish. Each event is matched to a template, which decides which features are on and how they are configured. Maestro sets this up with you; see Ingestion rules and templates.
  • Config files on the CDN. For every event, Maestro publishes a JSON document at a path built from your Site ID and your own event identifier. It is rebuilt whenever your feed changes or your team edits settings in the Admin.
  • The SDK. Your app instantiates it once with the Site ID, then configures it for content. The SDK fetches the configuration, builds the panels and overlays it describes, and renders them where your app says.

Core concepts​

Site. The top-level container for your content and configuration. Every SDK integration points at one site, identified by a Site ID.

Page. A layout within a site. Channels are the page type this SDK uses: interactive video pages with panels beside the player and overlays over it. A page created in the Admin is identified by a Page ID.

Event. One piece of scheduled content in your feed, identified by your own event ID. Once ingestion is set up, the SDK can be configured with that ID directly and fetches the configuration Maestro published for it.

Panel. An interactive component that lives outside the video player: chat, stats, shop, quests, fantasy, betting, schedule, and custom panels Maestro builds for you.

Overlay. An interactive graphic that appears over the video to drive immediate action: polls, predictions, trivia, lower thirds, highlights, calls to action.

Automation rules. Trigger overlays from real-time data, show or hide panels by user context, and configure whole experiences from templates.

Page ID and Event ID​

The SDK can be pointed at content two ways, and they make different calls.

  • A Page ID identifies a page you created in the Maestro Admin. The SDK loads that page's configuration directly. Hello World uses a Page ID so nothing depends on a feed.
  • An Event ID is your identifier from your own schedule feed. After ingestion is set up, the SDK fetches the configuration document Maestro published under it from the CDN. The eventID will be any unique ID passed around your application, directly mapping to a maestro page.

In practice you will never need to know or use a Page ID. Once ingestion is set up you use your own identifier exclusively, and Maestro resolves it to the page behind the scenes. Hello World uses a Page ID only because it runs before any feed exists.

Parameter names differ by platform and are stated in each Hello World section.

How it works: Stats panel example​

Your app talks to the SDK. The SDK talks to Maestro. The steps in the shaded box are the ones Hello World implements.

Steps 7 to 9 happen on their own once a Stats panel is configured for the event. They need your app to feed playerTimecode to the SDK; each platform exposes a call for that, and Hello World wires it in the overlay section.

Where the SDK lives in your app​

Instantiate once, at the application level

Create the Maestro SDK when your app starts, as a sibling of your video player, never inside it. The SDK is designed to be reconfigured for new content without being destroyed, which is what lets it keep its panel on screen while the video underneath changes. If instead the video experience owns the SDK, the SDK is torn down and redrawn every time content changes. Maestro expects you will implement against this lifecycle.

The panel's host view, whether that is a SwiftUI column, a Compose slot, a SceneGraph node, or a DOM element, is owned by your app shell for the same reason.

As a sequence, one SDK instance spans the whole session. Content selection repeats; instantiation and teardown happen once each.

The same sequence in each SDK​

Each step of the diagram maps to one call or one observable per platform. Values shown are the Hello World defaults against Maestro's demo page. "Fetch config" and "Build supported panels" happen inside the SDK; the row shows what your app can observe.

Diagram stepInterfaceHello World value
Open application, instantiate SDKMaestroManager.shared.configure(siteID:jwt:maestroManagerDelegate:maestroWorkingEnvironment:defaultPanel:)siteID: "69b2f133e8117ec6536d59a1", jwt: "", .prod, defaultPanel: .stats
Select content, pass pageID or eventIDawait MaestroManager.shared.userDidStartWatchingEvent(eventID:delegate:hideBetsPanel:hideBetsWagers:disableBetsOverlays:disableFantasyOverlays:) returns MaestroEventInterfaceeventID: "6aa966d669342216ada5a4b8" (the Page ID goes in this parameter)
Fetch config, build supported panelsInternal. The await returns once the session exists; MaestroPanel() renders the built panels. defaultPanel selects the first tab.Stats tab visible
Select other contentawait MaestroManager.shared.userDidStopWatchingEvent(currentID) then userDidStartWatchingEvent(eventID: nextID, ...)next Page ID
Application closed, destroyawait MaestroManager.shared.userDidStopWatchingEvent(currentID). There is no separate teardown call; the shared manager lives with the process.current Page ID
// Open application
MaestroManager.shared.configure(
    siteID: "69b2f133e8117ec6536d59a1", jwt: "",
    maestroManagerDelegate: AppDelegate(),
    maestroWorkingEnvironment: .prod, defaultPanel: .stats)

// Select content
let event = await MaestroManager.shared.userDidStartWatchingEvent(
    eventID: "6aa966d669342216ada5a4b8", delegate: self,
    hideBetsPanel: false, hideBetsWagers: false,
    disableBetsOverlays: false, disableFantasyOverlays: false)

// Select other content
await MaestroManager.shared.userDidStopWatchingEvent("6aa966d669342216ada5a4b8")
let next = await MaestroManager.shared.userDidStartWatchingEvent(eventID: nextPageID, delegate: self, /* ... */)

// Application closed
await MaestroManager.shared.userDidStopWatchingEvent(nextPageID)

Tech stack​

One SDK per platform, each built with that platform's native UI toolkit. Versions below are the minimums the current SDKs are built against; the sample apps use the same or newer.

LanguageSwift 5
UI frameworkSwiftUI. MaestroPanel and MaestroOverlay are SwiftUI views. UIKit apps host them in a UIHostingController.
Minimum OStvOS 18.0
ToolchainXcode 16
SDK packageMaestroKit, distributed as a binary XCFramework through Swift Package Manager from github.com/lessthan3/MaestroKit.swift. No CocoaPods. Current release 10.8.x.
Dependenciesrive-ios 6.12 or later, resolved automatically by SPM. Manual framework installs must add it by hand.
App requirementsNone. No Info.plist keys, entitlements, privacy manifest, or font registration.

Start with Hello World.

Last updated on