@glomex/vast-ima-player/dist/vast-ima-player.d.ts

Convenience wrapper for advertising video/audio content with Google IMA

/**
 * tslint:disable:max-classes-per-file
 *
 * @format
 */
import type { ImaSdk, google } from '@alugha/ima';
import { DelegatedEventTarget } from './delegated-event-target';
/**
 * Additional media events that help managing the
 * lifecycle of a media file playback.
 */
declare enum AdditionalMediaEvent {
    /** Fired when initial media file play happened. */
    MEDIA_START = "MediaStart",
    /** Fired when the first frame of the media file is played after linear preroll. */
    MEDIA_IMPRESSION = "MediaImpression",
    /** Fired when the media file playback finished after potential postroll. */
    MEDIA_STOP = "MediaStop",
    /** Fired when ad break cue points change. */
    MEDIA_CUE_POINTS_CHANGE = "MediaCuePointsChange",
    /**
     * Fired when media resumes playback. CONTENT_RESUME_REQUESTED
     * is sometimes triggered before playback and this event is only
     * triggered after ad is finished or when content resumes.
     */
    MEDIA_RESUMED = "MediaResumed"
}
/**
 * Adjusted enum of https://developers.google.com/interactive-media-ads/docs/sdks/html5/v3/reference/js/google.ima.AdEvent
 * to follow VPAID spec event names.
 */
declare enum ImaToAdEventMap {
    /**
     * Fired when an ad error occurred (standalone ad or ad within an ad rule).
     * IMA provides these events on different objects and this event normalizes it.
     */
    AD_ERROR = "AdError",
    /** Fired when the ad has stalled playback to buffer. */
    AD_BUFFERING = "AdBuffering",
    /** Fired when ad data is available. */
    LOADED = "AdLoaded",
    /** Fired when the impression URL has been pinged. */
    IMPRESSION = "AdImpression",
    /** Fired when the ad starts playing. */
    STARTED = "AdStarted",
    /** Fired when the ad playhead crosses first quartile. */
    FIRST_QUARTILE = "AdFirstQuartile",
    /** Fired when the ad playhead crosses midpoint. */
    MIDPOINT = "AdMidpoint",
    /** Fired when the ad playhead crosses third quartile. */
    THIRD_QUARTILE = "AdThirdQuartile",
    /** Fired when the ad's current time value changes. */
    AD_PROGRESS = "AdProgress",
    /** Fired when the ad completes playing. */
    COMPLETE = "AdComplete",
    /** Fired when the ad is clicked. */
    CLICK = "AdClick",
    /** Fired when the ad is paused. */
    PAUSED = "AdPaused",
    /** Fired when the ad is resumed. */
    RESUMED = "AdResumed",
    /** Fired when the ad is skipped by the user. */
    SKIPPED = "AdSkipped",
    /** Fired when the displayed ads skippable state is changed. */
    SKIPPABLE_STATE_CHANGED = "AdSkippableStateChanged",
    /** Fired when the ad volume has changed. */
    VOLUME_CHANGED = "AdVolumeChanged",
    /** Fired when the ad volume has been muted. */
    VOLUME_MUTED = "AdMuted",
    /** Fired when an ads list is loaded. This is when ad rule cuePoints are available. */
    AD_METADATA = "AdMetadata",
    /** Fired when an ad rule or a VMAP ad break would have played if autoPlayAdBreaks is false. */
    AD_BREAK_READY = "AdBreakReady",
    /** Fired when content should be paused. This usually happens right before an ad is about to cover the content. */
    CONTENT_PAUSE_REQUESTED = "AdContentPauseRequested",
    /** Fired when content should be resumed. This usually happens when an ad finishes or collapses. */
    CONTENT_RESUME_REQUESTED = "AdContentResumeRequested",
    /** Fired when the ads manager is done playing all the ads. */
    ALL_ADS_COMPLETED = "AdAllAdsCompleted",
    /** Fired when the ad's duration changes. */
    DURATION_CHANGE = "AdDurationChange",
    /** Fired when an ad triggers the interaction callback. Ad interactions contain an interaction ID string in the ad data. */
    INTERACTION = "AdInteraction",
    /** Fired when the displayed ad changes from linear to nonlinear, or vice versa. */
    LINEAR_CHANGED = "AdLinearChanged",
    /** Fired when a non-fatal error is encountered. The user need not take any action since the SDK will continue with the same or next ad playback depending on the error situation. */
    LOG = "AdLog",
    /** Fired when the ad is closed by the user. */
    USER_CLOSE = "AdUserClose",
    /** Not document by IMA */
    AD_CAN_PLAY = "AdCanPlay",
    /** Not document by IMA */
    EXPANDED_CHANGED = "AdExpandedChanged",
    /** Not document by IMA */
    VIEWABLE_IMPRESSION = "AdViewableImpression"
}
/**
 * Available events of the VAST-IMA-Player.
 *
 * Also see https://developers.google.com/interactive-media-ads/docs/sdks/html5/v3/reference/js/google.ima.AdEvent
 *
 * The player also triggers the normal media element events
 * (https://developer.mozilla.org/en-US/docs/Web/Guide/Events/Media_events)
 * when the content playback happens. This is useful when
 * "disableCustomPlaybackForIOS10Plus = false" (default) is configured and
 * the same media element is used on iOS to render both ad and content.
 * Those event names are not enumerated here because they are known.
 */
