Overlay Integration

Overview

This section walks you through integrating overlays into your Maestro tvOS SDK implementation. Overlays provide animated, contextual notifications that enhance user engagement during live events.

Integration Steps

MaestroOverlay is a SwiftUI component that provides an overlay view for you to add to your app's view hierarchy. The overlay should be presented either in a .overlay view modifier, or in a ZStack above your other views.

The order of events in using the MaestroOverlay goes like this:

1. The SDK determines that a MaestroOverlay needs to be shown
2. The SDK calls shouldShowOverlay(buttonSize:overlayType:payload:) in the MaestroEventDelegate to tell your app to display an overlay with the given buttonSize.
3. Your app instances MaestroOverlay(buttonPosition:overlayType:payload:) with a buttonPosition that indicates the position at which the overlay should be displayed. Your app should determine the best place for the overlay given the buttonSize provided in the shouldShowOverlay() call. The overlayType and payload parameters should be the values you received from the SDK in the shouldShowOverlay(buttonSize:overlayType:payload) call.
4. If the user takes no action, or clicks the button, the overlay will call shouldHideOverlay() in your app's MaestroEventDelegate implementation to let you know the overlay should be dismissed.
5. Your app should call didShowOverlay() and didHideOverlay() when those events occur, to keep the SDK apprised of your current use of the MaestroOverlay.

1. Implement MaestroEventDelegate methods

Your app must implement the following methods in the MaestroEventDelegate protocol to handle overlay display:

func shouldShowOverlay(buttonSize: CGSize, overlayType: OverlayType, payload: MaestroOverlayEvent?) {
    // Determine the best position for the overlay based on buttonSize
    let buttonPosition = CGPoint(x: 1100, y: 100)

    // Add MaestroOverlay to your view hierarchy
    // Store overlayType and payload to pass to MaestroOverlay
    MaestroOverlay(
        buttonPosition: buttonPosition,
        overlayType: overlayType,
        payload: payload //Optional Payload
    )
}

func shouldHideOverlay() {
    // Remove MaestroOverlay from your view hierarchy
}

2. Add MaestroOverlay to your View Hierarchy

Add the MaestroOverlay view to your view hierarchy when shouldShowOverlay is called:

import MaestroKit
import SwiftUI

struct ContentView: View {
    @State private var showOverlay = false
    @State private var overlayType: OverlayType?
    @State private var overlayPayload: MaestroOverlayEvent?
    @State private var buttonPosition: CGPoint = .zero

    var body: some View {
        ZStack {
            // Your main content
            VideoPlayerView()

            // Overlay (conditionally shown)
            if showOverlay, let overlayType = overlayType {
                MaestroOverlay(
                    buttonPosition: buttonPosition,
                    overlayType: overlayType,
                    payload: overlayPayload
                )
            }
        }
    }
}

3. Notify the SDK of Overlay Events

Call the appropriate methods on the Maestro Event Interface to keep the SDK informed:

// When overlay is shown
await maestroEvent.didShowOverlay()

// When overlay is hidden
await maestroEvent.didHideOverlay()

MaestroOverlay Component

MaestroOverlay is a struct that provides an overlay view for you to add to your app's view hierarchy.

struct MaestroOverlay: View

Parameters

Parameter	Type	Description
buttonPosition	CGPoint	The position at which the overlay should be displayed.
overlayType	OverlayType	The type of overlay to be shown.
payload	MaestroOverlayEvent?	The optional payload for the overlay.

Sample Usage

struct ContentView: View {
    var body: some View {
        MaestroOverlay(
            buttonPosition: CGPoint(x: 1100, y: 100),
            overlayType: .fantasy,
            payload: nil
        )
    }
}

Best Practices

• Position Calculation: Calculate the best position for overlays based on the provided buttonSize to ensure they don't obscure important content.
• Notify SDK: Always call didShowOverlay() and didHideOverlay() to keep the SDK synchronized with your overlay state.
• Handle Dismissal: Properly handle both user-initiated dismissal (clicks) and auto-dismissal after timeout.
• Error Handling: Implement proper error handling for overlay operations.