Using events

React to the ad lifecycle through the source event bus

The advertising packages add ad-related events to the source's event bus. Subscribe to them the same way as any other source event, through source.events.

const sourceApi = player.sources.add(sourceConfig);

sourceApi.events.on('ad-started', (event) => console.info('Ad started', event.ad));
sourceApi.events.on('ad-finished', (event) => console.info('Ad finished', event.ad));
sourceApi.events.on('ad-quartile', (event) => console.info('Quartile', event.quartile));
sourceApi.events.on('ad-error', (event) => console.warn('Ad error', event.error));

sourceApi.ads.schedule({
  tag: { type: 'vast', url: 'https://YOUR-AD-SERVER/preroll.xml' },
  position: 'pre',
});

Event names

Events are organised into three scopes — ad break, ad pod, and individual ad:

enum AdvertisingEvent {
  // Ad break
  AdBreakAdded = 'ad-break-added',
  AdBreakChanged = 'ad-break-changed',
  AdBreakRemoved = 'ad-break-removed',
  AdBreakStarted = 'ad-break-started',
  AdBreakError = 'ad-break-error',
  AdBreakFinished = 'ad-break-finished',

  // Ad pod
  AdPodAdded = 'ad-pod-added',
  AdPodRemoved = 'ad-pod-removed',
  AdPodLoaded = 'ad-pod-loaded',
  AdPodStarted = 'ad-pod-started',
  AdPodError = 'ad-pod-error',
  AdPodFinished = 'ad-pod-finished',

  // Ad
  AdStarted = 'ad-started',
  AdFinished = 'ad-finished',
  AdSkippableStateChanged = 'ad-skippable-state-changed',
  AdSkipped = 'ad-skipped',
  AdError = 'ad-error',
  AdClicked = 'ad-clicked',
  AdQuartile = 'ad-quartile',
  AdPlaying = 'ad-playing',
  AdPaused = 'ad-paused',
  AdProgress = 'ad-progress',
  AdVolumeChanged = 'ad-volume-changed',
}

Payloads

Every payload carries the entity it concerns. Ad-scoped events also carry the enclosing adPod, and specific events add extra fields:

Event	Payload fields
`ad-break-*` (added/changed/removed/started/finished)	`adBreak`
`ad-break-error`	`adBreak`, `error`
`ad-pod-*` (added/removed/loaded/started/finished)	`adPod`
`ad-pod-error`	`adPod`, `error`
`ad-started` / `ad-finished` / `ad-playing` / `ad-paused` / `ad-skipped` / `ad-skippable-state-changed`	`adPod`, `ad`
`ad-error`	`adPod`, `ad`, `error`
`ad-quartile`	`adPod`, `ad`, `quartile`
`ad-clicked`	`adPod`, `ad`, `clickThroughUrl`
`ad-progress`	`adPod`, `ad`, `currentTime`, `duration`
`ad-volume-changed`	`adPod`, `ad`, `volume`

📘
ad-pod-loaded vs ad-pod-started
ad-pod-loaded fires when the pod's creatives have been resolved; ad-pod-started fires when its playback begins. ad-skippable-state-changed does not carry a boolean — read the current skippable state from the Ad object (ad.canSkip).

Event ordering

Container events wrap the events they contain, in a guaranteed order:

ad-break-added is emitted before the ad-pod-added for its pods.
ad-break-started is emitted before the ad-started of the first ad in the break.
ad-pod-finished is emitted before ad-break-finished.
On removal, ad-pod-removed is emitted before ad-break-removed.

You can rely on this ordering when building ad UIs or analytics on top of the event stream.

Event names

Payloads

ad-pod-loaded vs ad-pod-started

Event ordering

`ad-pod-loaded` vs `ad-pod-started`