@dailymotion/ad-sdk-web/dist/index.d.ts

JavaScript Ad SDK API by Dailymotion

type StandardCallback = () => void;
type ErrorCallback = (code?: number, message?: string) => void;

declare enum AdEvents {
    AD_BREAK_START = "AD_BREAK_START",
    AD_BREAK_END = "AD_BREAK_END",
    AD_LOAD = "AD_LOAD",
    AD_START = "AD_START",
    AD_PLAY = "AD_PLAY",
    AD_PAUSE = "AD_PAUSE",
    AD_END = "AD_END",
    AD_ERROR = "AD_ERROR",
    CONTENT_PAUSE_REQUESTED = "CONTENT_PAUSE_REQUESTED",
    CONTENT_RESUME_REQUESTED = "CONTENT_RESUME_REQUESTED"
}

interface MediaFile {
    fileURL: string;
    type?: string;
    width?: number;
    height?: number;
    bitrate?: number;
    mimeType?: string;
}
interface StaticResource {
    url: string;
    creativeType: string;
}
interface Variation {
    staticResources: StaticResource[];
    companionClickThroughURLTemplate: string;
    companionClickTrackingURLTemplates: string[];
    height: number | null;
    width: number | null;
    altText: string | null;
}
interface Creative {
    mediaFiles?: MediaFile[];
    duration?: number;
    id?: string;
    adParameters?: any;
    variations?: Variation[];
    type: 'linear' | 'nonlinear' | 'companion' | string;
    sequence: number | null;
}
interface URLTemplate {
    url: string;
}
interface System {
    value: string;
    version: string | null;
}
type VastExtension = {
    name: string;
    value: string | null;
    attributes: Record<string, unknown>;
    children: unknown[];
};
interface TrackingEvent {
    verificationNotExecuted: string[];
}
interface AdVerification {
    resource: string | null;
    vendor: string | null;
    browserOptional: boolean;
    apiFramework: string;
    type: string;
    parameters: string;
    trackingEvents: TrackingEvent[];
}
interface VastAd {
    id?: string;
    sequence?: number | null;
    adType?: string | null;
    adServingId?: string | null;
    categories?: string[];
    adVerifications?: AdVerification[];
    advertiser?: string | null;
    allowMultipleAds?: boolean;
    blockedAdCategories?: string[];
    creatives?: Creative[];
    description?: string | null;
    errorURLTemplates?: string[];
    expires?: number | null;
    extensions?: VastExtension[];
    fallbackOnNoAd?: boolean | null;
    followAdditionalWrappers?: boolean;
    impressionURLTemplates?: URLTemplate[];
    pricing?: any;
    survey?: string | null;
    system?: System;
    title?: string;
    viewableImpression?: any[];
}
interface Ad {
    position: string;
    vastAd?: VastAd;
}

interface Consent {
    ccpaConsent?: string;
    tcfConsent?: string;
    tcf2HasConsentForGoogle?: boolean;
    tcf2HasConsentForDailymotion?: boolean;
    isGdprApplicable?: boolean;
    gppConsentStringFromPlayer?: string;
    gppApplicableSectionsFromPlayer?: number[];
}

interface EnvironmentContext {
    appName: string;
    locale: string;
    topDomain: string;
    embedder: string;
    clientType: 'ctv' | string;
    deviceId: string;
    trafficSegment: number;
    v1st: string;
    is3rdPartyCookiesAvailable: boolean;
    osFamily?: string | null;
    osName?: string | null;
    uaFamily?: string | null;
    uaName?: string | null;
    uaVersion?: string | null;
}

interface PlayerContext {
    videoTag: HTMLVideoElement;
    isPlayerControlsEnabled: boolean;
}

interface VideoState {
    id?: string;
    isAutoplay: boolean;
    type: 'STREAM' | 'LIVE';
    isCurrentTimeDVR: boolean;
    isSeekable: boolean;
    viewId: string;
    duration?: number | null;
    publisherId: string;
    publisherType: string;
    publisherReference: string;
    playlistId?: string;
    streamTech?: 'hls.js' | 'native' | '';
    ownerId?: string;
    ownerParentId?: string;
    protectedDelivery?: boolean;
    createdTime?: number;
    isPasswordProtected?: boolean;
    isPrivate?: boolean;
    mimeType: string;
}

interface AppState {
    consent: Consent;
    video: VideoState;
    environment: EnvironmentContext;
    player: PlayerContext;
}

interface DevelopmentOptions {
    useFakeAd: boolean;
    vmapUrl: string;
}

declare class AdSdkWeb {
    private adVideoElement;
    private adContainer;
    private playerContainer;
    private scriptLoaded;
    constructor();
    /**
     * Initializes the Ad SDK by loading the external script and preparing the DOM elements.
     * @throws If no container is provided or if script fails to load.
     * @param playerContainer
     */
    initialize(playerContainer: HTMLElement): Promise<void>;
    /**
     * Loads the ad with the given content video tag.
     * @param appState
     * @param developmentOptions
     * @throws If the Ad SDK is not initialized or ad elements are missing.
     */
    loadAdsSequence(appState: AppState, developmentOptions?: DevelopmentOptions): Promise<void>;
    /**
     * Starts playing the ad.
     * @throws If the Ad SDK is not initialized.
     */
    playAd(): void;
    /**
     * Stops playing the ad.
     * @throws If the Ad SDK is not initialized.
     */
    pauseAd(): void;
    /**
     * Skips the ad.
     * @throws If the Ad SDK is not initialized.
     */
    skipAd(): void;
    /**
     * Retrieves details about the currently loaded ad.
     * @returns An object containing the ad position (e.g., pre-roll, mid-roll).
     * @throws If the Ad SDK is not initialized.
     */
    getAdDetails(): Ad | null;
    /**
     * Subscribes to a specific Ad SDK event.
     * @param event - The name of the event to listen for.
     * @param callback - The event handler callback.
     * @throws If the Ad SDK is not initialized.
     */
    on(event: AdEvents.AD_ERROR, callback: ErrorCallback): void;
    on(event: Exclude<AdEvents, AdEvents.AD_ERROR>, callback: StandardCallback): void;
    /**
     * Unsubscribes from a specific Ad SDK event.
     * @param event - The name of the event to stop listening for.
     * @param callback - The callback function to remove.
     * @throws If the Ad SDK is not initialized.
     */
    off(event: AdEvents.AD_ERROR, callback: ErrorCallback): void;
    off(event: Exclude<AdEvents, AdEvents.AD_ERROR>, callback: StandardCallback): void;
    /**
     * Updates the current initialization state of the Ad SDK.
     * Use these constants to subscribe or unsubscribe from ad lifecycle events.
     */
    updateAppState(playerState: AppState): void;
    /**
     * Provides access to the Ad SDK event names.
     * Use these constants to subscribe or unsubscribe from ad lifecycle events.
     */
    Events: typeof AdEvents;
    private createAdVideoElement;
    private createAdContainer;
    private loadScript;
}

export { AdEvents, AdSdkWeb };
export type { Ad, AppState, DevelopmentOptions };