Ad SDK Web

A lightweight web wrapper for Dailymotion's Ad SDK – load, manage, and interact with video ads easily in modern web players.

⚙️ Required HTML & CSS Setup for the Player Container

To use our Ad SDK Web, you must define an HTML player container element styled correctly to hold both your content video tag and Ad SDK playback elements.

CSS styles to add

.videoPlayerContainer {
  position: relative;
  width: auto;
  height: 100%;
  aspect-ratio: 16 / 9;
}

.videoPlayerContainer is the wrapper where the SDK mounts the ad container and your video element.

The container is positioned relative to allow absolute positioning of ad overlays if needed.

The aspect ratio keeps the player consistent across screen sizes.

Example implementation reference

👉 Check out an example implementation here: https://dailymotion.github.io/ad-sdk-sample/

📘 Public API Documentation

async initialize(playerContainer: HTMLElement): Promise<void>

Loads the external ad SDK script and creates internal DOM elements for ad playback. This method should be called before any other function of the SDK and once per page.

Parameters:

• playerContainer: HTMLElement The DOM element where the ad container will be mounted.

Throws: If the container is missing or the script fails to load.

loadAdsSequence(appState: AppState, developmentOptions?: DevelopmentOptions): Promise<void>

Loads ads sequence with the provided contextual information.

After this call, the ad SDK will listen to the progress of the video and will trigger an AD_BREAK_START event whenever an ad break is about to begin. When this event occurs, the video player is expected to pause playback. Playback should resume only after the corresponding AD_BREAK_END event is received.

A preroll ad may start automatically after this call. If no preroll is available, the SDK will send an AD_BREAK_END event to indicate that content playback can proceed.

This method should be called once per video, before starting the main content.

Parameters:

• appState: AppState A structured object providing ad targeting and playback environment data.
  👉 See full structure below or jump to AppState
• developmentOptions: DevelopmentOptions Optional settings used only during development. 👉 See full structure below or jump to DevelopmentOptions

playAd(): void

Request the SDK to start the ad playback.

Throws:
If the SDK is not initialized.

pauseAd(): void

Request the SDK to pause the ad.

Throws:
If the SDK is not initialized.

skipAd(): void

Request the SDK to skip the currently playing ad.

Throws:
If the SDK is not initialized.

getAdDetails(): AdDetails

Returns detailed information about the currently playing ad.

Returns:
An AdDetails object containing properties such as position, ad duration, and other metadata.

👉 See full structure below or jump to AdDetails

on(event: AdEvents, callback: EventCallback): void

Subscribes to a specific Ad SDK event.

Parameters:

• event: AdEvents
  The event name to listen for.
  👉 See AdEvents for available event names.

• callback: EventCallback
  The callback function to execute when the event occurs.

  Callback signature depends on the event:

  • For AD_ERROR: (code?: number, message?: string) => void
    The callback receives optional VAST error code and message parameters.
  • For all other events: () => void
    The callback receives no parameters.

Throws:
If the Ad SDK is not initialized.

Example:

// Standard event callback (no parameters)
adSDK.on(adSDK.Events.AD_BREAK_START, () => {
  console.log('Ad break started')
})

// Error event callback (with code and message)
adSDK.on(adSDK.Events.AD_ERROR, (code, message) => {
  console.error('Ad error:', code, message)
})

off(event: AdEvents, callback: EventCallback): void

Unsubscribes from a specific Ad SDK event.

Parameters:

• event: AdEvents
  The event name to stop listening for.
  👉 See AdEvents for available event names.

• callback: EventCallback
  The callback function to remove. Must be the same function reference that was passed to on().

  Callback signature depends on the event:

  • For AD_ERROR: (code?: number, message?: string) => void
  • For all other events: () => void

Throws:
If the Ad SDK is not initialized.

updateAppState(appState: AppState): void

Updates the SDK with a new state payload.

Parameters:

• appState: AppState
  Updated app context data. 👉 See full structure below or jump to AppState

Data structures

AppState

| Parameter | Type | Required | Description | | ----------- | ------------------ | -------- | --------------------------------------------------------------------------------------- | | consent | Consent | yes | User consent and privacy settings relevant for ad personalization and legal compliance. | | video | VideoState | yes | Current video playback state and characteristics affecting ad behavior. | | environment | EnvironmentContext | yes | Context about the app environment, locale, and device details. | | player | PlayerContext | yes | Settings and references related to the video player instance. |

Consent

| Parameter | Type | Required | Default | Description | | ------------------------------- | -------- | -------- | -------- | ------------------------------------------------------------------------------ | | ccpaConsent | string | no | '1---' | User’s consent status under the California Consumer Privacy Act. | | tcfConsent | string | no | '' | Consent string according to the IAB Transparency and Consent Framework (TCF). | | tcf2HasConsentForGoogle | boolean | no | false | Whether consent has been given for Google in TCF v2 context. | | tcf2HasConsentForDailymotion | boolean | no | false | Whether consent has been given for Dailymotion in TCF v2 context. | | isGdprApplicable | boolean | no | false | Indicates if GDPR regulations apply to the current user/session. | | gppConsentStringFromPlayer | string | no | '' | GPP consent string received from the player. | | gppApplicableSectionsFromPlayer | number[] | no | [] | Array of GPP section IDs that apply to the user based on player configuration. |

