Ad Break Orchestration

Swagger API Documentation

Summary

Ad break orchestration endpoints control the lifecycle of squeezeback ad breaks during live events. These endpoints allow starting, extending, and terminating ad breaks dynamically, enabling real-time control over when and how ads are inserted into the stream.

Overview

Squeezeback ad breaks are orchestrated through a three-phase lifecycle:

  1. Start - Initiate a new ad break with specified duration and ads
  2. Extend - Prolong an active ad break with additional time/ads
  3. Terminate - End an active ad break and return to normal content

API Documentation

See the Swagger API Documentation for complete API details including endpoints, request/response schemas, parameters, and examples.

Ad Break Lifecycle 

┌─────────────┐
│   IDLE      │
│  (No Break) │
└──────┬──────┘
       │
       │ POST /start-ad-break
       ▼
┌─────────────┐
│   ACTIVE    │◄────────┐
│ (Break Run) │         │
└──────┬──────┘         │
       │                │
       │ POST /extend-ad-break
       │                │
       │                │
       │ POST /terminate-ad-break
       │                │
       ▼                │
┌─────────────┐         │
│ TERMINATED  │         │
│  (Cleanup)  │         │
└──────┬──────┘         │
       │                │
       └────────────────┘
       (Back to IDLE)

Integration

Refer to the Swagger API Documentation for detailed integration examples and request/response schemas.

Best Practices

  1. Duration Planning
    • Allow buffer time for ad transitions
    • Consider network latency in timing
  2. Break Identifiers
    • Use consistent naming conventions
    • Track break IDs for analytics
  3. Error Handling
    • Check response status before assuming success
    • Implement retries for network failures
  4. Ad Selection
    • Pre-configure ads for best performance
    • Use ad tags for dynamic decisioning
    • Combine both for fallback scenarios
  5. Timing
    • Start breaks slightly before natural content breaks
    • Monitor actual vs. planned duration
  6. Layout Choice
    • Use dual-box (default) for standard side-by-side layout
    • Use L-bar when vertical space is premium (L-bar not yet implemented)
    • Match layout to content and ad creative
  7. Testing
    • Test full lifecycle before live
    • Verify ad URIs are accessible
    • Test network failure scenarios

Monitoring

Key metrics to monitor:

  • Break start/extend/terminate latency
  • Ad playback errors
  • Break duration accuracy (planned vs. actual)
  • Concurrent viewers during breaks
  • Ad creative load times

Security

All ad break orchestration endpoints require proper authentication and authorization. See the Swagger API Documentation for security requirements.