Skip to main content

Maestro SDK Getting Started Guide

1. Welcome to Maestro SDK​

Overview of Maestro​

Maestro is a platform for building personalized, interactive video experiences across web, mobile, and connected TV. With Maestro’s SDKs, you can embed interactive features such as polls, stats, chat, shopping, and overlays directly into your apps and sites. These experiences work seamlessly alongside live or on-demand video, and are fully configurable through the Maestro Admin UI.

info

While Maestro is a cross-platform video app builder for web, mobile, and TV, this documentation is specific to the SDKs that power connected TV experiences.

What You Can Build​

With Maestro, you can:

  • Add interactive panels to enhance your video content — polls, stats, chat, shopping, betting, and more.
  • Display dynamic overlays with clickable calls to action on or around video in real time.
  • Automate personalized experiences based on user data, behaviors, and events.
  • Create themeable, modular pages using blocks such as hero banners, playlists, or galleries.
  • Power entire OTT apps on web, mobile, and TV platforms using Maestro as the interactive layer.

Supported Programming Languages and Platforms​

The Maestro SDK is available across the most popular devices and frameworks:

  • Swift: tvOS (iOS coming soon)
  • Kotlin: Android TV, Fire TV (Android Mobile coming soon)
  • BrightScript: Roku
  • JavaScript: Samsung Tizen, LG webOS, Web, Mobile Web

Each platform SDK offers a familiar development model while keeping features consistent across environments.

2. Core Concepts​

Sites​

A site is the top-level container for your content and configuration. Each SDK integration points to a site, which defines branding, theming, pages, and rules for your experience.

Pages​

A page is the foundational layout components within a site. A page controls what users see when they navigate through your app.

  • Channels: Main page type leveraged in this SDK. Optimized for interactive video experiences and feature panels and overlays over/around the video player.
  • Landing Pages: Designed for discovery and browsing content, often with playlists or banners.
note

Landing Pages are not currently used in the Maestro SDK.

Panels​

A panel is an interactive components that lives outside the video player.

  • Types: Chat, Stats, Shop, Quests, Fantasy, Bet, Schedule, Image, and more.

These panel types are available in Maestro’s core platform. Maestro SDK integration is coming soon.

Overlays​

An overlay is an interactive graphic that appears directly over the video. Overlays are designed to drive immediate user action, such as a click, vote, or purchase, and they can also be used similar to notifications or to replace burned-in informational graphics.

  • Types: Shopify, Raffle, Message, Poll, Prediction, Trivia, Poll Results, Lower Third, Highlight

These overlay types are available in Maestro's core platform. Maestro SDK integration is coming soon.

Automation Rules​

Automation allows you to deliver personalized, contextual interactions. With Automation Rules, you can:

  • Trigger overlays based on real-time data (e.g., a score update).
  • Show or hide panels depending on user profile or behavior (coming soon).
  • Automatically configure entire experiences using channel templates (coming soon).

3. Getting Started​

The Getting Started guide walks you through the general steps to integrate the Maestro SDK into your project and sets you up to start leveraging our interactive tools. For more technical guidance find your platform’s example repo below.

Pre-requisites​

Maestro Site & Page IDs​

Site ID (provided when you create a site via maestro.io)

To obtain a Site ID:

  1. Navigate to maestro.io and create a site using the START FOR FREE button.
  2. Go to Site Settings → Developers.
  3. Your Site ID is listed beneath (and is the same as) your Client ID.
Example Site ID Location

Page ID (used to load a specific page experience)

To obtain a Page ID:

  1. Navigate to the page you want to use.
  2. Click Settings.
  3. Under the Name, you will see the Page ID.
Example Site ID Location

Platform-Specific Requirements​

  • An Apple TV device
  • Xcode installed
  • Your own tvOS app running on tvOS version 18 or above

Step 1: Install the SDK​

Each platform has its own dependency management system, so the installation process varies slightly depending on where you’re building your app. Use the standard package manager or installation method for your platform to add the Maestro SDK to your project:

  • Swift / tvOS: Use Swift Package Manager or CocoaPods.
  • Kotlin / Android TV / Fire TV: Use Gradle.
  • BrightScript / Roku: Include the SDK files in your Roku project.
  • JavaScript / Web / Smart TVs: Use npm or yarn to add the SDK package.

Once installed, your project is ready to move on to the next step: initializing the SDK.

Step 2: Initialize the SDK​

Initialize the Maestro SDK to connect your app to the Maestro platform. During initialization, you provide key parameters such as your Site ID and Page ID, which link your app to the correct content and configuration.

Step 3: Place MaestroPanel In Your App​

Panels are the main entry point for interactive experiences in the Maestro SDK. MaestroPanel is the container for all panels configured for a specific page.

To create space for the MaestroPanel, we recommend creating a Pinchback View or similar with the following layout:

Example Site ID Location

This ensures your interactive panels display correctly and integrate seamlessly with your app’s UI.

Step 4: Manage Focus Between MaestroPanel and Your App​

Managing focus between the MaestroPanel and your app is critical for a smooth user experience, especially in TV and full-screen environments. Each platform provides specific methods or interfaces to notify the SDK when the panel is shown or hidden. This allows the SDK to respond appropriately, maintain internal state, and control input focus.

  • Maintain internal state.
  • Control input focus.
  • Ensure panels behave consistently across different devices.
Example of Setting Focus

By managing focus effectively, you ensure that your users can navigate and interact with panels effortlessly, without any interruptions to the viewing experience.

Platform Example Repos​

With these steps, you’re ready to integrate the Maestro SDK. For detailed guidance and working examples, check out the example repositories for your platform, which include fully functional sample apps.

This sample Apple TV app demonstrates how to integrate the Maestro SDK on tvOS using Swift. It covers setup in Xcode, SDK initialization, and rendering interactive panels.
Use the button below to view the full example project on GitHub.
Swift Hello World Repo README (Coming Soon)
Last updated on