feat: Standardize ads-ad-skipped event (#542)

docs/integrator/api.md

@@ -30,8 +30,8 @@ Your ad plugin can invoke these methods and events to play (or skip) ads. See [G
   * For a preroll ad, you can invoke `startLinearAdMode` after the `readyforpreroll` event if `isWaitingForAdBreak()` is true.
   * For a midroll ad, you can invoke `startLinearAdMode` during content playback if `isInAdMode()` is false.
   * For a postroll ad, you can invoke `startLinearAdMode` after the `readyforpostroll` event if `isWaitingForAdBreak()` is true.
-* `ads-ad-started` (event) -- Trigger this event during an ad break to indicate that an ad has actually started playing. This will hide the loading spinner. It is possible for an ad break to end without playing any ads.
-* `endLinearAdMode()` (method) -- Invoke this method to end an ad break. This will cause content to resume. You can check if an ad break is active using `inAdBreak()`.
+* `ads-ad-started` (EVENT) -- Trigger this event during an ad break to indicate that an ad has actually started playing. This will hide the loading spinner. It is possible for an ad break to end without playing any ads.
+* `endLinearAdMode()` (METHOD) -- Invoke this method to end an ad break. This will cause content to resume. You can check if an ad break is active using `inAdBreak()`.
 * `skipLinearAdMode()` (METHOD) -- At a time when `startLinearAdMode()` is expected, calling `skipLinearAdMode()` will immediately resume content playback instead.
 * `nopreroll` (EVENT) -- You can trigger this event even before `readyforpreroll` to indicate that no preroll will play. The ad plugin will not check for prerolls and will instead begin content playback after the `play` event (or immediately, if playback was already requested).
 * `nopostroll` (EVENT) -- Similar to `nopreroll`, you can trigger this event even before `readyforpostroll` to indicate that no postroll will play.  The ad plugin will not wait for a postroll to play and will instead immediately trigger the `ended` event.

docs/integrator/common-interface.md

@@ -1,6 +1,6 @@
 # Common Interface
 
-videojs-contrib-ads does not implement these. This page establishes a convention used some some ad plugins that you may want to consider sending for consistency as they may be useful.
+videojs-contrib-ads does not implement these. This page establishes a convention used by some ad plugins that you may want to consider sending for consistency as they may be useful.
 
 ## Events
 
@@ -10,6 +10,7 @@ videojs-contrib-ads does not implement these. This page establishes a convention
 * `ads-pod-ended`: Fired when a LINEAR ad pod has completed.
 * `ads-allpods-completed`: Fired when all LINEAR ads are completed.
 * `ads-ad-started`: Fired when the ad starts playing. Should include the event parameter `indexInBreak`.
+* `ads-ad-skipped`: Fired when the ad unit is skipped. 
 * `ads-ad-ended`: Fired when the ad completes playing.
 * `ads-first-quartile`: Fired when the ad playhead crosses first quartile.
 * `ads-midpoint`: Fired when the ad playhead crosses midpoint.
@@ -34,4 +35,9 @@ player.ads.ad = {
   "duration": `Number`,
   "currentTime": `Function`
 }
+
+player.ads.pod = {
+  "id": `String`,
+  "size": `Number`
+}
 ```

src/plugin.js

@@ -278,7 +278,7 @@ const contribAdsPlugin = function(options) {
   player.on([
     'play', 'playing', 'ended',
     'adsready', 'adscanceled', 'adskip', 'adserror', 'adtimeout', 'adended',
-    'ads-ad-started',
+    'ads-ad-started', 'ads-ad-skipped',
     'contentchanged', 'dispose', 'contentresumed', 'readyforpostroll',
     'nopreroll', 'nopostroll'
   ], (e) => {

src/states/abstract/State.js

@@ -56,6 +56,7 @@ class State {
   onAdsCanceled() {}
   onAdTimeout() {}
   onAdStarted() {}
+  onAdSkipped() {}
   onContentChanged() {}
   onContentResumed() {}
   onReadyForPostroll() {
@@ -124,6 +125,8 @@ class State {
       this.onAdTimeout(player);
     } else if (type === 'ads-ad-started') {
       this.onAdStarted(player);
+    } else if (type === 'ads-ad-skipped') {
+      this.onAdSkipped(player);
     } else if (type === 'contentchanged') {
       this.onContentChanged(player);
     } else if (type === 'contentresumed') {

test/unit/states/abstract/test.State.js

@@ -62,7 +62,45 @@ QUnit.test('is not in an ad break by default', function(assert) {
 });
 
 QUnit.test('handles events', function(assert) {
-  this.state.onPlay = sinon.stub();
-  this.state.handleEvent('play');
-  assert.ok(this.state.onPlay.calledOnce);
+  const eventNames = [
+    'play',
+    'adsready',
+    'adserror',
+    'adscanceled',
+    'adtimeout',
+    'ads-ad-started',
+    'ads-ad-skipped',
+    'contentchanged',
+    'contentresumed',
+    'readyforpostroll',
+    'playing',
+    'ended',
+    'nopreroll',
+    'nopostroll',
+    'adended'
+  ];
+
+  const methods = [
+    'onPlay',
+    'onAdsReady',
+    'onAdsError',
+    'onAdsCanceled',
+    'onAdTimeout',
+    'onAdStarted',
+    'onAdSkipped',
+    'onContentChanged',
+    'onContentResumed',
+    'onReadyForPostroll',
+    'onPlaying',
+    'onEnded',
+    'onNoPreroll',
+    'onNoPostroll',
+    'onAdEnded'
+  ];
+
+  methods.forEach((name, i) => {
+    this.state[name] = sinon.stub();
+    this.state.handleEvent(eventNames[i]);
+    assert.ok(this.state[name].calledOnce);
+  });
 });