theoplayer
Version:
THEOplayer is the universal video player solution, enabling you to quickly deliver cross-platform content playback.
1,714 lines (1,704 loc) • 424 kB
TypeScript
/**
* Fired when an event occurs.
*
* @category Events
* @public
*/
interface Event<TType extends string = string> {
/**
* The type of the event.
*/
type: TType;
/**
* The creation date of the event.
*/
date: Date;
}
/**
* The function to be executed when an event occurred.
*
* @category Events
* @public
*/
type EventListener<TEvent extends Event> = (event: TEvent) => void;
/**
* A record used to map events.
* Each entry contains an event name with associated event interface.
*
* @example
* ```
* {
* 'statechange': StateChangeEvent,
* 'error': ErrorEvent
* }
* ```
*
* @category Events
* @public
*/
type EventMap<TType extends string> = {
[type in TType]: Event;
};
/**
* Helper type to extract string keys from type objects.
*
* @public
*/
type StringKeyOf<T> = Extract<keyof T, string>;
/**
* Dispatches events that are fired.
*
* @category Events
* @public
*/
interface EventDispatcher<TEventMap extends EventMap<StringKeyOf<TEventMap>>> {
/**
* Add the given listener for the given event type(s).
*
* @param type - The type of the event.
* @param listener - The callback which is executed when the event occurs.
*/
addEventListener<TType extends StringKeyOf<TEventMap>>(type: TType | readonly TType[], listener: EventListener<TEventMap[TType]>): void;
/**
* Remove the given listener for the given event type(s).
*
* @param type - The type of the event.
* @param listener - The callback which will be removed.
*/
removeEventListener<TType extends StringKeyOf<TEventMap>>(type: TType | readonly TType[], listener: EventListener<TEventMap[TType]>): void;
}
/**
* Fired when the ad has stalled playback to buffer.
*
* @category Ads
* @category Events
* @public
*/
interface AdBufferingEvent extends AdEvent<'adbuffering'> {
/**
* The ad which is buffered.
*/
readonly ad: GoogleImaAd;
}
/**
* Fired when an ads list is loaded.
*
* @category Ads
* @category Events
* @public
*/
interface AdMetadataEvent extends Event<'admetadata'> {
}
/**
* The Google DAI API.
*
* @remarks
* <br/> - Available since v3.7.0.
*
* @category Ads
* @public
*/
interface GoogleDAI {
/**
* Returns the content time without ads for a given stream time. Returns the given stream time for live streams.
*
* @param time - The stream time with inserted ads (in seconds).
*/
contentTimeForStreamTime(time: number): number;
/**
* Returns the stream time with ads for a given content time. Returns the given content time for live streams.
*
* @param time - The content time without any ads (in seconds).
*/
streamTimeForContentTime(time: number): number;
/**
* Replaces all the ad tag parameters used for upcoming ad requests for a live stream.
*
* @param adTagParameters - The new ad tag parameters.
*/
replaceAdTagParameters(adTagParameters?: Record<string, string>): void;
/**
* Whether snapback is enabled. When enabled and the user seeks over multiple ad breaks, the last ad break that was seeked past will be played.
*/
snapback: boolean;
/**
* A source transformer which will receive the source as returned from Google DAI before loading it in the player. This capability can be useful
* if you need to add authentication tokens or signatures to the source URL as returned by Google.
*/
sourceTransformer: (url: string) => string | Promise<string>;
}
/**
* A synchronous or asynchronous return type
*
* @public
*/
type MaybeAsync<T> = T | PromiseLike<T>;
/**
* A code that indicates the type of error that has occurred.
*
* @category Errors
* @public
*/
declare enum ErrorCode {
/**
* The configuration provided is invalid.
*/
CONFIGURATION_ERROR = 1000,
/**
* The license provided is invalid.
*/
LICENSE_ERROR = 2000,
/**
* The provided license does not contain the current domain.
*/
LICENSE_INVALID_DOMAIN = 2001,
/**
* The current source is not allowed in the license provided.
*/
LICENSE_INVALID_SOURCE = 2002,
/**
* The license has expired.
*/
LICENSE_EXPIRED = 2003,
/**
* The provided license does not contain the necessary feature.
*/
LICENSE_INVALID_FEATURE = 2004,
/**
* The source provided is not valid.
*/
SOURCE_INVALID = 3000,
/**
* The provided source is not supported.
*/
SOURCE_NOT_SUPPORTED = 3001,
/**
* The manifest could not be loaded.
*/
MANIFEST_LOAD_ERROR = 4000,
/**
* An Error related to Cross-origin resource sharing (CORS).
*
* @remarks
* <br/> - See {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS | Cross-Origin Resource Sharing (CORS)}.
*/
MANIFEST_CORS_ERROR = 4001,
/**
* The manifest could not be parsed.
*/
MANIFEST_PARSE_ERROR = 4002,
/**
* The media is not supported.
*/
MEDIA_NOT_SUPPORTED = 5000,
/**
* The media could not be loaded.
*/
MEDIA_LOAD_ERROR = 5001,
/**
* The media could not be decoded.
*/
MEDIA_DECODE_ERROR = 5002,
/**
* An error related to playback through AVPlayer in the iOS or tvOS SDK.
*/
MEDIA_AVPLAYER_ERROR = 5003,
/**
* The fetching process for the media resource was aborted by the user agent at the user's request.
*/
MEDIA_ABORTED = 5004,
/**
* An error related to network has been detected.
*/
NETWORK_ERROR = 6000,
/**
* The network has timed out.
*/
NETWORK_TIMEOUT = 6001,
/**
* An error related to the content protection.
*/
CONTENT_PROTECTION_ERROR = 7000,
/**
* The DRM provided is not supported on this platform.
*/
CONTENT_PROTECTION_NOT_SUPPORTED = 7001,
/**
* The media is DRM protected, but no content protection configuration was provided.
*/
CONTENT_PROTECTION_CONFIGURATION_MISSING = 7002,
/**
* The content protection configuration is invalid.
*/
CONTENT_PROTECTION_CONFIGURATION_INVALID = 7003,
/**
* The DRM initialization data could not be parsed.
*/
CONTENT_PROTECTION_INITIALIZATION_INVALID = 7004,
/**
* The content protection's certificate could not be loaded.
*/
CONTENT_PROTECTION_CERTIFICATE_ERROR = 7005,
/**
* The content protection's certificate is invalid.
*/
CONTENT_PROTECTION_CERTIFICATE_INVALID = 7006,
/**
* The content protection's license could not be loaded.
*/
CONTENT_PROTECTION_LICENSE_ERROR = 7007,
/**
* The content protection's license is invalid.
*/
CONTENT_PROTECTION_LICENSE_INVALID = 7008,
/**
* The content protection's key has expired.
*/
CONTENT_PROTECTION_KEY_EXPIRED = 7009,
/**
* The content protection's key is missing.
*/
CONTENT_PROTECTION_KEY_MISSING = 7010,
/**
* All qualities require HDCP, but the current output does not fulfill HDCP requirements.
*/
CONTENT_PROTECTION_OUTPUT_RESTRICTED = 7011,
/**
* Something went wrong in the internal logic of the content protection system.
*/
CONTENT_PROTECTION_INTERNAL_ERROR = 7012,
/**
* Loading subtitles has failed.
*/
SUBTITLE_LOAD_ERROR = 8000,
/**
* Loading subtitles has failed due to CORS.
*
* @remarks
* <br/> - See {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS | Cross-Origin Resource Sharing (CORS)}.
*/
SUBTITLE_CORS_ERROR = 8001,
/**
* Parsing subtitles has failed.
*/
SUBTITLE_PARSE_ERROR = 8002,
/**
* This error occurs when VR is not supported on the current platform.
*/
VR_PLATFORM_UNSUPPORTED = 9000,
/**
* Changing the presentation to VR was not possible.
*/
VR_PRESENTATION_ERROR = 9001,
/**
* Something went wrong with an ad.
*/
AD_ERROR = 10000,
/**
* An ad blocker has been detected.
*/
AD_BLOCKER_DETECTED = 10001,
/**
* Changing the presentation to fullscreen was not possible.
*/
FULLSCREEN_ERROR = 11000,
/**
* Changing the presentation to picture-in-picture was not possible.
*/
PICTURE_IN_PICTURE_ERROR = 11001,
/**
* Something went wrong while caching a source.
*/
CACHE_SOURCE_ERROR = 12000,
/**
* Something went wrong while caching content protection's license.
*/
CACHE_CONTENT_PROTECTION_ERROR = 12001,
/**
* Something went wrong with THEOlive playback.
*/
THEO_LIVE_UNKNOWN_ERROR = 13000,
/**
* The THEOlive channel could not be played because it was not found. This can be because it was never created, it has been deleted or locked.
*/
THEO_LIVE_CHANNEL_NOT_FOUND = 13001,
/**
* The THEOlive channel is a demo channel and the demo window has expired.
*/
THEO_LIVE_END_OF_DEMO = 13002,
/**
* A fatal error occurred regarding THEOlive analytics.
*/
THEO_LIVE_ANALYTICS_ERROR = 13003
}
/**
* The category of an error.
*
* @category Errors
* @public
*/
declare enum ErrorCategory {
/**
* This category clusters all errors related to the configuration.
*/
CONFIGURATION = 1,
/**
* This category clusters all errors related to the license.
*/
LICENSE = 2,
/**
* This category clusters all errors related to the source.
*/
SOURCE = 3,
/**
* This category clusters all errors related to the manifest.
*/
MANIFEST = 4,
/**
* This category clusters all errors related to the media.
*/
MEDIA = 5,
/**
* This category clusters all errors related to the network.
*/
NETWORK = 6,
/**
* This category clusters all errors related to the content protection.
*/
CONTENT_PROTECTION = 7,
/**
* This category clusters all errors related to the subtitles.
*/
SUBTITLE = 8,
/**
* This category clusters all errors related to VR.
*/
VR = 9,
/**
* This category clusters all errors related to ads.
*/
AD = 10,
/**
* This category clusters all errors related to fullscreen.
*/
FULLSCREEN = 11,
/**
* This category clusters all errors related to caching.
*/
CACHE = 12,
/**
* This category clusters all errors related to THEOlive.
*/
THEOLIVE = 13
}
/**
* The category of an error.
*
* @category Errors
* @public
*/
declare namespace ErrorCategory {
/**
* Determine the `ErrorCategory` of the given {@link ErrorCode}.
*
* @param code - The {@link ErrorCode} to determine the `ErrorCategory` of.
*/
function fromCode(code: ErrorCode): ErrorCategory;
}
/**
* A handler for a server-side ad integration.
*
* You can implement one or more of these methods to hook into various parts
* of the player's lifecycle and perform your integration-specific ad handling.
*
* Use the {@link ServerSideAdIntegrationController} provided by {@link ServerSideAdIntegrationFactory}
* to update the state of your integration.
*
* @see {@link Ads.registerServerSideIntegration}
*
* @category Ads
*/
interface ServerSideAdIntegrationHandler {
/**
* Handler which will be called when a new source is loaded into the player.
*
* This allows the integration to transform the source description,
* e.g. by calling an external service to replace {@link TypedSource.src | the content URL},
* or by adding a fixed pre-roll linear ad to {@link SourceDescription.ads | the list of ads}.
*
* @remarks
* - If this handler throws an error, the player fires a fatal {@link PlayerEventMap.error | `error`} event
* (as if by calling {@link ServerSideAdIntegrationController.fatalError}).
*
* @param source
*/
setSource?(source: SourceDescription): MaybeAsync<SourceDescription>;
/**
* Handler which will be called when an ad is requested to be skipped.
*
* To skip the ad, the handler should call {@link ServerSideAdIntegrationController.skipAd}.
*
* @remarks
* - This is only called for ads whose {@link Ad.integration}
* matches {@link ServerSideAdIntegrationController.integration}.
* - If this handler is missing, the player will always skip the ad
* by calling {@link ServerSideAdIntegrationController.skipAd}.
* - If this handler throws an error, the player fires a non-fatal {@link AdsEventMap.aderror | `aderror`} event
* (as if by calling {@link ServerSideAdIntegrationController.error}).
*
* @param ad
*/
skipAd?(ad: Ad): void;
/**
* Handler which will be called before a new source is loaded into the player,
* or before the player is destroyed.
*
* This allows the integration to clean up any source-specific resources,
* such as scheduled ads or pending HTTP requests.
*
* @remarks
* - If this handler is missing, the player will remove all remaining ads
* by calling {@link ServerSideAdIntegrationController.removeAllAds}.
* - If this handler throws an error, the player fires a fatal {@link PlayerEventMap.error | `error`} event
* (as if by calling {@link ServerSideAdIntegrationController.fatalError}).
*/
resetSource?(): MaybeAsync<void>;
/**
* Handler which will be called when the player is {@link ChromelessPlayer.destroy | destroyed}.
*
* This allows the integration to clean up any resources, such as DOM elements or event listeners.
*/
destroy?(): MaybeAsync<void>;
}
/**
* A controller to be used by your {@link ServerSideAdIntegrationHandler}
* to update the state of your custom server-side ad integration.
*
* @see {@link Ads.registerServerSideIntegration}
*
* @category Ads
*/
interface ServerSideAdIntegrationController {
/**
* The identifier for this integration, as it was passed to {@link Ads.registerServerSideIntegration}.
*/
readonly integration: CustomAdIntegrationKind;
/**
* The scheduled ads managed by this integration.
*
* @remarks
* Use {@link ServerSideAdIntegrationController.createAd} and {@link ServerSideAdIntegrationController.removeAd} to add or remove ads.
*/
readonly ads: readonly Ad[];
/**
* The scheduled ad breaks managed by this integration.
*
* @remarks
* Use {@link ServerSideAdIntegrationController.createAdBreak} and {@link ServerSideAdIntegrationController.removeAdBreak} to add or remove ad breaks.
*/
readonly adBreaks: readonly AdBreak[];
/**
* Create a new ad.
*
* @remarks
* - The ad will be added to {@link Ads.scheduledAds}.
*
* @param init
* The initial properties to be set on the created ad.
* @param [adBreak]
* If given, appends the ad to the given existing {@link AdBreak}.
* Otherwise, appends the ad to a new or existing {@link AdBreak} with the configured {@link AdInit.timeOffset}.
*/
createAd(init: AdInit, adBreak?: AdBreak): Ad;
/**
* Update the given ad.
*
* @param ad
* The ad to be updated.
* @param init
* The properties to be updated on the ad.
*/
updateAd(ad: Ad, init: Partial<AdInit>): void;
/**
* Update the playback progression of the given ad.
*
* @remarks
* - The player will fire progression events such as {@link AdsEventMap.adfirstquartile},
* {@link AdsEventMap.admidpoint} and {@link AdsEventMap.adthirdquartile}.
*
* @param ad
* The ad to be updated.
* @param progress
* The playback progress, as a number between 0 (at the start of the ad) and 1 (at the end of the ad).
* @throws Error
* If the ad is not {@link ServerSideAdIntegrationController.beginAd | started}.
*/
updateAdProgress(ad: Ad, progress: number): void;
/**
* Begin the given ad.
*
* @remarks
* - The ad will be added to {@link Ads.currentAds}.
* - An {@link AdsEventMap.adbegin} event will be fired.
*
* @param ad
*/
beginAd(ad: Ad): void;
/**
* End the given ad.
*
* @remarks
* - The ad will be removed from {@link Ads.currentAds}.
* - If the ad was currently playing, an {@link AdsEventMap.adend} event will be fired.
*
* @param ad
*/
endAd(ad: Ad): void;
/**
* Skip the given ad.
*
* @remarks
* - The ad will be removed from {@link Ads.currentAds}.
* - If the ad was currently playing, an {@link AdsEventMap.adskip} event will be fired.
*
* @param ad
*/
skipAd(ad: Ad): void;
/**
* Remove the given ad.
*
* @remarks
* - The ad will be removed from {@link Ads.currentAds} and {@link Ads.scheduledAds}.
* - If the ad was currently playing, it will first be {@link ServerSideAdIntegrationController.endAd | ended}.
*
* @param ad
*/
removeAd(ad: Ad): void;
/**
* Create a new ad break.
*
* This can be used to indicate where ad breaks can be expected in advance,
* before populating those ad breaks with ads.
*
* @remarks
* - The ad break will be added to {@link ServerSideAdIntegrationController.adBreaks} and {@link Ads.scheduledAdBreaks}.
*
* @param init
* The initial properties to be set on the created ad break.
* @throws Error
* If there is already an existing ad break with the given {@link AdBreakInit.timeOffset}.
*/
createAdBreak(init: AdBreakInit): AdBreak;
/**
* Update the given ad break.
*
* @param adBreak
* The ad break to be updated.
* @param init
* The properties to be updated on the ad break.
*/
updateAdBreak(adBreak: AdBreak, init: Partial<AdBreakInit>): void;
/**
* Remove the given ad break and all of its ads.
*
* @remarks
* - The ad break will be removed from {@link ServerSideAdIntegrationController.adBreaks} and {@link Ads.scheduledAdBreaks}.
* - Any remaining ads in the ad break will be {@link ServerSideAdIntegrationController.removeAd | removed}.
*
* @param adBreak
* The ad break to be removed.
*/
removeAdBreak(adBreak: AdBreak): void;
/**
* Remove all ads and ad breaks.
*
* @remarks
* - This is a shorthand for calling {@link ServerSideAdIntegrationController.removeAdBreak}
* on all ad breaks in {@link ServerSideAdIntegrationController.adBreaks}.
*/
removeAllAds(): void;
/**
* Fire an {@link AdsEventMap.aderror | `aderror`} event on the player.
*
* This does not stop playback.
*
* @param error - The error.
*/
error(error: Error): void;
/**
* Fire a fatal {@link PlayerEventMap.error | `error`} event on the player.
*
* This stops playback immediately. Use {@link ChromelessPlayer.source} to load a new source.
*
* @param error
* The error.
* @param [code]
* The error code. By default, this is set to {@link ErrorCode.AD_ERROR}.
*/
fatalError(error: Error, code?: ErrorCode): void;
}
/**
* An initializer for a custom {@link Ad}.
*
* @see {@link ServerSideAdIntegrationController.createAd}
* @see {@link ServerSideAdIntegrationController.updateAd}
*
* @category Ads
*/
interface AdInit extends Omit<Partial<Ad>, 'integration' | 'adBreak'> {
/**
* The type of the ad.
*/
type: AdType;
/**
* The time offset at which content will be paused to play the ad, in seconds.
*/
timeOffset?: number;
/**
* Additional integration-specific data associated with this ad.
*/
customData?: unknown;
}
/**
* An initializer for a custom {@link AdBreak}.
*
* @see {@link ServerSideAdIntegrationController.createAdBreak}
* @see {@link ServerSideAdIntegrationController.updateAdBreak}
*
* @category Ads
*/
interface AdBreakInit {
/**
* The time offset at which content will be paused to play the ad break, in seconds.
*/
timeOffset: number;
/**
* The duration of the ad break, in seconds.
*/
maxDuration?: number | undefined;
/**
* Additional integration-specific data associated with this ad break.
*/
customData?: unknown;
}
/**
* Factory to create an {@link ServerSideAdIntegrationHandler}.
*
* @param controller
* The controller to use.
* @return The new server-side ad integration handler.
*
* @see {@link Ads.registerServerSideIntegration}
*
* @category Ads
*/
type ServerSideAdIntegrationFactory = (controller: ServerSideAdIntegrationController) => ServerSideAdIntegrationHandler;
/**
* Fired when the {@link https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/reference/js/google.ima.AdsManager | google.ima.AdsManager} is created.
*
* @category Ads
* @category Events
* @public
*/
interface AdsManagerLoadedEvent extends Event<'adsmanagerloaded'> {
/**
* The {@link https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/reference/js/google.ima.AdsManager | google.ima.AdsManager}
*/
readonly adsManager: any;
}
/**
* Represents a VAST creative. It is either a linear or non-linear ad.
*
* @category Ads
* @public
*/
interface Ad {
/**
* The source ad server information included in the ad response.
*
* @remarks
* <br/> - Available when the {@link Ad.readyState} is `'ready'`.
*/
adSystem: string | undefined;
/**
* The integration of the ad, represented by a value from {@link AdIntegrationKind}
* or {@link CustomAdIntegrationKind | the identifier of a custom integration} added with {@link Ads.registerServerSideIntegration}.
*
* @defaultValue `'csai'`
*
* @remarks
* <br/> - The `'theo'` integration naming is deprecated and has been replaced with `'csai'`.
*/
integration?: AdIntegrationKind | CustomAdIntegrationKind;
/**
* The type of the ad.
*/
type: AdType;
/**
* The identifier of the creative.
*
* @remarks
* <br/> - Available when the {@link Ad.readyState} is `'ready'`.
*/
id: string | undefined;
/**
* The ready state of the ad.
*/
readyState?: AdReadyState;
/**
* The ad break which the ad is part of.
*
* @remarks
* <br/> - Available for VAST-ads.
*/
adBreak: AdBreak;
/**
* The duration of the ad, in seconds.
*
* @remarks
* <br/> - Available when the {@link Ad.readyState} is `'ready'`.
* <br/> - Only available for LinearAd.
*/
duration: number | undefined;
/**
* The width of the ad, in pixels.
*
* @remarks
* <br/> - Available when the {@link Ad.readyState} is `'ready'`.
*/
width: number | undefined;
/**
* The height of the ad.
*
* @remarks
* <br/> - Available when the {@link Ad.readyState} is `'ready'`.
*/
height: number | undefined;
/**
* The URI of the ad content.
*
* @remarks
* <br/> - Available when the {@link Ad.readyState} is `'ready'`.
*/
resourceURI: string | undefined;
/**
* The website of the advertisement.
*
* @remarks
* <br/> - Available when the {@link Ad.readyState} is `'ready'`.
*/
clickThrough: string | undefined;
/**
* List of companions which can be displayed outside the player.
*
* @remarks
* <br/> - Available when the {@link Ad.readyState} is `'ready'`.
* <br/> - Only supported for `'csai'` and `'google-dai'`.
*/
companions: CompanionAd[];
/**
* Offset after which the ad break may be skipped, in seconds.
*
* @remarks
* <br/> - Available when the {@link Ad.readyState} is `'ready'`.
* <br/> - If the offset is -1, the ad is unskippable.
* <br/> - If the offset is 0, the ad is immediately skippable.
* <br/> - Otherwise it must be a positive number indicating the offset.
*/
skipOffset: number | undefined;
/**
* The identifier of the selected creative for the ad.
*
* @remarks
* <br/> - Available when the {@link Ad.readyState} is `'ready'`.
*/
creativeId: string | undefined;
/**
* The list of universal ad ID information of the selected creative for the ad.
*
* @remarks
* <br/> - Only supported for `'csai'` and `'google-ima'`.
*/
universalAdIds: UniversalAdId[];
/**
* Additional integration-specific data associated with this ad.
*/
customData: unknown;
/**
* Whether the ad is a slate or not.
*
* @remarks
* </br> - Only used for THEOads ads.
*/
isSlate: boolean;
}
/**
* The type of the ad, represented by a value from the following list:
* <br/> - `'linear'`
* <br/> - `'nonlinear'`
*
* @category Ads
* @public
*/
type AdType = 'linear' | 'nonlinear';
/**
* The ad preloading strategy, represented by a value from the following list:
* <br/> - `'none'`: Ads are not preloaded.
* <br/> - `'midroll-and-postroll'`: Media files of mid- and postrolls are preloaded.
*
* @remarks
* <br/> - For Google IMA, preloading starts 8 seconds before ad playback.
*
* @category Ads
* @public
*/
type AdPreloadType = 'none' | 'midroll-and-postroll';
/**
* The ad readiness state, represented by a value from the following list:
* <br/> - `'none'`: The ad not loaded state.
* <br/> - `'ready'`: The ad loaded state.
*
* @remarks
* <br/> - An ad is loaded when the ad resource (e.g. VAST file) is downloaded.
*
* @category Ads
* @public
*/
type AdReadyState = 'none' | 'ready';
/**
* Describes the configuration of advertisement.
*
* @category Ads
* @public
*/
interface AdsConfiguration {
/**
* Allows configuring which mime types are allowed during ad playback.
*
* @remarks
* <br/> - If set to an array, all ads with another mime types will be ignored.
* <br/> - If set to `undefined`:
* - for Google IMA, the ad system will pick media based on the browser's capabilities.
* - for the other integrations, the ad system will ignore all streaming ads.
*
* @defaultValue `undefined`
*/
allowedMimeTypes?: string[];
/**
* Whether an advertisement duration countdown will be shown in the UI.
*
* @deprecated use {@link GoogleImaConfiguration.uiElements} instead
*
* @remarks
* <br/> - Available since v2.22.9.
* <br/> - This feature is only available for Google IMA.
*
* @defaultValue `true`
*/
showCountdown?: boolean;
/**
* Whether media files of mid- and postrolls are preloaded.
*
* @remarks
* <br/> - This feature is only available for Google IMA.
*
* @defaultValue `'midroll-and-postroll'`
*/
preload?: AdPreloadType;
/**
* The iframe policy for VPAID ads.
*
* @remarks
* <br/> - This feature is only available for Google IMA and SpotX.
*
* @defaultValue `'enabled'`
*/
vpaidMode?: VPAIDMode;
/**
* The Google IMA configuration.
*/
googleIma?: GoogleImaConfiguration;
/**
* Whether to enable THEOads support.
*
* @remarks
* <br/> - Available since 8.2.0.
* <br/> - This must be set to `true` in order to schedule a {@link TheoAdDescription}.
*
* @defaultValue `false`
*/
theoads?: boolean;
/**
* Flag to allow seeking out of ads with `skipAdBreak` when using the `csai` integration.
*
* @remarks
* <br/> - Available since 9.4.0.
*/
allowSkipAdBreak?: boolean;
}
/**
* Describes the configuration of Google IMA.
*
* @category Ads
* @public
*/
interface GoogleImaConfiguration {
/**
* Whether the native (mobile) IMA implementation will be used.
*
* @internal
*/
useNativeIma: boolean;
/**
* Whether to use an ad UI element for clickthrough and displaying other ad UI.
*
* @remarks
* <br/> - Available since v8.6.0.
* <br/> - If set to `true`, Google DAI can show additional ad UI elements
* on top of the player for certain ads, such as a skip button for skippable ads
* or a specific UI for GDPR compliance.
* <br/> - If set to `false`, Google DAI ads will only show a basic "Learn More" button.
* Ads that need additional UI elements will not be played.
* <br/> - This only applies to Google DAI server-side inserted ads.
* Client-side ads from Google IMA can always show additional UI elements.
* <br/> - This flag is enabled by default since v10.0.0.
*
* @defaultValue `true` (was `false` in version 9 and lower)
*/
useAdUiElementForSsai?: boolean;
/**
* The maximum recommended bitrate in kbit/s. Ads with a bitrate below the specified maximum will be picked.
*
* @remarks
* <br/> - When set to -1, it will select the ad with the highest bitrate.
* <br/> - If there is no ad below the specified maximum, the ad closest to the bitrate will be picked.
*
* @defaultValue -1
*/
bitrate?: number;
/**
* The language code of the UI elements. See {@link https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/localization | localization docs} for more information.
*
* @remarks
* <br/> - This will default to {@link UIConfiguration.language} when not specified.
*
*/
language?: string;
/**
* The UI elements passed to Google IMA. See {@link https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/reference/js/google.ima#.UiElements | Google IMA docs} for more information.
*
* @remarks
* <br/> - Available since v6.13.0.
*/
uiElements?: string[];
/**
* A flag to enable seeking during an ad break in a DAI stream.
*
* @remarks
* <br/> - Available since v9.2.0
*
* @defaultValue false
*/
allowSeekingForGoogleDai?: boolean;
}
/**
* Represents a non-linear ad in the VAST specification.
*
* @category Ads
* @public
*/
interface NonLinearAd extends Ad {
/**
* The alternative description for the ad.
*
* @remarks
* <br/> - Available when the {@link Ad.readyState} is `'ready'`.
*/
altText: string | undefined;
/**
* The website of the ad.
*
* @remarks
* <br/> - Available when the {@link Ad.readyState} is `'ready'`.
*/
clickThrough: string | undefined;
/**
* The HTML-string with the content of the ad.
*
* @remarks
* <br/> - Available when the {@link Ad.readyState} is `'ready'`.
*/
contentHTML: string | undefined;
}
/**
* The delivery type of the ad content file, represented by a value from the following list:
* <br/> - `'progressive'`: Delivered through progressive download protocols (e.g. HTTP).
* <br/> - `'streaming'`: Delivered through streaming download protocols.
*
* @category Ads
* @public
*/
type DeliveryType = 'progressive' | 'streaming';
/**
* Represents metadata of a media file with ad content.
*
* @remarks
* <br/> - This metadata is retrieved from the VAST file.
*
* @category Ads
* @public
*/
interface MediaFile {
/**
* The delivery type of the video file.
*/
delivery: DeliveryType;
/**
* The MIME type for the file container.
*/
type: string;
/**
* The native width of the video file, in pixels.
*/
width: number;
/**
* The native height of the video file, in pixels.
*/
height: number;
/**
* The URI of the VAST content.
*/
contentURL: string;
}
/**
* Represents metadata of a closed caption for a media file with ad content.
*
* @remarks
* <br/> - This metadata is retrieved from the VAST file.
*
* @category Ads
* @public
*/
interface ClosedCaptionFile {
/**
* The MIME type for the file.
*/
type: string;
/**
* The language of the Closed Caption file using ISO 631-1 codes. An optional locale
* suffix can also be provided.
*
* @example
* "en", "en-US", "zh-TW"
*/
language: string;
/**
* The URI of the file providing Closed Caption info for the media file.
*/
contentURL: string;
}
/**
* Represents the contents of an Extension tag found under an Inline or Wrapper's Extensions tag (if present).
*
* @remarks
* <br/> - Available since 9.4.0.
* <br/> - Only parsed for the `csai` integration.
*
* @category Ads
* @public
*/
interface VastExtension {
/**
* A type to identify the Extension.
*/
type: string;
/**
* String representation of the custom xml wrapped inside the Extension tag as found in the VAST.
*
*/
xml: string;
}
/**
* Represents a linear ad in the VAST specification.
*
* @category Ads
* @public
*/
interface LinearAd extends Ad {
/**
* The duration of the ad, in seconds.
*
* @remarks
* <br/> - Available when the {@link Ad.readyState} is `'ready'`.
*/
duration: number;
/**
* List of media files which contain metadata about ad video files.
*/
mediaFiles: MediaFile[];
/**
* The URL of the media file loaded for ad playback. Returns undefined if no URL is available yet.
*
* @remarks
* <br/> - Available when the ad break has started.
*/
mediaUrl?: string;
/**
* List of closed caption files which contain metadata about the closed captions that accompany any media files.
*/
closedCaptionFiles: ClosedCaptionFile[];
/**
* List of Extensions found in the related Inline or Wrapper tag
*
* @remarks
* <br/> - Available since 9.4.0.
*/
extensions: VastExtension[];
}
/**
* Represents a Google IMA creative compliant to the VAST specification.
*
* @remarks
* <br/> - Available since v2.60.0.
*
* @category Ads
* @public
*/
interface GoogleImaAd extends Ad {
/**
* The bitrate of the currently playing creative as listed in the VAST response or 0.
*/
readonly bitrate: number;
/**
* Record of custom parameters for the ad at the time of ad trafficking.
* Each entry contains a parameter name with associated value.
*
* @remarks
* <br/> - Available when the {@link Ad.readyState} is `'ready'`.
*/
traffickingParameters: {
[parameterKey: string]: string;
} | undefined;
/**
* Return title of the advertisement.
*
* @remarks
* <br/> - Available when the {@link Ad.readyState} is `'ready'`.
*/
title: string | undefined;
/**
* The custom parameters for the ad at the time of ad trafficking, as a string.
*
* @remarks
* <br/> - A parsed version is available as {@link GoogleImaAd.traffickingParameters}.
* <br/> - Available when the {@link Ad.readyState} is `'ready'`.
*/
traffickingParametersString: string | undefined;
/**
* List of wrapper ad identifiers as specified in the VAST response.
*/
wrapperAdIds: string[];
/**
* List of wrapper ad systems as specified in the VAST response.
*/
wrapperAdSystems: string[];
/**
* List of wrapper creative identifiers.
*
* @remarks
* <br/> - Starts with the first wrapper ad.
*/
wrapperCreativeIds: string[];
/**
* The url of the chosen media file.
*
* @remarks
* <br/> - Available when the {@link Ad.readyState} is `'ready'`.
*/
mediaUrl: string | undefined;
/**
* The content type of the ad.
*
* @remarks
* <br/> - Available when the {@link Ad.readyState} is `'ready'`.
* <br/> - For linear ads, the content type is only going to be available after the `'adbegin'` event, when the media file is selected.
*/
contentType: string | undefined;
/**
* The identifier of the API framework needed to execute the ad.
*
* @remarks
* <br/> - Available when the {@link Ad.readyState} is `'ready'`.
* <br/> - This corresponds with the apiFramework specified in vast.
*/
apiFramework: string | undefined;
/**
* The description of the ad from the VAST response.
*
* @remarks
* <br/> - Available since 8.6.0.
* <br/> - Available for `google-ima` and `google-dai` integrations only.
*/
description: string | undefined;
}
/**
* Represents the information regarding the universal identifier of an ad.
*
* @category Ads
* @public
*/
interface UniversalAdId {
/**
* The registry associated with cataloging the UniversalAdId of the selected creative for the ad.
*
* @remarks
* <br/> - Returns the registry value, or "unknown" if unavailable.
*/
adIdRegistry: string;
/**
* The UniversalAdId of the selected creative for the ad.
*
* @remarks
* <br/> - Returns the id value or "unknown" if unavailable.
*/
adIdValue: string;
}
/**
* Represents an ad break in the VMAP specification or an ad pod in the VAST specification.
*
* @category Ads
* @public
*/
interface AdBreak {
/**
* The integration of the ad break, represented by a value from {@link AdIntegrationKind}
* or {@link CustomAdIntegrationKind | the identifier of a custom integration} registered with {@link Ads.registerServerSideIntegration}.
*
* @remarks
* <br/> - The `'theo'` integration naming is deprecated and has been replaced with `'csai'`.
*/
integration: AdIntegrationKind | CustomAdIntegrationKind | undefined;
/**
* List of ads which will be played sequentially at the ad break's time offset.
*/
ads: Ad[] | undefined;
/**
* The time offset at which content will be paused to play the ad break, in seconds.
*/
timeOffset: number;
/**
* The duration of the ad break, in seconds.
*
* @remarks
* <br/> - Ads are lazily loaded. This property becomes available when all ads are loaded.
*/
maxDuration: number | undefined;
/**
* The remaining duration of the ad break, in seconds.
*
* @remarks
* <br/> - Ads are lazily loaded. This property becomes available when all ads are loaded.
* <br/> - This feature is not available in the Google IMA integration and will default to -1.
*/
maxRemainingDuration: number | undefined;
/**
* Additional integration-specific data associated with this ad.
*/
customData: unknown;
}
/**
* Represents a companion ad which is displayed near the video player.
*
* @category Ads
* @public
*/
interface CompanionAd {
/**
* The identifier of the element in which the companion ad should be appended, if available.
*
* @remarks
* <br/> Only available for Google DAI and THEO ads if provided in the VAST.
*/
adSlotId?: string;
/**
* The alternative description for the ad.
*
* @remarks
* <br/> - Returns value as reported in the VAST StaticResource. If not specified, it returns an empty string.
* <br/> - Returns an empty string for THEO ads if not available.
* <br/> - Returns an empty string for Google IMA / Google DAI integrations.
*/
altText: string;
/**
* The content of the ad, as HTML.
*
* @remarks
* <br/> - Available for StaticResource and HTMLResource in THEO ad system.
* <br/> - Available in the DAI ad system.
*/
contentHTML: string;
/**
* The website of the advertisement.
*
* @remarks
* <br/> - Only available for StaticResource if specified by the VAST. Otherwise returns an empty string.
*/
clickThrough?: string;
/**
* The height of the ad, in pixels.
*
* @remarks
* <br/> - Only available for IMA ad system and THEO ad system.
*/
height: number;
/**
* The URI of the ad content as specified in the VAST file.
*
* @remarks
* <br/> - Only available in the THEO ad system for StaticResource. Otherwise returns an empty string.
*/
resourceURI: string;
/**
* The width of the ad, in pixels.
*
* @remarks
* <br/> - Only available for IMA ad system and THEO ad system.
*/
width: number;
}
/**
* The events fired by the {@link Ads | ads API}.
*
* @category Ads
* @public
*/
interface AdsEventMap {
/**
* Fired when an ad break is added.
*
* @remarks
* <br/> - Available since v2.60.0.
*/
addadbreak: AdBreakEvent<'addadbreak'>;
/**
* Fired when an ad break is removed.
*
* @remarks
* <br/> - Available since v2.60.0.
*/
removeadbreak: AdBreakEvent<'removeadbreak'>;
/**
* Fired when an ad break begins.
*/
adbreakbegin: AdBreakEvent<'adbreakbegin'>;
/**
* Fired when an ad break ends.
*/
adbreakend: AdBreakEvent<'adbreakend'>;
/**
* Fired when an ad break changes.
*/
adbreakchange: AdBreakEvent<'adbreakchange'>;
/**
* Fired when an ad is added.
*
* @remarks
* <br/> - Available since v2.60.0.
*/
addad: AdEvent<'addad'>;
/** @internal */
adadded: Event<'adadded'>;
/**
* Fired when an ad is updated.
*
* @remarks
* <br/> - Available since v2.60.0.
*/
updatead: AdEvent<'updatead'>;
/**
* Fired when an AdBreak is updated.
*
* @remarks
* <br/> - Available since v2.66.0.
*/
updateadbreak: AdBreakEvent<'updateadbreak'>;
/**
* Fired when an ad is loaded.
*/
adloaded: Event<'adloaded'>;
/**
* Fired when an ad begins.
*/
adbegin: AdEvent<'adbegin'>;
/**
* Fired when an ad ends.
*/
adend: AdEvent<'adend'>;
/**
* Fired when an ad is skipped.
*/
adskip: AdSkipEvent;
/**
* Fired when an ad errors.
*/
aderror: Event<'aderror'>;
/**
* Fired when an ad counts as an impression.
*/
adimpression: AdEvent<'adimpression'>;
/**
* Fired when an ad reaches the first quartile.
*/
adfirstquartile: AdEvent<'adfirstquartile'>;
/**
* Fired when an ad reaches the mid point.
*/
admidpoint: AdEvent<'admidpoint'>;
/**
* Fired when an ad reaches the third quartile.
*/
adthirdquartile: AdEvent<'adthirdquartile'>;
/**
* Fired when the ad has stalled playback to buffer.
*
* @remarks
* <br/> - only available in the Google IMA integration.
*/
adbuffering: AdBufferingEvent;
/**
* Fired when an ads list is loaded.
*
* @remarks
* <br/> - only available in the Google IMA integration.
*/
admetadata: AdMetadataEvent;
/**
* Fired when the {@link https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/reference/js/google.ima.AdsManager | google.ima.AdsManager} is created.
*
* @remarks
* <br/> - only available in the Google IMA integration.
*/
adsmanagerloaded: AdsManagerLoadedEvent;
}
/**
* Base type for events related to a single ad.
*
* @category Ads
* @category Events
* @public
*/
interface AdEvent<TType extends string> extends Event<TType> {
/**
* The ad.
*/
readonly ad: Ad;
}
/**
* Fired when an ad is skipped.
*
* @category Ads
* @category Events
* @public
*/
interface AdSkipEvent extends AdEvent<'adskip'> {
/**
* The amount of time that was played before the ad was skipped, as a fraction between 0 and 1.
*/
readonly playedPercentage: number;
}
/**
* Base type for events related to an ad break.
*
* @category Ads
* @category Events
* @public
*/
interface AdBreakEvent<TType extends string> extends Event<TType> {
/**
* The ad break.
*/
readonly adBreak: AdBreak;
}
/**
* The API for advertisements.
*
* @remarks
* <br/> - Integrates with `'csai'`, `'google-ima'`, `'google-dai'`, `'freewheel'` or `'theoads'`.
*
* @category Ads
* @public
*/
interface Ads extends EventDispatcher<AdsEventMap> {
/**
* Whether a linear ad is currently playing.
*/
playing: boolean;
/**
* The currently playing ad break.
*/
readonly currentAdBreak: AdBreak | null;
/**
* List of currently playing ads.
*/
readonly currentAds: Ad[];
/**
* List of ad breaks which still need to be played.
*/
readonly scheduledAdBreaks: AdBreak[];
/**
* List of ads which still need to be played.
*/
readonly scheduledAds: Ad[];
/**
* The Google DAI API.
*
* @remarks
* <br/> - Only available with the feature `'google-dai'`.
*/
readonly dai?: GoogleDAI;
/**
* Add an ad break request.
*
* @remarks
* <br/> - Available since v2.18.0.
* <br/> - Prefer scheduling ad breaks up front through {@link SourceConfiguration.ads}.
*
* @param adDescription - Describes the ad break to be scheduled.
*/
schedule(adDescription: AdDescription): void;
/**
* Skip the current linear ad.
*
* @remarks
* <br/> - This will have no effect when the current linear ad is (not yet) skippable.
*/
skip(): void;
/**
* Seek to a point in the main content timeline.
*
* @remarks
* <br/> - Available since v9.4.0.
* <br/> - Only supported for the `csai` integration.
* <br/> - This will have no effect when `allowSkipAdBreak` is not set to `true` in the `AdsConfiguration`.
*/
skipAdBreak(target?: number): void;
/**
* Register a custom advertisement integration.
*
* This allows you to integrate with third-party advertisement providers,
* and have them report their ads and ad-related events through the THEOplayer {@link Ads} API.
*
* @param integrationId
* An identifier of the integration.
* @param integrationFactory
* Factory that will construct an {@link ServerSideAdIntegrationHandler} for this integration.
*/
registerServerSideIntegration(integrationId: CustomAdIntegrationKind, integrationFactory: ServerSideAdIntegrationFactory): void;
}
/**
* The type of ad source:
* <br/> - `'vast'`: The source is a VAST resource.
* <br/> - `'vmap'`: The source is a VMAP resource.
* <br/> - `'adrule'`: The source is a Ad Rule resource.
*
* @remarks
* <br/> - An ad rule is a simplified VMAP alternative only available in the Google IMA integration.
*
* @category Ads
* @public
*/
type AdSourceType = 'vast' | 'vmap' | 'adrule';
/**
* Describes the source of the ad.
*
* @category Ads
* @public
*/
interface AdSource {
/**
* The URL of the ad resource.
*/
src: string;
/**
* The type of ad resource.
*
* @defaultValue 'vmap' when set through {@link SourceConfiguration.ads} without a time offset, otherwise 'vast'.
*/
type?: AdSourceType;
}
/**
* Describes an ad break request.
*
* @category Ads
* @public
*/
interface AdDescription {
/**
* The integration of the ad, represented by a value from {@link AdIntegrationKind}
* or {@link CustomAdIntegrationKind | the identifier of a custom integration} registered with {@link Ads.registerServerSideIntegration}.
*
* @defaultValue `'csai'`
*/
integration?: AdIntegrationKind | CustomAdIntegrationKind;
/**
* Whether the ad replaces playback of the content.
*
* @remarks
* <br/> - When the ad ends, the content will resume at the ad break's offset plus its duration.
*
* @defaultValue
* <br/> - `true` for live content,
* <br/> - `false` for VOD content.
*/
replaceContent?: boolean;
/**
* A source which contains the location of ad resources to be scheduled.
*
* @remarks
* <br/> - Important: This should *not* be an array of sources.
* <br/> - VPAID support is limited to the `'google-ima'` integration.
* <br/> - Not specifying this property should only happen when using a third party ad integration that uses an other system of specifying which ads to schedule
*/
sources?: string | AdSource;
/**
* Offset after which the ad break will start.
*
* Possible formats:
* <br/> - A number for the offset in seconds.
* <br/> - `'start'` for a preroll.
* <br/> - `'end'` for a postroll.
* <br/> - `'HH:MM:SS.mmm'` for a timestamp in the playback window.
* <br/> - A percentage string (XX%) for a proportion of the content duration.
*
* @remarks
* <br/> - A timestamp which is not in the playback window will result in the ad break not being started.
* <br/> - Do NOT set for VMAP ads. VMAP resources will ignore this value as they contain an internal offset. https://www.theoplayer.com/docs/theoplayer/how-to-guides/ads/how-to-set-up-vast-and-vmap/#vmap
* <br/> - Since 2.18, numbers are supported for the Google IMA integration, since 2.21 other formats as well.
*
* @defaultValue `'start'`
*
*/
timeOffset?: string | number;
}
/**
* Describes a SpotX ad break request.
*
* @remarks
* <br/> - Available since v2.13.0.
*
* @example
* ```
* {
* integration: 'spotx',
* id: 123456,
* cacheBuster: true,
* app: {
* bundle: 'com.exampleapps.example',
* name: 'My CTV App'
* },
* device: {
* ifa: '38400000-8cf0-11bd-b23e-10b96e40000d',
* ua: 'Mozilla/5.0 (iPhone; CPU iPhone OS 10_3 like Mac OS X) AppleWebKit/602.1.50 (KHTML, like Gecko) CriOS/56.0.2924.75 Mobile/14E5239e Safari/602.1',
* geo: {
* lat: -24.378528,
* lon: -128.325