Ad Break Orchestration

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:

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

Start Ad Break

POST `/api/v1/squeezeback/start-ad-break`

Initiates a new ad break for a squeezeback event.

Request Body:

{
  "asset_id": "superbowl-2025",
  "break_duration": 120,
  "ad_break_id": "BREAK1",
  "ad_uris": [
    "https://cdn.example.com/ads/ad1.mp4",
    "https://cdn.example.com/ads/ad2.mp4",
    "https://cdn.example.com/ads/ad3.mp4"
  ],
  "ad_tag_url": "https://freewheel.example.com/ad/g/1?...",
  "is_lbar": false
}

Parameters:

Field	Type	Required	Description
`asset_id`	string	Yes	Asset identifier for the event
`break_duration`	integer	Yes	Total ad break duration in seconds
`ad_break_id`	string	No	Identifier for the ad break (e.g., “BREAK1”)
`ad_uris`	array	No	Array of ad creative URIs to play sequentially
`ad_tag_url`	string	No	VAST/VMAP ad tag URL for dynamic ad decisioning
`is_lbar`	boolean	No	Use L-bar layout (default: false for dual-box)

Response: 200 OK

{
  "status": "started",
  "asset_id": "superbowl-2025",
  "break_id": "BREAK1",
  "break_duration": 120,
  "ads_count": 3,
  "start_time": "2025-02-09T18:45:00Z"
}

Error Responses:

400 Bad Request - Invalid parameters or event not found
409 Conflict - Ad break already in progress
500 Internal Server Error - Server error during break initialization

Usage Notes

Either ad_uris or ad_tag_url should be provided (or both)
If both are provided, ad_uris takes precedence
break_duration should match or exceed total ad durations
Ad break starts immediately upon successful request

Extend Ad Break

POST `/api/v1/squeezeback/extend-ad-break`

Extends an active ad break with additional time and/or ads.

Request Body:

{
  "asset_id": "superbowl-2025",
  "additional_duration": 30,
  "ad_uris": [
    "https://cdn.example.com/ads/ad4.mp4"
  ]
}

Parameters:

Field	Type	Required	Description
`asset_id`	string	Yes	Asset identifier for the event
`additional_duration`	integer	Yes	Additional seconds to extend the break
`ad_uris`	array	No	Additional ad URIs to append to the break
`ad_tag_url`	string	No	Additional VAST/VMAP tag for more ads

Response: 200 OK

{
  "status": "extended",
  "asset_id": "superbowl-2025",
  "new_duration": 150,
  "additional_ads_count": 1,
  "extended_at": "2025-02-09T18:46:30Z"
}

Error Responses:

400 Bad Request - Invalid parameters or no active break
404 Not Found - No active ad break for specified asset
500 Internal Server Error - Server error during extension

Usage Notes

Can only extend an ad break that is currently active
Multiple extend calls can be made to the same break
Extension takes effect immediately
Original break configuration (layout, etc.) is maintained

Terminate Ad Break

POST `/api/v1/squeezeback/terminate-ad-break`

Terminates an active ad break and returns to normal content display.

Request Body:

{
  "asset_id": "superbowl-2025"
}

Parameters:

Field	Type	Required	Description
`asset_id`	string	Yes	Asset identifier for the event

Response: 200 OK

{
  "status": "terminated",
  "asset_id": "superbowl-2025",
  "break_duration_actual": 145,
  "terminated_at": "2025-02-09T18:47:25Z"
}

Error Responses:

400 Bad Request - Invalid asset_id
404 Not Found - No active ad break for specified asset
500 Internal Server Error - Server error during termination

Usage Notes

Immediately ends the ad break regardless of remaining duration
Triggers squeeze-out animation back to full-screen content
Cleans up ad break state for the asset
Safe to call even if break has naturally completed

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 Examples

Example 1: Simple Ad Break

# Start a 60-second ad break with pre-configured ads
curl -X POST https://bakery.vtg.paramount.tech/api/v1/squeezeback/start-ad-break \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d '{
    "asset_id": "my-event",
    "break_duration": 60,
    "ad_break_id": "BREAK1",
    "ad_uris": [
      "https://cdn.example.com/ads/30sec-ad1.mp4",
      "https://cdn.example.com/ads/30sec-ad2.mp4"
    ],
    "is_lbar": false
  }'

