Skip to main content
View as Markdown

Ads Cue Points - Kaltura Player

Kaltura Ad Cue Points API​

Ad cue points define when and how advertisements play during video content.
They support VAST and VPAID protocols for pre-roll, mid-roll, post-roll,
and overlay ad insertion.

Base URL: $KALTURA_SERVICE_URL (e.g., https://www.kaltura.com/api_v3)
Auth: KS via ks parameter (admin KS with disableentitlement for full access)
Format: format=1 for JSON responses
Service: cuepoint_cuepoint (shared with all cue point types)
objectType: KalturaAdCuePoint
Prerequisite: Cue Points Hub for base cue point concepts and shared CRUD

1. When to Use​

  • Video monetization — Insert pre-roll, mid-roll, and post-roll advertisements into video content to generate ad revenue from your video library.
  • Publisher ad management — Define ad break positions on the video timeline and link them to VAST or VPAID ad feeds served by your ad network.
  • Overlay promotions — Display non-linear banner overlays at specific moments during playback without interrupting the video content.
  • Sponsored content integration — Place sponsor messages at precise points in educational, entertainment, or event recordings.
  • Dynamic ad scheduling — Programmatically manage ad cue points across large content libraries, enabling bulk ad insertion and per-entry ad customization.

2. Prerequisites​

  • KS (Kaltura Session): Admin KS (type=2) with disableentitlement for creating and managing ad cue points.
  • Cue Points plugin: The cuePoint and adCuePoint server plugins must be enabled on the account.
  • Ad server: A VAST or VPAID-compliant ad server providing XML ad feeds at accessible URLs.
  • Player ad plugin: To trigger ads during playback, enable the kalturaCuepoints and bumper plugins in the player configuration.
  • Session management: See Session Guide for KS generation and privilege scoping.

3. Ad Types​

ValueNameDescription
1VIDEOLinear ad — pauses video content
2OVERLAYNon-linear ad — displays over video content

4. Fields (in addition to base)​

FieldTypeDescription
protocolTypeintAd protocol (insert-only, immutable after creation)
sourceUrlstringURL to VAST/VPAID XML feed
adTypeint1=VIDEO (linear), 2=OVERLAY (non-linear)
titlestringAd title (max 250 chars)
endTimeintEnd time in milliseconds
durationintDuration in milliseconds

5. Protocol Types​

ValueNameDescription
0CUSTOMCustom ad protocol
1VASTVAST 1.0
2VAST_2_0VAST 2.0
3VPAIDVPAID

6. Ad Placement​

PlacementstartTimeDescription
Pre-roll0Plays before video content
Mid-rollN (in ms)Plays at position N in the video
Post-rolldurationPlays after video content
OverlayanyNon-linear overlay with adType=2 and startTime/endTime defining the visible window

7. Create a Mid-Roll Ad​

curl -X POST "$KALTURA_SERVICE_URL/service/cuepoint_cuepoint/action/add" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "cuePoint[objectType]=KalturaAdCuePoint" \
  -d "cuePoint[entryId]=$KALTURA_ENTRY_ID" \
  -d "cuePoint[startTime]=120000" \
  -d "cuePoint[protocolType]=2" \
  -d "cuePoint[sourceUrl]=https://example.com/vast/midroll.xml" \
  -d "cuePoint[adType]=1" \
  -d "cuePoint[title]=Sponsor message"

8. Create an Overlay Ad​

curl -X POST "$KALTURA_SERVICE_URL/service/cuepoint_cuepoint/action/add" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "cuePoint[objectType]=KalturaAdCuePoint" \
  -d "cuePoint[entryId]=$KALTURA_ENTRY_ID" \
  -d "cuePoint[startTime]=30000" \
  -d "cuePoint[endTime]=45000" \
  -d "cuePoint[protocolType]=1" \
  -d "cuePoint[sourceUrl]=https://example.com/vast/overlay.xml" \
  -d "cuePoint[adType]=2" \
  -d "cuePoint[title]=Banner overlay"

Overlay ads use adType=2 with both startTime and endTime to define the visible window.

9. Protocol Immutability​

protocolType cannot be changed after creation — attempting to update it returns PROPERTY_VALIDATION_NOT_UPDATABLE. Plan the protocol type before creating ad cue points.

10. Player Ad Plugin Integration​

The Player v7 bumper plugin handles ad playback based on ad cue points. Configure the player with the kalturaCuepoints core plugin to load ad cue point data:

plugins: {
  kalturaCuepoints: {},
  bumper: {}
}

The bumper plugin reads ad cue points and triggers VAST/VPAID requests at the specified startTime.

11. Searching Ad Cue Points​

Ad cue point titles are indexed in eSearch via KalturaESearchCuePointItem with fieldName=name. See Cue Points Hub — eSearch Integration for query examples.

12. Error Handling​

ErrorCauseFix
PROPERTY_VALIDATION_CANNOT_BE_NULLList without identifying filterInclude entryIdEqual, entryIdIn, idEqual, or idIn
INVALID_CUE_POINT_IDCue point not found or already deletedVerify ID exists and status is not DELETED
PROPERTY_VALIDATION_NOT_UPDATABLEUpdating protocolType on ad cue pointprotocolType is immutable after creation

13. Best Practices​

  • Times are in milliseconds. A cue point at 2 minutes = startTime=120000.
  • Ad protocolType is set once. Plan the protocol type before creating ad cue points — it cannot be changed.
  • Use adType=1 for linear (video) ads that pause content, adType=2 for overlay (non-linear) ads.
  • Set endTime for overlay ads to define the visible window. Linear ads play their full duration.
  • Use VAST 2.0 (protocolType=2) for the most widely supported ad format.