THEOplayer Web SDK
    Preparing search index...

    Interface ClientSideAdIntegrationControllerExperimental

    The controller for a custom client-side ad integration.

    Besides the common CustomAdIntegrationController operations, it allows the integration to pause the content and play linear ads, either on its own or through the built-in player.

    ClientSideAdIntegrationHandler

    interface ClientSideAdIntegrationController {
        adBreaks: readonly AdBreak[];
        adContainer: HTMLElement;
        ads: readonly Ad[];
        content: ContentPlayer;
        contentElement: HTMLElement;
        contentVideoElement: HTMLVideoElement | undefined;
        integration: CustomAdIntegrationKind;
        linearAdPlayer: LinearAdPlayer;
        beginAd(ad: Ad): void;
        createAd(init: AdInit, adBreak?: AdBreak): Ad;
        createAdBreak(init: AdBreakInit): AdBreak;
        endAd(ad: Ad): void;
        endAdBreak(adBreak: AdBreak): void;
        endLinearAdBreak(options?: EndLinearAdBreakOptions): void;
        error(error: Error): void;
        fatalError(error: Error, code?: ErrorCode): void;
        removeAd(ad: Ad): void;
        removeAdBreak(adBreak: AdBreak): void;
        removeAllAds(): void;
        skipAd(ad: Ad): void;
        startLinearAdBreak(options?: StartLinearAdBreakOptions): void;
        updateAd(ad: Ad, init: Partial<AdInit>): void;
        updateAdBreak(adBreak: AdBreak, init: Partial<AdBreakInit>): void;
        updateAdProgress(ad: Ad, progress: number): void;
        updateLinearAdBreak(): void;
    }

    Hierarchy (View Summary)

    Index
    adBreaks adContainer ads content contentElement contentVideoElement integration linearAdPlayer
    beginAd createAd createAdBreak endAd endAdBreak endLinearAdBreak error fatalError removeAd removeAdBreak removeAllAds skipAd startLinearAdBreak updateAd updateAdBreak updateAdProgress updateLinearAdBreak
    adBreaks: readonly AdBreak[]

    The scheduled ad breaks managed by this integration.

    Use createAdBreak and removeAdBreak to add or remove ad breaks.

    adContainer: HTMLElement

    A DOM element for rendering ads, owned by this integration.

    The element is absolutely positioned over the player's video area (position: absolute; inset: 0), on top of the content video. It is initially empty and does not receive pointer events. The integration may add child elements to render non-linear ads, or to play linear ads with its own ad player (see LinearAdPlayback). It may style this element during a linear ad break; the player resets its styles when the break ends or when a new source is set during an active break.

    ads: readonly Ad[]

    The scheduled ads managed by this integration.

    Use createAd and removeAd to add or remove ads.

    Readonly Experimentalcontent

    content: ContentPlayer

    The content playback state and controls, independent of the active ad player.

    contentElement: HTMLElement

    The DOM element in which the content is rendered, owned by the player.

    The element is positioned in the normal flow of the player's DOM (position: relative), so it dictates the size of the player's video area. It always contains contentVideoElement, if that is defined. During a linear ad break, the integration may style this element to create custom ad layouts, for example to scale the content down into a corner while an ad is shown in adContainer. The player resets its styles when the break ends.

    contentVideoElement: HTMLVideoElement | undefined

    The video element in which the content is played.

    On some platforms, a linear ad must be played in the same video element as the content, for example to keep native fullscreen playback on iOS. In that case, play the linear ad in this element (for example by passing it to a third-party ad SDK), and set LinearAdPlayback.usesContentVideoElement when starting linear ad playback.

    • This is undefined when the player can't let ad integrations reuse the content's video element for linear ad playback, for example when the content is rendered into multiple media elements or outside of the DOM. Play linear ads in adContainer instead.
    • When defined, this is a descendant of contentElement.
    • The integration may only change the element's source or playback state during linear ad playback, after startLinearAdBreak was called with LinearAdPlayback.usesContentVideoElement set.
    • The element may change when a new source is set. Read it when starting each linear ad break rather than caching it.
    integration: CustomAdIntegrationKind

    The identifier for this integration, as it was passed to Ads.registerServerSideIntegration or Ads.registerClientSideIntegration.

    linearAdPlayer: LinearAdPlayer

    The built-in linear ad player shared by all client-side ad integrations for this player.

    Settings
    Member Visibility

    On This Page
    Properties
    Methods