# Wait 60 seconds or manually terminate
sleep 60

# Terminate the break
curl -X POST https://bakery.vtg.paramount.tech/api/v1/squeezeback/terminate-ad-break \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d '{
    "asset_id": "my-event"
  }'

Example 2: Dynamic Ad Break with Extensions

# Start with initial duration
curl -X POST https://bakery.vtg.paramount.tech/api/v1/squeezeback/start-ad-break \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d '{
    "asset_id": "live-sports",
    "break_duration": 90,
    "ad_break_id": "TIMEOUT1",
    "ad_tag_url": "https://freewheel.tv/ad/g/1?nw=520311&...",
    "is_lbar": false
  }'

# Game timeout extended - add more time
sleep 45

curl -X POST https://bakery.vtg.paramount.tech/api/v1/squeezeback/extend-ad-break \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d '{
    "asset_id": "live-sports",
    "additional_duration": 30,
    "ad_tag_url": "https://freewheel.tv/ad/g/1?nw=520311&..."
  }'

# Game resumes early - terminate
curl -X POST https://bakery.vtg.paramount.tech/api/v1/squeezeback/terminate-ad-break \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d '{
    "asset_id": "live-sports"
  }'

Example 3: Using Configured Ads

# Assume ads already configured in squeeze_configured_ads table
# Query configured ads for the break
curl https://bakery.vtg.paramount.tech/api/v1/squeeze-configured-ads?event_id=42&abid=BREAK1 \
  -H "Authorization: Bearer $JWT_TOKEN"

# Returns:
# [
#   {"ad_uri": "https://cdn.example.com/ads/ad1.mp4", "ad_duration": 30, ...},
#   {"ad_uri": "https://cdn.example.com/ads/ad2.mp4", "ad_duration": 15, ...}
# ]

# Start break with these URIs
curl -X POST https://bakery.vtg.paramount.tech/api/v1/squeezeback/start-ad-break \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d '{
    "asset_id": "my-event",
    "break_duration": 45,
    "ad_break_id": "BREAK1",
    "ad_uris": [
      "https://cdn.example.com/ads/ad1.mp4",
      "https://cdn.example.com/ads/ad2.mp4"
    ],
    "is_lbar": false
  }'

Best Practices

Duration Planning
- Set break_duration slightly longer than total ad durations
- Allow buffer time for ad transitions
- Consider network latency in timing
Break Identifiers
- Use consistent naming: “BREAK1”, “BREAK2”, etc.
- Include context: “TIMEOUT1”, “HALFTIME”, “INNING3”
- Track break IDs for analytics
Error Handling
- Check response status before assuming success
- Implement retries for network failures
- Handle 409 conflicts gracefully (break already active)
Ad Selection
- Pre-configure ads in squeeze_configured_ads for best performance
- Use ad tags for dynamic decisioning
- Combine both for fallback scenarios
Timing
- Start breaks slightly before natural content breaks
- Monitor actual vs. planned duration
- Use extend to handle unpredictable break lengths
Layout Choice
- Use dual-box (default) for standard side-by-side layout
- Use L-bar when vertical space is premium
- Match layout to content and ad creative
Testing
- Test full lifecycle (start → extend → terminate) 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:

Valid JWT token in Authorization header
Appropriate permissions for the asset/event
HTTPS for production environments

Ad Break Orchestration

Summary

Overview

Start Ad Break

POST /api/v1/squeezeback/start-ad-break

Usage Notes

Extend Ad Break

POST /api/v1/squeezeback/extend-ad-break

Usage Notes

Terminate Ad Break

POST /api/v1/squeezeback/terminate-ad-break

Usage Notes

Ad Break Lifecycle

Integration Examples

Example 1: Simple Ad Break

Example 2: Dynamic Ad Break with Extensions

Example 3: Using Configured Ads

Best Practices

Monitoring

Security

POST `/api/v1/squeezeback/start-ad-break`

POST `/api/v1/squeezeback/extend-ad-break`

POST `/api/v1/squeezeback/terminate-ad-break`