export declare const PlayerEvent: {
    MEDIA_START: AdditionalMediaEvent.MEDIA_START;
    MEDIA_IMPRESSION: AdditionalMediaEvent.MEDIA_IMPRESSION;
    MEDIA_STOP: AdditionalMediaEvent.MEDIA_STOP;
    MEDIA_CUE_POINTS_CHANGE: AdditionalMediaEvent.MEDIA_CUE_POINTS_CHANGE;
    MEDIA_RESUMED: AdditionalMediaEvent.MEDIA_RESUMED;
    AD_ERROR: ImaToAdEventMap.AD_ERROR;
    AD_BUFFERING: ImaToAdEventMap.AD_BUFFERING;
    LOADED: ImaToAdEventMap.LOADED;
    IMPRESSION: ImaToAdEventMap.IMPRESSION;
    STARTED: ImaToAdEventMap.STARTED;
    FIRST_QUARTILE: ImaToAdEventMap.FIRST_QUARTILE;
    MIDPOINT: ImaToAdEventMap.MIDPOINT;
    THIRD_QUARTILE: ImaToAdEventMap.THIRD_QUARTILE;
    AD_PROGRESS: ImaToAdEventMap.AD_PROGRESS;
    COMPLETE: ImaToAdEventMap.COMPLETE;
    CLICK: ImaToAdEventMap.CLICK;
    PAUSED: ImaToAdEventMap.PAUSED;
    RESUMED: ImaToAdEventMap.RESUMED;
    SKIPPED: ImaToAdEventMap.SKIPPED;
    SKIPPABLE_STATE_CHANGED: ImaToAdEventMap.SKIPPABLE_STATE_CHANGED;
    VOLUME_CHANGED: ImaToAdEventMap.VOLUME_CHANGED;
    VOLUME_MUTED: ImaToAdEventMap.VOLUME_MUTED;
    AD_METADATA: ImaToAdEventMap.AD_METADATA;
    AD_BREAK_READY: ImaToAdEventMap.AD_BREAK_READY;
    CONTENT_PAUSE_REQUESTED: ImaToAdEventMap.CONTENT_PAUSE_REQUESTED;
    CONTENT_RESUME_REQUESTED: ImaToAdEventMap.CONTENT_RESUME_REQUESTED;
    ALL_ADS_COMPLETED: ImaToAdEventMap.ALL_ADS_COMPLETED;
    DURATION_CHANGE: ImaToAdEventMap.DURATION_CHANGE;
    INTERACTION: ImaToAdEventMap.INTERACTION;
    LINEAR_CHANGED: ImaToAdEventMap.LINEAR_CHANGED;
    LOG: ImaToAdEventMap.LOG;
    USER_CLOSE: ImaToAdEventMap.USER_CLOSE;
    AD_CAN_PLAY: ImaToAdEventMap.AD_CAN_PLAY;
    EXPANDED_CHANGED: ImaToAdEventMap.EXPANDED_CHANGED;
    VIEWABLE_IMPRESSION: ImaToAdEventMap.VIEWABLE_IMPRESSION;
};
export declare class PlayerOptions {
    /** Sets whether to disable custom playback on iOS 10+ browsers. If true, ads will play inline if the content video is inline. This enables TrueView skippable ads. However, the ad will stay inline and not support iOS's native fullscreen. */
    disableCustomPlaybackForIOS10Plus: boolean;
    /** Enables or disables auto resizing of adsManager. If enabled it also resizes non-linear ads. */
    autoResize: boolean;
    /** Allows to have a separate 'Learn More' click tracking element on mobile. */
    clickTrackingElement?: HTMLElement;
}
export declare class PlayerError extends Error {
    errorCode: number;
    innerError: Error;
    type: string;
    vastErrorCode: number;
    static ERROR_CODE_ADS_MANAGER_LOADED_TIMEOUT: number;
    static ERROR_CODE_REQUEST_ADS_TIMEOUT: number;
    constructor(...args: any[]);
}
declare type StartAd = {
    start: () => void;
    startWithoutReset: () => void;
    ad?: google.ima.Ad;
    adBreakTime?: number;
};
declare type StartAdCallback = (startAd: StartAd) => void;
/**
 * Convenience player wrapper for the Google IMA HTML5 SDK
 */
