SqueezeConfiguredAds

Summary

SqueezeConfiguredAds manages pre-configured advertisements for squeezeback events. These ads can be transcoded to match specific requirements (FPS, scale) and are selected based on airing date, event, stream, geographic location, and other targeting parameters.

Use Cases

  • Pre-load ads for scheduled squeezeback events
  • Configure ads with specific durations for precise ad break filling
  • Target ads by geographic location and language
  • Track ad transcoding status via Matrix job IDs
  • Support both L-bar and dual-box ad layouts
  • Configure ad break identifiers (abid) and ad item identifiers (aiid)

Model Definition

Field Type Description
id integer Unique ad record identifier (auto-generated)
airing_date timestamp Date and time when ad should air (with timezone)
event_id integer Reference to squeeze_event_config (optional)
propeller_stream_id string Propeller stream identifier for targeting
abid string Ad break identifier (e.g., “BREAK1”, “BREAK2”)
aiid string Ad item identifier within the break
geo_lang_loc string Geographic/language/location targeting code
ad_uri string URI to the ad creative file (required)
matrix_job_id string Matrix transcoding job identifier
ad_duration integer Ad duration in seconds (default: 0)
ad_fps numeric(6,2) Target frames per second for transcoding
ad_scale string Target scale/resolution for transcoding (e.g., “1920x1080”)
is_lbar boolean True for L-bar layout, false for dual-box (default: false)
slau string Slot audience unit identifier (e.g., “midroll”, “preroll”)
created_at timestamp Record creation timestamp
updated_at timestamp Record last update timestamp

REST Operations

GET /api/v1/squeeze-configured-ads/{adId}

Return specific configured ad by ID.

Parameters:

  • adId (path, required): Ad record identifier

Response: 200 OK

{
  "id": 123,
  "airing_date": "2025-02-09T18:45:00Z",
  "event_id": 42,
  "propeller_stream_id": "stream-12345",
  "abid": "BREAK1",
  "aiid": "ad-item-001",
  "geo_lang_loc": "US:EN:ALL",
  "ad_uri": "https://cdn.example.com/ads/superbowl-2025-ad1.mp4",
  "matrix_job_id": "mtx-job-987654",
  "ad_duration": 30,
  "ad_fps": 29.97,
  "ad_scale": "1920x1080",
  "is_lbar": false,
  "slau": "midroll",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-20T14:22:00Z"
}

GET /api/v1/squeeze-configured-ads?{query}

Query configured ads with multiple filter parameters.

Query Parameters:

  • airing_date (query, optional): Filter by airing date
  • event_id (query, optional): Filter by event ID
  • propeller_stream_id (query, optional): Filter by stream ID
  • abid (query, optional): Filter by ad break ID
  • geo_lang_loc (query, optional): Filter by geo/lang/location
  • page (query, optional): Page number for pagination (default: 0)
  • page_size (query, optional): Items per page (required for pagination)

Example:

GET /api/v1/squeeze-configured-ads?event_id=42&abid=BREAK1&page=0&page_size=20

Response: 200 OK with array of configured ads

POST /api/v1/squeeze-configured-ads

Create new configured ad.

Request Body:

{
  "airing_date": "2025-02-09T18:45:00Z",
  "event_id": 42,
  "propeller_stream_id": "stream-12345",
  "abid": "BREAK1",
  "aiid": "ad-item-001",
  "geo_lang_loc": "US:EN:ALL",
  "ad_uri": "https://cdn.example.com/ads/superbowl-2025-ad1.mp4",
  "ad_duration": 30,
  "ad_fps": 29.97,
  "ad_scale": "1920x1080",
  "is_lbar": false,
  "slau": "midroll"
}

Response: 201 Created with created ad record

PUT /api/v1/squeeze-configured-ads/{adId}

Update existing configured ad.

Parameters:

  • adId (path, required): Ad record identifier

Request Body: Same as POST (all fields optional for update)

Response: 200 OK with updated ad record

DELETE /api/v1/squeeze-configured-ads/{adId}

Delete configured ad.

Parameters:

  • adId (path, required): Ad record identifier

Response: 204 No Content

Ad Break Identifier (abid)

