video-ad-sdk/dist/runner/runWaterfall.d.ts

VAST/VPAID SDK that allows video ads to be played on top of any player

import { type RequestAdOptions } from '../vastRequest';
import { VastAdUnit, VpaidAdUnit } from '../adUnit';
import type { VastChain, Hooks, CancelFunction } from '../types';
import { type RunOptions } from './run';
/**
 * Error data from the ad unit error.
 */
export interface ErrorData {
    /**
     * The {@link VastChain} that caused the error.
     */
    vastChain?: VastChain;
    /**
     * Ad unit instance it can be a {@link VastAdUnit} or a {@link VpaidAdUnit}. Will only be added if the vastChain had an ad.
     */
    adUnit?: VastAdUnit | VpaidAdUnit;
}
/**
 * Hooks to configure the behaviour of the ad.
 */
export interface RunWaterfallHooks extends Hooks {
    /**
     * If provided it will be called passing the current {@link VastChain} for each valid vast response. Must throw if there is a problem with the vast response. If the Error instance has an `code` number then it will be tracked using the error macros in the Vast response. It will also call {@link runWaterfall~onError} with the thrown error.
     */
    validateVastResponse?(vastChain: VastChain): void;
    /**
     * If provided it will be called with the current {@link VastChain} before building the adUnit allowing the modification of the vastResponse if needed.
     */
    transformVastResponse?(vastChain: VastChain): VastChain;
}
/**
 * Options map to start one of the ads with {@link runWaterfall}
 */
export interface RunWaterfallOptions extends RunOptions, RequestAdOptions {
    /**
     * If false and it gets a VPAID ad, it will throw an error before starting the ad and continue down in the waterfall. Defaults to `true`.
     */
    vpaidEnabled?: boolean;
    /**
     * Will be called once the ad starts with the ad unit.
     *
     * @param adUnit the ad unit instance.
     */
    onAdStart?(adUnit: VastAdUnit | VpaidAdUnit): void;
    /**
     * Will be called whenever the an error occurs within the ad unit. It may be called several times with different errors
     *
     * @param error the ad unit error.
     * @param data Data object that will contain.
     */
    onError?(error: Error, data: ErrorData): void;
    /**
     * Will be called once the ad run is finished. It will be called no matter how the run was finished (due to an ad complete or an error). It can be used to know when to unmount the component.
     */
    onRunFinish?(): void;
    /**
     * Optional map with hooks to configure the behaviour of the ad.
     */
    hooks?: RunWaterfallHooks;
}
/**
 * Will try to start one of the ads returned by the `adTag`. It will keep trying until it times out or it runs out of ads.
 *
 * @param adTag The VAST ad tag request url.
 * @param placeholder placeholder element that will contain the video ad.
 * @param options Options Map
 * @returns CancelFunction function. If called it will cancel the ad run. {@link runWaterfall~onRunFinish} will still be called;
 */
export declare const runWaterfall: (adTag: string, placeholder: HTMLElement, options: RunWaterfallOptions) => CancelFunction;