export declare class Player extends DelegatedEventTarget {
    #private;
    constructor(ima: ImaSdk, mediaElement: HTMLVideoElement, adElement: HTMLElement, adsRenderingSettings?: google.ima.AdsRenderingSettings, options?: PlayerOptions);
    /**
     * This allows synchronous activation of the media element
     * and the Google IMA ad-display-container. Useful when you
     * have to do async work before calling "playAds".
     */
    activate(): void;
    /**
     * This is the entry point to start ad playback. It can be used
     * as such:
     *
     * - With a single VAST at the beginning to play a preroll
     * - Anyhwere during content playback with a single VAST
     * - With a single VMAP at the beginning
     */
    playAds(adsRequest: google.ima.AdsRequest): void;
    /**
     * Similar to "playAds" method but with the difference
     * that it allows to first load the ad and start it separately
     * within the given callback.
     *
     * When a VAST or a VMAP ad break is given the callback is called
     * with a "start" method which either starts playing the individual
     * VAST ad or starts the VMAP ad break. If "start" method is not called
     * it won't play the ad.
     */
    loadAds(adsRequest: google.ima.AdsRequest, startAdCallback: StartAdCallback): void;
    private _mediaElementPlay;
    private _requestAds;
    private _setupIma;
    skipAd(): void;
    discardAdBreak(): void;
    /**
     * Starts playback of either content or ad element.
     */
    play(): void;
    /**
     * Pauses playback of either content or ad element.
     */
    pause(): void;
    /**
     * Sets volume of either content or ad element.
     */
    set volume(volume: number);
    /**
     * Returns volume of either content or ad element.
     */
    get volume(): number;
    /**
     * Sets muted state on either content or ad element.
     */
    set muted(muted: boolean);
    /**
     * Returns muted state of either content or ad element.
     */
    get muted(): boolean;
    /**
     * Sets current time of content element when not in ad playback mode.
     */
    set currentTime(currentTime: number);
    /**
     * Returns current playhead time of either content or ad element.
     */
    get currentTime(): number;
    /**
     * Returns current duration of either content or ad element.
     */
    get duration(): number;
    /**
     * Returns list of ad break cue points that weren't played yet.
     * Only available after "AdMetadata" event when VMAP is passed in playAds.
     */
    get cuePoints(): number[];
    private _setCuePoints;
    /**
     * Remove already played cuepoints
     *
     * @param timeOffset offset in seconds as defined in VMAP or 0 for preroll and -1 for postroll
     */
    private _adjustCuePoints;
    /**
     * Allows resizing the ad element. Useful when options.autoResize = false.
     */
    resizeAd(width: number, height: number): void;
    /**
     * Cleans up current ad and ad manager session or the complete IMA (via force).
     *
     * Externally call this function with "force = true" when you want to switch
     * the content source or move the player to another DOM node before doing
     * another "playAds" or "loadAds", so that it does a full cleanup.
     *
     * @param force - enforce a full cleanup
     * @returns a promise which resolves after all the cleanup work is done
     */
    reset(force?: boolean): void;
    private _resetIma;
    /**
     * Completely destroys this instance. It is unusable after that.
     */
    destroy(): void;
    isCustomPlaybackUsed(): boolean;
    private _resetAd;
    private _handleMediaElementEvents;
    private _handleAdsManagerEvents;
    private _onAdsLoaderError;
    private _onAdsManagerLoaded;
    private _startAdsManager;
    private _mediaStop;
    private _resizeObserverCallback;
    private _resizeAdsManager;
    private _getViewMode;
    private _playContent;
    private _createPlayerErrorFromImaErrorEvent;
    private _onAdError;
}
export {};