VideoState

| Parameter | Type | Required | Default | Description | | ------------------ | ------- | -------- | ------- | ---------------------------------------------------------------- | | id | string | yes | — | The video id | | isAutoplay | boolean | yes | — | Whether the video is set to autoplay. | | type | string | yes | — | Indicates if the type of the video. LIVE | STREAM | | isCurrentTimeDVR | boolean | yes | — | Whether the current playback position is within a DVR window. | | isSeekable | boolean | yes | — | Whether the video player supports seeking functionality. | | duration | number | no | 0 | The duration of the video | | viewId | string | yes | — | Unique identifier for the video view or playback session. | | publisherId | string | yes | — | Identifier of the content publisher. | | publisherType | string | yes | — | Type/category of the publisher. | | publisherReference | string | yes | — | Reference code or identifier of the publisher. | | playlistId | string | no | '' | The playlist id. | | streamTech | string | no | '' | Playback technology used by the stream. 'hls.js' | 'native' | | ownerId | string | no | '' | Identifier of the video owner account. | | ownerParentId | string | no | '' | Identifier of the owner's parent. | | protectedDelivery | boolean | no | — | | | createdTime | number | no | 0 | Video creation timestamp in milliseconds since epoch. | | isPasswordProtected| boolean | no | false | Whether the video requires a password to view. | | isPrivate | boolean | no | false | Whether the video is private. | | mimeType | string | yes | — | MIME type of the content, e.g., video/mp4. |

EnvironmentContext

| Parameter | Type | Required | Description | | -------------------------- | ------- | -------- | ----------------------------------------------------------------- | | appName | string | yes | Name of the app or website embedding the player. | | locale | string | yes | Locale or language setting for the user session. | | topDomain | string | yes | The top-level domain of the page embedding the player. | | embedder | string | yes | Identifier or name of the embedding entity or partner. | | clientType | string | yes | Type of client (e.g., web, mobile app, CTV). | | deviceId | string | yes | Unique identifier for the user’s device. | | trafficSegment | number | yes | Numeric segment ID used for traffic or user segmentation. | | v1st | string | yes | A unique ID automatically assigned to your device by Dailymotion. | | is3rdPartyCookiesAvailable | boolean | yes | Indicates if third-party cookies are accessible in this context. | | osFamily | string | no | Operating system family parsed from UA, e.g., Linux. | | osName | string | no | Operating system name parsed from UA, e.g., Ubuntu. | | uaFamily | string | no | User agent family, e.g., Chromium. | | uaName | string | no | User agent name, e.g., Chrome. | | uaVersion | string | no | User agent version, e.g., 120.0.0. |

PlayerContext

| Parameter | Type | Required | Description | | ----------------------- | ---------------- | -------- | ---------------------------------------- | | videoTag | HTMLVideoElement | yes | Reference to the HTML video element. | | isPlayerControlsEnabled | boolean | yes | Whether the player controls are enabled. |

DevelopmentOptions

Intended only for development and testing purposes.

| Parameter | Type | Required | Description | | --------- | ------- | -------- | ----------------------------- | | useFakeAd | boolean | no | Enables a fake ad simulation. |

Internal data models

AdDetails

| Parameter | Type | Description | | ----------------- | ------------------------------------ | ------------------------------------------------------------ | | skipOffset | number | Time in seconds after which the ad can be skipped. | | duration | number | Total duration of the ad in seconds. | | mediaFile | string | URL of the media file (video/audio) for the ad. | | impressionTracker | string | URL used to track ad impressions (views). | | midrollTime | number | Timestamp in the main content when a midroll ad should play. | | position | 'preroll' | 'midroll' | 'postroll' | Indicates the ad position relative to the main content. |

AdEvents

| Parameter | Description | Callback Signature | | ------------------------ | -------------------------------------------------- | ------------------------------------- | | AD_BREAK_START | Sent when the ad break has started | () => void | | AD_BREAK_END | Sent when the ad break has ended | () => void | | AD_LOAD | Sent when the ad has loaded | () => void | | CONTENT_PAUSE_REQUESTED | Sent to pause the content for midroll ads | () => void | | AD_START | Sent when the ad has started | () => void | | AD_PLAY | Sent when the ad is played | () => void | | AD_PAUSE | Sent when the ad is paused | () => void | | AD_END | Sent when an ad has ended | () => void | | AD_ERROR | Sent when an error preventing to play an ad occurs | (code?: number, message?: string) => void | | CONTENT_RESUME_REQUESTED | Sent to resume content after an ad | () => void |

Note: The AD_ERROR event callback receives optional code (number) and message (string) parameters containing VAST error information. The error code corresponds to IAB VAST error codes (e.g., 100, 300, 400, etc.). All other events use a callback with no parameters.

SDK and Events sequences for each ad position

Preroll sequence

Midroll sequence

Postroll sequence