docs: ✏️ (xgplayer-ads) 更新readme

fixtures/ads/index.js

@@ -1,4 +1,4 @@
-import AdPlugin from '../../packages/xgplayer-ads/src'
+import AdPlugin, { AdEvents } from '../../packages/xgplayer-ads/src'
 import { Logger } from '../../packages/xgplayer-streaming-shared/src/logger'
 import Player from '../../packages/xgplayer/src/index.umd'
 
@@ -11,36 +11,37 @@ window.player = new Player({
   autoplay: true,
   width: '80%',
   height: 700,
-  ignores:[],
+  ignores: [],
   plugins: [AdPlugin],
   ad: {
     adType: 'ima'
   }
 })
 
-player.on('adPlay', function (e) {
+player.on(AdEvents.AD_PLAY, function (e) {
   console.log('=====> AD_PLAY', e)
 })
 
-player.on('adPause', function (e) {
+player.on(AdEvents.AD_PAUSE, function (e) {
   console.log('=====> AD_PAUSE', e)
 })
 
+player.on(AdEvents.IMA_AD_LOADER_READY, function (e) {
+  // Request video ads.
+  const adsRequest = new google.ima.AdsRequest()
+  adsRequest.adTagUrl =
+    'https://pubads.g.doubleclick.net/gampad/ads?' +
+    'iu=/21775744923/external/single_ad_samples&sz=640x480&' +
+    'cust_params=sample_ct%3Dlinear&ciu_szs=300x250%2C728x90&gdfp_req=1&' +
+    'output=vast&unviewed_position_start=1&env=vp&impl=s&correlator='
 
+  // Specify the linear and nonlinear slot sizes. This helps the SDK to
+  // select the correct creative if multiple are returned.
+  adsRequest.linearAdSlotWidth = 640
+  adsRequest.linearAdSlotHeight = 400
 
-// Request video ads.
-const adsRequest = new google.ima.AdsRequest()
-adsRequest.adTagUrl = 'https://pubads.g.doubleclick.net/gampad/ads?' +
-  'iu=/21775744923/external/single_ad_samples&sz=640x480&' +
-  'cust_params=sample_ct%3Dlinear&ciu_szs=300x250%2C728x90&gdfp_req=1&' +
-  'output=vast&unviewed_position_start=1&env=vp&impl=s&correlator='
+  adsRequest.nonLinearAdSlotWidth = 640
+  adsRequest.nonLinearAdSlotHeight = 150
 
-// Specify the linear and nonlinear slot sizes. This helps the SDK to
-// select the correct creative if multiple are returned.
-adsRequest.linearAdSlotWidth = 640
-adsRequest.linearAdSlotHeight = 400
-
-adsRequest.nonLinearAdSlotWidth = 640
-adsRequest.nonLinearAdSlotHeight = 150
-
-player.plugins.ad.requestAd(adsRequest)
+  player.plugins.ad.requestAds(adsRequest)
+})

packages/xgplayer-ads/README.md

@@ -8,7 +8,7 @@ xgplayer-ads 插件内提供了对 'Google IMA', 'Google DAI' 符合VAST、VMAP
 
 ```javascript
 import Player from "xgplayer"
-import AdPlugin, { IMA } from "xgplayer-ads"
+import AdPlugin, { ADEvents } from "xgplayer-ads"
 import "xgplayer/dist/xgplayer.min.css"
 
 const player = new Player({
@@ -19,22 +19,46 @@ const player = new Player({
     width: window.innerWidth,
     plugins: [AdPlugin],
     ad: {
-      adType: IMAPlugin
+      adType: 'ima',
     }
 })
 
+player.on(ADEvents.AD_PLAY, ()=>{
+    // do something
+})
 player.on('adPlay', ()=>{
     // do something
 })
+player.on('adPause', ()=>{})
+
+
+function createAdsRequest() {
+  // Request video ads.
+  const adsRequest = new google.ima.AdsRequest()
+  adsRequest.adTagUrl = 'https://pubads.g.doubleclick.net/gampad/ads?' +
+        'iu=/21775744923/external/single_ad_samples&sz=640x480&' +
+        'cust_params=sample_ct%3Dlinear&ciu_szs=300x250%2C728x90&gdfp_req=1&' +
+        'output=vast&unviewed_position_start=1&env=vp&impl=s&correlator='
+
+  // Specify the linear and nonlinear slot sizes. This helps the SDK to
+  // select the correct creative if multiple are returned.
+  adsRequest.linearAdSlotWidth = 640
+  adsRequest.linearAdSlotHeight = 400
+  adsRequest.nonLinearAdSlotWidth = 640
+  adsRequest.nonLinearAdSlotHeight = 150
+  return adsRequest
+}
 
 ```
 
 
 可配置的能力
 
-| 配置字段 | 默认值 | 含义 |
+| 配置字段 | 类型 | 含义 |
 | ------ | -------- | ----- |
-| locale |  |  |
+| locale | string | 参看：[Localizing for language and locale](https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/localization) |
+| adsRequest | object | 参看：[google.ima.AdsRequest](https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/reference/js/google.ima.AdsRequest) |
+| adTagUrl | string | adsRequest的一个参数，指定向广告服务器请求地址 |
 
 
 事件（Events）
@@ -51,6 +75,7 @@ player.on('adPlay', ()=>{
 | ------ | ----- |
 | adPlay | 当广告启播时，发布此事件 |
 | adPause | 当广告暂停时，发布此事件 |
+| adPause | 当广告暂停时，发布此事件 |
 
 ## IMA
 
@@ -89,7 +114,10 @@ TODO: 待调研
 2. 广告的状态应尽可能独立于 xgplayer 中抽离出来，并通过插件的方式获取
     
     - 贴片广告UI和正片差异化很大时，如何实现？
+        - 这种情况下，广告的样式完全实现于广告插件中。
+        - 广告插件开放自定义UI的能力，可以实现广告UI的定制。
     - 贴片广告UI和正片差异化不大时，需要复用控制条样式，并进行一些小的修改，如何实现？
+        - 播放器部分UI会针对广告时的样式进行区分，做小的微调。
 
 
 ### 广告状态、事件、方法的实现

packages/xgplayer-ads/src/events.js

@@ -3,7 +3,8 @@ export const AD_PLAY = 'adPlay'
 export const AD_PAUSE = 'adPause'
 
 // IMA Specific Events
-export const IMA_AD_MANAGER_LOADED = 'ima_ad_manager_loaded'
+export const IMA_AD_LOADER_READY = 'ima_ad_loader_ready'
+export const IMA_AD_MANAGER_READY = 'ima_ad_manager_ready'
 export const IMA_AD_PAUSE = 'ima_ad_pause'
 export const IMA_AD_ENDED = 'ima_ad_ended'
 export const IMA_AD_SKIPPED = 'ima_ad_skipped'

packages/xgplayer-ads/src/imaAdManager.js

@@ -72,7 +72,7 @@ export class ImaAdManager extends BaseAdManager {
    */
   _initLoader () {
     // Create ads loader.
-    const adsLoader = new google.ima.AdsLoader(this.displayContainer)
+    const adsLoader = (this.adsLoader = new google.ima.AdsLoader(this.displayContainer))
 
     // Listen and respond to ads loaded and error events.
     adsLoader.addEventListener(
@@ -86,7 +86,7 @@ export class ImaAdManager extends BaseAdManager {
       false
     )
 
-    this.adsLoader = adsLoader
+    this.emit(ADEvents.IMA_AD_LOADER_READY, { adsLoader })
   }
 
   /**
@@ -180,9 +180,7 @@ export class ImaAdManager extends BaseAdManager {
       this.onAdEvent()
     }
 
-    this.emit(ADEvents.IMA_AD_MANAGER_LOADED, {
-      adsManager
-    })
+    this.emit(ADEvents.IMA_AD_MANAGER_READY, { adsManager })
   }
 
   /**
@@ -192,6 +190,7 @@ export class ImaAdManager extends BaseAdManager {
   _initAdsManagerEventListeners () {
     const adsManager = this.adsManager
 
+    // https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/reference/js/google.ima.AdErrorEvent
     adsManager.addEventListener(google.ima.AdErrorEvent.Type.AD_ERROR, this.onAdError)
 
     // https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/reference/js/google.ima.AdEvent
@@ -296,7 +295,7 @@ export class ImaAdManager extends BaseAdManager {
       // This event is sent when an ad is resumed after a pause.
       case google.ima.AdEvent.Type.RESUMED: {
         this._isAdPaused = false
-        this.player.emit(Events.PLAY, {
+        this.player.emit(ADEvents.AD_PLAY, {
           ad
         })
         break
@@ -305,7 +304,7 @@ export class ImaAdManager extends BaseAdManager {
       // This event is sent when an ad is paused before it finishes.
       case google.ima.AdEvent.Type.PAUSED: {
         this._isAdPaused = true
-        this.player.emit(Events.PAUSE, {
+        this.player.emit(ADEvents.AD_PAUSE, {
           ad
         })
         break

packages/xgplayer-ads/src/index.js

@@ -1,109 +1,5 @@
-import { BasePlugin, Plugin, Util } from 'xgplayer'
-import { Logger } from 'xgplayer-streaming-shared'
 import * as AdEvents from './events'
-import { ImaAdManager } from './imaAdManager'
-import './index.scss'
+import { AdsPlugin } from './plugin'
 
-const logger = new Logger('AdsPlugin')
-
-export default class AdsPlugin extends Plugin {
-  static get pluginName () {
-    return 'ad'
-  }
-  get version () {
-    return __VERSION__
-  }
-
-  afterCreate () {
-    this.csManager = undefined
-  }
-
-  beforePlayerInit () {
-    this._initHooks()
-    this._proxyPlayer()
-
-    const promise = new Promise((resolve, reject) => {
-      if (this.config.adType === 'ima') {
-        this.initClientSideAd()
-
-        this.csManager?.on(AdEvents.IMA_AD_MANAGER_LOADED, () => {
-          resolve()
-        })
-      }
-    })
-
-    return promise
-  }
-
-  /**
-   * @private
-   */
-  _initHooks () {
-    this.player.useHooks('play', () => {
-      if (this.csManager?.isAdRunning) {
-        this.csManager?.play()
-        return false
-      }
-    })
-    this.player.useHooks('pause', () => {
-      if (this.csManager?.isAdRunning) {
-        this.csManager?.pause()
-        return false
-      }
-    })
-  }
-
-  /**
-   * @private
-   */
-  _proxyPlayer () {
-    const { player } = this
-
-    BasePlugin.defineGetterOrSetter(player, {
-      adPaused: {
-        get: () => {
-          const media = player.media || player.video
-          logger.log(
-            'csManager.paused',
-            this.csManager?.isAdRunning,
-            this.csManager.paused,
-            this.csManager?.isAdRunning
-              ? this.csManager.paused
-              : media
-                ? media.paused
-                : true
-          )
-          return this.csManager?.isAdRunning
-            ? this.csManager.paused
-            : media
-              ? media.paused
-              : true
-        },
-        configurable: true
-      }
-    })
-  }
-
-  render () {
-    return Util.createDom('xg-ad', '', {}, 'xgplayer-ads')
-  }
-
-  initClientSideAd () {
-    if (this.config.adType === 'ima') {
-      this.initImaAd()
-    }
-  }
-
-  initImaAd () {
-    this.csManager = new ImaAdManager({
-      displayContainer: this.root,
-      player: this.player
-    })
-
-    this.csManager.init()
-  }
-
-  destroy () {
-    this.csManager?.destroy()
-  }
-}
+export { AdEvents, AdsPlugin }
+export default AdsPlugin

packages/xgplayer-ads/src/plugin.js

@@ -0,0 +1,118 @@
+import { BasePlugin, Plugin, Util } from 'xgplayer'
+import { Logger, createPublicPromise } from 'xgplayer-streaming-shared'
+import * as AdEvents from './events'
+import { ImaAdManager } from './imaAdManager'
+import './index.scss'
+
+const logger = new Logger('AdsPlugin')
+
+export class AdsPlugin extends Plugin {
+  static get pluginName () {
+    return 'ad'
+  }
+  get version () {
+    return __VERSION__
+  }
+
+  afterCreate () {
+    this.csManager = undefined
+  }
+
+  beforePlayerInit () {
+    this._initHooks()
+    this._proxyPlayer()
+
+    this.initPromise = createPublicPromise()
+
+    if (this.config.adType === 'ima') {
+      this.initClientSideAd()
+    }
+
+    return this.initPromise
+  }
+
+  /**
+   * @private
+   */
+  _initHooks () {
+    this.player.useHooks('play', () => {
+      if (this.csManager?.isAdRunning) {
+        this.csManager?.play()
+        return false
+      }
+    })
+    this.player.useHooks('pause', () => {
+      if (this.csManager?.isAdRunning) {
+        this.csManager?.pause()
+        return false
+      }
+    })
+  }
+
+  /**
+   * @private
+   */
+  _proxyPlayer () {
+    const { player } = this
+
+    BasePlugin.defineGetterOrSetter(player, {
+      adPaused: {
+        get: () => {
+          const media = player.media || player.video
+          logger.log(
+            'csManager.paused',
+            this.csManager?.isAdRunning,
+            this.csManager.paused,
+            this.csManager?.isAdRunning
+              ? this.csManager.paused
+              : media
+                ? media.paused
+                : true
+          )
+          return this.csManager?.isAdRunning
+            ? this.csManager.paused
+            : media
+              ? media.paused
+              : true
+        },
+        configurable: true
+      }
+    })
+  }
+
+  render () {
+    return Util.createDom('xg-ad', '', {}, 'xgplayer-ads')
+  }
+
+  initClientSideAd () {
+    if (this.config.adType === 'ima') {
+      this.initImaAd()
+    }
+  }
+
+  initImaAd () {
+    this.csManager = new ImaAdManager({
+      displayContainer: this.root,
+      player: this.player
+    })
+
+    this.csManager.on(AdEvents.IMA_AD_LOADER_READY, () => {
+      this.emit(AdEvents.IMA_AD_LOADER_READY)
+    })
+    this.csManager.on(AdEvents.IMA_AD_MANAGER_READY, () => {
+      this.initPromise?.resolve()
+      this.emit(AdEvents.IMA_AD_MANAGER_READY)
+    })
+
+
+    this.csManager.init()
+  }
+
+  requestAds (payload) {
+    this.csManager?.requestAds(payload)
+  }
+
+  destroy () {
+    this.csManager?.destroy()
+  }
+}