The abid field identifies which ad break the ad belongs to:

  • Format: String identifier (e.g., “BREAK1”, “BREAK2”, “MIDROLL_1”)
  • Used to group ads that should play in the same break
  • Allows multiple ads to be sequenced within a single break
  • Should match the break identifier used in ad break orchestration calls

Ad Item Identifier (aiid)

The aiid field identifies individual ads within a break:

  • Unique identifier for the specific ad creative
  • Used for tracking and reporting
  • Can be combined with abid for precise ad placement

Geographic Targeting

The geo_lang_loc field allows granular geographic and language targeting:

Format: {country}:{language}:{location}

Examples:

  • US:EN:ALL - United States, English, all locations
  • US:EN:NY - United States, English, New York
  • CA:FR:QC - Canada, French, Quebec
  • UK:EN:LON - United Kingdom, English, London

Transcoding Parameters

Frame Rate (ad_fps)

  • Specify target FPS for transcoding (e.g., 23.98, 29.97, 59.94)
  • If not set, uses original ad frame rate
  • Common values: 23.98, 24, 29.97, 30, 59.94, 60

Scale (ad_scale)

  • Specify target resolution (e.g., “1920x1080”, “1280x720”)
  • Format: {width}x{height}
  • If not set, uses original ad resolution
  • Should match content resolution for best quality

Matrix Job ID

  • Populated when ad is submitted for transcoding
  • Used to track transcoding progress and status
  • Can be used to query Matrix service for job details

Layout Types

Dual-Box Layout (is_lbar: false)

  • Content and ad displayed side-by-side
  • Both boxes visible simultaneously
  • Default layout type

L-Bar Layout (is_lbar: true)

  • Ad positioned in an L-shaped configuration
  • Content squeezed to make room for L-bar
  • Alternative layout for specific use cases

Slot Audience Unit (slau)

The slau field identifies the audience unit/slot type:

  • Common values: “preroll”, “midroll”, “postroll”
  • Used in ad decisioning and reporting
  • Corresponds to Freewheel slot audience unit parameter

Indexing and Performance

The following indexes optimize query performance:

  • idx_squeeze_configured_ads_airing_date - Query by airing date
  • idx_squeeze_configured_ads_event_id - Query by event
  • idx_squeeze_configured_ads_propeller_stream_id - Query by stream
  • idx_squeeze_configured_ads_abid - Query by break ID
  • idx_squeeze_configured_ads_aiid - Query by ad item ID
  • idx_squeeze_configured_ads_geo_lang_loc - Query by location
  • idx_squeeze_configured_ads_filters - Composite index for multi-filter queries
  • idx_squeeze_configured_ads_break_geo - Break and geo combined queries

Best Practices

  1. Pre-populate ads before event start for faster ad breaks
  2. Set accurate durations to ensure precise ad break timing
  3. Use consistent abid naming across related ads
  4. Pre-transcode ads to match content specs (FPS, resolution)
  5. Test geo targeting before live events
  6. Monitor matrix_job_id for transcoding failures
  7. Update airing_date if event schedule changes
  8. Clean up old ads after event completion

Example: Bulk Ad Configuration 

# Create multiple ads for a single break
curl -X POST https://bakery.vtg.paramount.tech/api/v1/squeeze-configured-ads \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d '{
    "airing_date": "2025-02-09T18:45:00Z",
    "event_id": 42,
    "abid": "BREAK1",
    "aiid": "ad-001",
    "ad_uri": "https://cdn.example.com/ads/ad1.mp4",
    "ad_duration": 30,
    "ad_fps": 29.97,
    "ad_scale": "1920x1080",
    "is_lbar": false,
    "slau": "midroll",
    "geo_lang_loc": "US:EN:ALL"
  }'

curl -X POST https://bakery.vtg.paramount.tech/api/v1/squeeze-configured-ads \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d '{
    "airing_date": "2025-02-09T18:45:30Z",
    "event_id": 42,
    "abid": "BREAK1",
    "aiid": "ad-002",
    "ad_uri": "https://cdn.example.com/ads/ad2.mp4",
    "ad_duration": 15,
    "ad_fps": 29.97,
    "ad_scale": "1920x1080",
    "is_lbar": false,
    "slau": "midroll",
    "geo_lang_loc": "US:EN:ALL"
  }'