Skip to main content

Overlay Integration Guide

Overview​

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

Integration Steps​

1. Access the Overlay View Model​

After initializing an event, access the overlay view model through the SDK's view models:

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

// Get the view models after event initialization
const viewModels = SDK.getMaestroViewModels();
const overlayViewModel = viewModels?.overlayViewModel;

2. Create Overlay Events​

Configure overlay events with the required parameters:

import { OverlayType, IMaestroOverlayEvent, IOverlaySize } from '@maestro_io/maestro-web-sdk';

// Define overlay size and position
const overlaySize: IOverlaySize = {
  width: 570,
  height: 128
};

// Create a Bet Win overlay
const betWinOverlay: IMaestroOverlayEvent = {
  type: OverlayType.WinningBet,
  size: overlaySize,
  position: {
    top: 50,
    right: 20
  },
  winningBet: {
    serverID: 'bet-123',
    notificationText: 'Your Lakers bet won!',
    amount: 125.50,
    outcome: 'WIN'
  }
};

3. Display Overlays​

Use the overlay view model to show overlays:

// Show a single overlay
overlayViewModel.showOverlay(betWinOverlay);

4. Handle Overlay Interactions​

Overlays automatically handle user interactions, but you can also manually control them:

// Manually hide the current overlay
overlayViewModel.hideOverlay();

// Handle overlay click (called automatically on user interaction)
overlayViewModel.handleOverlayClick();

5. Listen to Overlay State Changes​

Monitor overlay visibility and state changes:

// Subscribe to overlay visibility changes
overlayViewModel.isVisible.subscribe((isVisible) => {
  console.log('Overlay visibility changed:', isVisible);
});

// Subscribe to current overlay changes
overlayViewModel.currentOverlay.subscribe((overlay) => {
  console.log('Current overlay:', overlay);
});

// Subscribe to overlay queue changes
overlayViewModel.overlayQueue.subscribe((queue) => {
  console.log('Overlay queue length:', queue.length);
});

Helper Methods for Common Use Cases​

Triggering Bet Win Overlays​

function showWinningBetOverlay(betData: IWinningBet) {
  const overlayEvent: IMaestroOverlayEvent = {
    type: OverlayType.WinningBet,
    size: { width: 570, height: 128 },
    position: { top: 50, right: 20 },
    winningBet: betData
  };
  
  const viewModels = SDK.getMaestroViewModels();
  viewModels?.overlayViewModel?.showOverlay(overlayEvent);
}

// Usage
showWinningBetOverlay({
  serverID: 'bet-456',
  notificationText: 'Your over 2.5 goals bet won!',
  amount: 75.25,
  outcome: 'WIN'
});

Positioning Options​

Overlays can be positioned using any combination of positioning properties, in pixels:

// Top-right corner
position: { top: 20, right: 20 }

// Bottom-left corner
position: { bottom: 20, left: 20 }

Best Practices​

  • Check Availability: Always verify that the overlay view model is available before use
  • Positioning: Use consistent positioning across your application
  • Content Validation: Ensure overlay content is properly formatted
  • Error Handling: Implement proper error handling for overlay operations

Next Steps​

Last updated on