@dailymotion/ad-sdk-web-in-feed 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,131 @@
1
- # Temporary Holding Version
1
+ # @dailymotion/ad-sdk-web-in-feed
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Plays an ad in its own vertical video, so that a host can show it anywhere in a feed.
4
+
5
+ It is independent from `@dailymotion/ad-sdk-web` (ads inside a content video) but loads the same `core.js`. Every ad is
6
+ independent: several of them can live on one page.
7
+
8
+ ```ts
9
+ import { AdSdkWebInFeedAd } from '@dailymotion/ad-sdk-web-in-feed'
10
+
11
+ // The container is positioned (e.g. `position: relative`) and has the size of the ad (e.g. a 9:16 box)
12
+ const ad = new AdSdkWebInFeedAd(container)
13
+ ad.on(ad.Events.AD_ERROR, () => removeTheCard())
14
+
15
+ const infos = await ad.loadInFeedAd({ vastUrl, environment }) // or { vastXml, ... }
16
+
17
+ ad.play() // when the ad is in front of the viewer
18
+ ad.pause() // when it leaves the screen, the tab goes to the background, the page changes...
19
+ ad.trackEvent('like') // when the viewer likes the ad, 'unlike' when they take it back
20
+ ad.destroy() // when it is removed
21
+ ```
22
+
23
+ ## API
24
+
25
+ | Method | Description |
26
+ |------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
27
+ | `new AdSdkWebInFeedAd(container)` | Creates the ad video (`div.ad-container > video.ad-video`) inside `container`. |
28
+ | `loadInFeedAd(params)` | Gets the VAST and selects the creative. Does not play. Gives the `InFeedAdInfos` (below). Rejects and emits `AD_ERROR` when no ad can be loaded. |
29
+ | `play()` | Starts the ad (first call), or resumes it. Call it once `loadInFeedAd` has resolved. |
30
+ | `pause()` | Pauses the ad. |
31
+ | `setMuted(muted)` | Mutes or unmutes the ad. |
32
+ | `trackEvent(event)` | Calls the URLs the VAST gives for `like` or `unlike` (in `events` of the extension below), with the same macros as the VAST tracking (`[ADPLAYHEAD]`, `[TIMESTAMP]`...). Does nothing before the ad is loaded. |
33
+ | `on(event, cb)` / `off(event, cb)` | See the events below. |
34
+ | `destroy()` | Stops the playback and removes everything the SDK created. Safe to call twice. |
35
+ | `Events` | `InFeedAdEvents`, the names of the events below. |
36
+
37
+ ### `loadInFeedAd` params
38
+
39
+ The ad comes from the URL of a VAST **or** from the VAST itself, exactly one of them:
40
+
41
+ | Param | Description |
42
+ |---------------|----------------------------------------------------------------------|
43
+ | `vastUrl` | URL of the VAST, from the Dailymotion ad server. The SDK fetches it. |
44
+ | `vastXml` | The VAST as an XML string, from the Dailymotion ad server. |
45
+ | `environment` | Same shape as in `@dailymotion/ad-sdk-web` (`EnvironmentContext`). |
46
+ | `isMuted` | Start muted (default `true`, required for autoplay in a feed). |
47
+
48
+ It gives the `InFeedAdInfos`, read from the `dm-infeed-infos` extension of the VAST (below). Every field is `null` when
49
+ the VAST does not give it:
50
+
51
+ | Field | |
52
+ |---------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|
53
+ | `xid` | The video of the ad. The host gets everything else it shows (creator, title...) from it. |
54
+ | `adType` | `boosted` (a video of a creator, promoted) or `standalone` (a creative that only exists as an ad). |
55
+ | `inventoryId` | The inventory the ad was served on. |
56
+ | `ownerName`, `ownerImage` | The advertiser, to show instead of the name and the profile image of the channel. |
57
+ | `dsa` | `{ behalf, paid, params }`, what the Digital Services Act requires to show about the ad. `params` is a list of numbers (e.g. `[1, 2]`). |
58
+
59
+ The ad is a stream video. The media file is attached to the video (with `preload="auto"`) as soon as the ad is loaded,
60
+ so that the browser can start downloading it
61
+ before the ad plays: call `loadInFeedAd` when the ad is about to be shown, not long before. `destroy()` stops the
62
+ download of an ad that never played.
63
+
64
+ ### Events
65
+
66
+ | Event | Callback |
67
+ |-----------------|--------------------------------------------------------------------------------|
68
+ | `AD_LOAD` | `() => void`: the ad was loaded |
69
+ | `AD_START` | `() => void`: the ad starts playing |
70
+ | `AD_PLAY` | `() => void`: the ad resumes |
71
+ | `AD_PAUSE` | `() => void`: the ad is paused |
72
+ | `AD_END` | `() => void`: the ad reached its end |
73
+ | `AD_ERROR` | `(code?: number, message?: string) => void`: the ad cannot be loaded or played |
74
+ | `VOLUME_CHANGE` | `({ muted, volume }) => void`: the volume or the mute state of the ad changed |
75
+
76
+ ## Tracking
77
+
78
+ The ad uses the same VAST tracking as the other ads of ad-sdk-web. The ad server is called for:
79
+
80
+ | Event | When |
81
+ |-----------------------------------------------------|--------------------------------------------------------------|
82
+ | `Impression`, `creativeView`, `start` | The ad starts playing. |
83
+ | `firstQuartile`, `midpoint`, `thirdQuartile` | The ad reaches 25%, 50%, 75%. |
84
+ | `complete` | The ad reaches its end. |
85
+ | `mute`, `unmute` | The sound of the ad changes. |
86
+ | `events.like`, `events.unlike` of `dm-infeed-infos` | The host calls `trackEvent('like')`, `trackEvent('unlike')`. |
87
+ | `pause`, `resume` | The ad is paused, resumed. |
88
+ | `Error` | The ad cannot be loaded or played. |
89
+
90
+ The macros of VAST (`[TIMESTAMP]`, `[ADPLAYHEAD]`, `[CACHEBUSTING]`...) are replaced.
91
+
92
+ ## Event bus
93
+
94
+ The ad sends its events to the Dailymotion event bus like the other ads, but with its own identity:
95
+
96
+ | Field | In-feed ad | Other ads |
97
+ |-----------------------------------------------|-------------------------|---------------------------------------------------|
98
+ | `info.player.type` | `Ad-SDK-Web-In-Feed-Ad` | `Ad-SDK-Web` |
99
+ | `ad_type` (position of the ad) | `infeed` | `preroll`, `midroll`, `postroll` or `liveadbreak` |
100
+ | `ad_client_inventory_id` | `<viewId>_INFEED_0_1` | `<viewId>_PRE_0_1`, `_MID_`... |
101
+ | `ad_log_id` of the SDK errors (`adLog` event) | `adSdkInFeedAdError` | `adSdkError` |
102
+
103
+ The position is `infeed` for the whole life of the ad. In-feed ads do not run any verification script (OM SDK) for now.
104
+
105
+ ## The VAST
106
+
107
+ A VAST 4.x with a stream video (MP4) and, to give the video and the kind of the ad, the Dailymotion extension. Its JSON
108
+ must be valid, otherwise the extension is ignored:
109
+
110
+ ```xml
111
+
112
+ <Extension type="dm-infeed-infos"><![CDATA[{
113
+ "version": 1,
114
+ "xid": "x9abc12",
115
+ "invId": "INVENTORY_ID",
116
+ "events": {
117
+ "like": ["https://TRACKING_URL/like?pos=[ADPLAYHEAD]&ts=[TIMESTAMP]"],
118
+ "unlike": ["https://TRACKING_URL/unlike?pos=[ADPLAYHEAD]&ts=[TIMESTAMP]"]
119
+ },
120
+ "adInfo": { "type": "standalone", "ownerName": "Advertiser", "ownerImage": "https://..." },
121
+ "dsa": { "behalf": "Advertiser", "paid": "Advertiser Inc.", "params": [1, 2] }
122
+ }]]></Extension>
123
+ ```
124
+
125
+ ## Example
126
+
127
+ `npm run dev:in-feed` from the repository root starts the core and an example
128
+ feed (https://adsdkweb.local.dailymotion.com:9098):
129
+ a vertical feed that loads an ad after the 2nd video, plays it when it is in front of the viewer and pauses it when it
130
+ leaves. A side panel tries the API by hand (`play()`, `pause()`), loads an ad from a VAST URL
131
+ or from a VAST XML, and lists the events. `?vastUrl=<url>` loads a VAST from a URL.
@@ -0,0 +1,137 @@
1
+ interface VolumeChangePayload {
2
+ muted?: boolean;
3
+ volume?: number;
4
+ }
5
+
6
+ type StandardCallback = () => void;
7
+ type ErrorCallback = (code?: number, message?: string) => void;
8
+ type VolumeChangeCallback = (payload: VolumeChangePayload) => void;
9
+
10
+ declare enum AdEvents {
11
+ AD_BREAK_START = "AD_BREAK_START",
12
+ AD_BREAK_END = "AD_BREAK_END",
13
+ AD_LOAD = "AD_LOAD",
14
+ AD_START = "AD_START",
15
+ AD_PLAY = "AD_PLAY",
16
+ AD_PAUSE = "AD_PAUSE",
17
+ AD_END = "AD_END",
18
+ AD_ERROR = "AD_ERROR",
19
+ CONTENT_PAUSE_REQUESTED = "CONTENT_PAUSE_REQUESTED",
20
+ CONTENT_RESUME_REQUESTED = "CONTENT_RESUME_REQUESTED",
21
+ AD_READY_TO_FETCH = "AD_READY_TO_FETCH",
22
+ AD_DEBUG_LOG = "AD_DEBUG_LOG",
23
+ ADS_SEQUENCE_LOADED = "ADS_SEQUENCE_LOADED",
24
+ VOLUME_CHANGE = "VOLUME_CHANGE"
25
+ }
26
+
27
+ type AppTrackingTransparencyAuthorizationStatus = 0 | 1 | 2 | 3;
28
+ /**
29
+ * Player display mode
30
+ * - regular: main player (PIP off or PIP on with main player displayed)
31
+ * - pip_expanded: PIP running, expanded
32
+ * - pip_collapsed: PIP running, small viewport
33
+ * - pip_corner: PIP running, not small viewport
34
+ */
35
+ type PlayerDisplayMode = 'regular' | 'pip_expanded' | 'pip_collapsed' | 'pip_corner';
36
+ interface EnvironmentContext {
37
+ appName: string;
38
+ locale: string;
39
+ topDomain: string;
40
+ embedder: string;
41
+ clientType: 'ctv' | string;
42
+ deviceType?: string;
43
+ deviceId?: string;
44
+ uid?: string;
45
+ readerId?: string;
46
+ dailymotionAdvertisingId?: string;
47
+ eid?: Record<string, string>;
48
+ playerDisplayMode?: PlayerDisplayMode;
49
+ trafficSegment: number;
50
+ v1st: string;
51
+ is3rdPartyCookiesAvailable: boolean;
52
+ isNativeApp?: boolean;
53
+ appTrackingTransparencyAuthorizationStatus?: AppTrackingTransparencyAuthorizationStatus;
54
+ isTrackingAllowed?: boolean;
55
+ isLimitAdTracking?: boolean;
56
+ osFamily?: string | null;
57
+ osName?: string | null;
58
+ uaFamily?: string | null;
59
+ uaName?: string | null;
60
+ uaVersion?: string | null;
61
+ asNumber?: string;
62
+ continent?: string;
63
+ country?: string;
64
+ region?: string;
65
+ }
66
+
67
+ interface InFeedAdInfos {
68
+ xid: string | null;
69
+ adType: string | null;
70
+ inventoryId: string | null;
71
+ ownerName: string | null;
72
+ ownerImage: string | null;
73
+ dsa: InFeedAdDsa | null;
74
+ }
75
+ interface InFeedAdDsa {
76
+ behalf: string | null;
77
+ paid: string | null;
78
+ params: number[] | null;
79
+ }
80
+ type InFeedAdSource = {
81
+ vastUrl: string;
82
+ vastXml?: never;
83
+ } | {
84
+ vastXml: string;
85
+ vastUrl?: never;
86
+ };
87
+ type InFeedAdParams = InFeedAdSource & {
88
+ environment: EnvironmentContext;
89
+ isMuted?: boolean;
90
+ };
91
+ declare const InFeedAdEvents: {
92
+ readonly AD_LOAD: AdEvents.AD_LOAD;
93
+ readonly AD_START: AdEvents.AD_START;
94
+ readonly AD_PLAY: AdEvents.AD_PLAY;
95
+ readonly AD_PAUSE: AdEvents.AD_PAUSE;
96
+ readonly AD_END: AdEvents.AD_END;
97
+ readonly AD_ERROR: AdEvents.AD_ERROR;
98
+ readonly VOLUME_CHANGE: AdEvents.VOLUME_CHANGE;
99
+ };
100
+ type InFeedAdEvent = (typeof InFeedAdEvents)[keyof typeof InFeedAdEvents];
101
+ type InFeedAdTrackingEvent = 'like' | 'unlike';
102
+
103
+ declare class AdSdkWebInFeedAd {
104
+ private adContainer;
105
+ private adVideoElement;
106
+ private instance;
107
+ private isDestroyed;
108
+ constructor(container: HTMLElement);
109
+ /**
110
+ * Gets the VAST, from its URL (`vastUrl`) or from its XML (`vastXml`), and selects the creative.
111
+ * Does not start the playback: call `play()` when the ad is visible.
112
+ * Gives what the host needs to draw the ad (`InFeedAdInfos`): its video, its kind, the advertiser and the DSA infos.
113
+ * Rejects when the ad cannot be loaded.
114
+ */
115
+ loadInFeedAd(params: InFeedAdParams): Promise<InFeedAdInfos | null>;
116
+ /** Starts the ad or resumes it. */
117
+ play(): Promise<void>;
118
+ pause(): void;
119
+ setMuted(muted: boolean): void;
120
+ /** Calls the URLs the VAST gives for this event, with the same macros as the VAST tracking. */
121
+ trackEvent(event: InFeedAdTrackingEvent): void;
122
+ /** Fired on every volume or mute change of the ad video, including the ones made by `setMuted`. */
123
+ on(event: AdEvents.VOLUME_CHANGE, callback: VolumeChangeCallback): void;
124
+ on(event: AdEvents.AD_ERROR, callback: ErrorCallback): void;
125
+ on(event: Exclude<InFeedAdEvent, AdEvents.VOLUME_CHANGE | AdEvents.AD_ERROR>, callback: StandardCallback): void;
126
+ off(event: AdEvents.VOLUME_CHANGE, callback: VolumeChangeCallback): void;
127
+ off(event: AdEvents.AD_ERROR, callback: ErrorCallback): void;
128
+ off(event: Exclude<InFeedAdEvent, AdEvents.VOLUME_CHANGE | AdEvents.AD_ERROR>, callback: StandardCallback): void;
129
+ /** Stops the playback, removes every listener and the elements created by the SDK. */
130
+ destroy(): void;
131
+ /** The events an in-feed ad emits. */
132
+ Events: typeof InFeedAdEvents;
133
+ private pendingListeners;
134
+ }
135
+
136
+ export { AdSdkWebInFeedAd, InFeedAdEvents };
137
+ export type { AppTrackingTransparencyAuthorizationStatus, EnvironmentContext, InFeedAdDsa, InFeedAdEvent, InFeedAdInfos, InFeedAdParams, InFeedAdSource, InFeedAdTrackingEvent, PlayerDisplayMode, VolumeChangePayload };
package/dist/index.js ADDED
@@ -0,0 +1,87 @@
1
+ var D = Object.defineProperty;
2
+ var l = (i, e, t) => e in i ? D(i, e, { enumerable: !0, configurable: !0, writable: !0, value: t }) : i[e] = t;
3
+ var d = (i, e, t) => l(i, typeof e != "symbol" ? e + "" : e, t);
4
+ var n = /* @__PURE__ */ ((i) => (i.AD_BREAK_START = "AD_BREAK_START", i.AD_BREAK_END = "AD_BREAK_END", i.AD_LOAD = "AD_LOAD", i.AD_START = "AD_START", i.AD_PLAY = "AD_PLAY", i.AD_PAUSE = "AD_PAUSE", i.AD_END = "AD_END", i.AD_ERROR = "AD_ERROR", i.CONTENT_PAUSE_REQUESTED = "CONTENT_PAUSE_REQUESTED", i.CONTENT_RESUME_REQUESTED = "CONTENT_RESUME_REQUESTED", i.AD_READY_TO_FETCH = "AD_READY_TO_FETCH", i.AD_DEBUG_LOG = "AD_DEBUG_LOG", i.ADS_SEQUENCE_LOADED = "ADS_SEQUENCE_LOADED", i.VOLUME_CHANGE = "VOLUME_CHANGE", i))(n || {});
5
+ const _ = {
6
+ AD_LOAD: n.AD_LOAD,
7
+ AD_START: n.AD_START,
8
+ AD_PLAY: n.AD_PLAY,
9
+ AD_PAUSE: n.AD_PAUSE,
10
+ AD_END: n.AD_END,
11
+ AD_ERROR: n.AD_ERROR,
12
+ VOLUME_CHANGE: n.VOLUME_CHANGE
13
+ }, o = "https://asw.dmcdn.net/2.0.0/core.js";
14
+ let r = null;
15
+ const h = () => window.AdSdkInFeedAd ? Promise.resolve() : r || (r = new Promise((i, e) => {
16
+ const t = document.createElement("script");
17
+ t.src = o, t.onload = () => i(), t.onerror = () => {
18
+ t.remove(), r = null, e(new Error(`Failed to load script: ${o}`));
19
+ }, document.head.appendChild(t);
20
+ }), r);
21
+ class R {
22
+ constructor(e) {
23
+ d(this, "adContainer", null);
24
+ d(this, "adVideoElement", null);
25
+ d(this, "instance", null);
26
+ d(this, "isDestroyed", !1);
27
+ /** The events an in-feed ad emits. */
28
+ d(this, "Events", _);
29
+ d(this, "pendingListeners", []);
30
+ if (!e) throw new Error("No container provided");
31
+ this.adContainer = document.createElement("div"), this.adContainer.classList.add("ad-container"), this.adVideoElement = document.createElement("video"), this.adVideoElement.classList.add("ad-video"), this.adVideoElement.setAttribute("playsinline", ""), this.adVideoElement.setAttribute("webkit-playsinline", ""), this.adVideoElement.muted = !0, this.adVideoElement.style.objectFit = "contain", this.adVideoElement.style.backgroundColor = "#0D0D0D", this.adContainer.appendChild(this.adVideoElement), e.appendChild(this.adContainer);
32
+ }
33
+ /**
34
+ * Gets the VAST, from its URL (`vastUrl`) or from its XML (`vastXml`), and selects the creative.
35
+ * Does not start the playback: call `play()` when the ad is visible.
36
+ * Gives what the host needs to draw the ad (`InFeedAdInfos`): its video, its kind, the advertiser and the DSA infos.
37
+ * Rejects when the ad cannot be loaded.
38
+ */
39
+ async loadInFeedAd(e) {
40
+ if (this.isDestroyed) throw new Error("In-feed ad has been destroyed");
41
+ if (await h(), this.isDestroyed) throw new Error("In-feed ad has been destroyed");
42
+ this.instance || (this.instance = AdSdkInFeedAd.createInFeedAd({
43
+ adVideoTag: this.adVideoElement,
44
+ adContainer: this.adContainer
45
+ }));
46
+ const t = this.instance;
47
+ return this.pendingListeners.forEach(([s, a]) => t.on(s, a)), this.pendingListeners = [], t.loadInFeedAd(e);
48
+ }
49
+ /** Starts the ad or resumes it. */
50
+ play() {
51
+ var e;
52
+ return ((e = this.instance) == null ? void 0 : e.play()) ?? Promise.resolve();
53
+ }
54
+ pause() {
55
+ var e;
56
+ (e = this.instance) == null || e.pause();
57
+ }
58
+ setMuted(e) {
59
+ var t;
60
+ this.adVideoElement && (this.adVideoElement.muted = e), (t = this.instance) == null || t.setMuted(e);
61
+ }
62
+ /** Calls the URLs the VAST gives for this event, with the same macros as the VAST tracking. */
63
+ trackEvent(e) {
64
+ var t;
65
+ (t = this.instance) == null || t.trackEvent(e);
66
+ }
67
+ on(e, t) {
68
+ const s = t;
69
+ this.instance ? this.instance.on(e, s) : this.pendingListeners.push([e, s]);
70
+ }
71
+ off(e, t) {
72
+ var a;
73
+ const s = t;
74
+ this.pendingListeners = this.pendingListeners.filter(
75
+ ([E, A]) => E !== e || A !== s
76
+ ), (a = this.instance) == null || a.off(e, s);
77
+ }
78
+ /** Stops the playback, removes every listener and the elements created by the SDK. */
79
+ destroy() {
80
+ var e, t;
81
+ this.isDestroyed || (this.isDestroyed = !0, (e = this.instance) == null || e.destroy(), this.instance = null, this.pendingListeners = [], (t = this.adContainer) == null || t.remove(), this.adContainer = null, this.adVideoElement = null);
82
+ }
83
+ }
84
+ export {
85
+ R as AdSdkWebInFeedAd,
86
+ _ as InFeedAdEvents
87
+ };
package/package.json CHANGED
@@ -1,6 +1,49 @@
1
1
  {
2
2
  "name": "@dailymotion/ad-sdk-web-in-feed",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "author": "Dailymotion <ad-sdk-web@dailymotion.com> (https://developer.dailymotion.com/)",
4
+ "version": "1.0.0",
5
+ "description": "JavaScript SDK to display video ads in a feed, by Dailymotion",
6
+ "keywords": [
7
+ "vast",
8
+ "ad",
9
+ "advertising",
10
+ "feed",
11
+ "video"
12
+ ],
13
+ "repository": {
14
+ "type": "git",
15
+ "url": "https://github.com/dailymotion/ad-sdk-sample"
16
+ },
17
+ "type": "module",
18
+ "main": "dist/index.js",
19
+ "types": "dist/index.d.ts",
20
+ "files": [
21
+ "dist/index.js",
22
+ "dist/index.d.ts"
23
+ ],
24
+ "publishConfig": {
25
+ "registry": "https://registry.npmjs.org"
26
+ },
27
+ "scripts": {
28
+ "dev": "vite",
29
+ "build": "vite build --config vite.sdk.config.js && rollup -c vite.dts.config.js",
30
+ "build:examples": "tsc && vite build",
31
+ "preview": "vite preview",
32
+ "style": "eslint .",
33
+ "type-check": "tsc --noEmit",
34
+ "test": "vitest run --passWithNoTests"
35
+ },
36
+ "devDependencies": {
37
+ "@eslint/css": "^0.7.0",
38
+ "@eslint/js": "^9.26.0",
39
+ "@stylistic/eslint-plugin": "^4.4.1",
40
+ "@types/node": "^24.0.14",
41
+ "eslint": "^9.26.0",
42
+ "globals": "^16.0.0",
43
+ "rollup-plugin-dts": "^6.2.1",
44
+ "typescript": "~5.7.2",
45
+ "typescript-eslint": "^8.32.0",
46
+ "vite": "^6.2.0",
47
+ "vitest": "^3.2.4"
48
+ }
49
+ }