Making a VPAID 2 Compliant Flash Creative

Intro

现在国内的视频站点已陆续开始支持符合 VPAID 2 协议的广告了。VPAID 是 IAB 给出的一个广告规范，可让用户在广告播放期间与之交互，并知会支持 VPAID 创意的播放器相关的用户行为和事件。

VPAID 协议不处理跨平台的问题。一个符合 VPAID 协议的 Flash 广告，不能同 JavaScript 版本的 VPAID 播放器通信。因此，要支持多个平台，必须使用不同的语言制作多种格式的广告，或者经过其他协议转换。下面的内容是针对 Flash 平台的，我用的 IDE 是 Flash Professional CC 2014，和 ActionScript 3.0 语言。

VPAID 2 是可以独立于 VAST 3 工作的，所以下面只在描述一些交集事件的时候，会有和 VAST 3 协同工作的内容。

另外，这篇文章的重点是 VPAID 2 创意，不是 VPAID 2 播放器。下面会先给规范中提到的 Interface 和 Events 做注解，之后提供一个 VPAID 创意内部的视频播放控件，最后描述一个完整的创意展现、交互流程，并给出一份示例创意代码。

Interface

在 VPAID 2 规范的 6.1 一节里，给出了 VPAID 创意需要实现的方法，和推荐 VPAID 播放器获取到创意之后的封装方法。这里针对广告创意的实现，只关注前者。规范的 3.1 和 3.2 节详细描述了每一个属性和方法，下面列出这些属性和方法，并带上简要注释。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
package {
  public interface IVPAID {
    // ------------ 属性 --------------

    // 是否是线性创意。这个属性可能会根据创意当前的状态而改变。
    // 例如，一个前贴创意应该一直返回 true。
    function get adLinear():Boolean;

    // 创意的宽度。
    function get adWidth():Number

    // 创意的高度。
    function get adHeight():Number

    // 创意是否处于展开状态。
    // 例如，一个 Overlay 式的非线性创意，默认为 false；
    // 在用户交互后，创意展开，变为线性创意，此时则应为 true。
    // 再如，一个 Overlay 式的非线性创意，默认为 false；
    // 在用户交互后，创意尺寸变大，但仍未非线性创意，此时应为 true。
    // 如果一个 Overlay 式的非线性创意有多种尺寸，
    // 则只能在一种尺寸下返回 true，其他尺寸都应返回 false，
    // 一般在其到达最大尺寸时，返回 true。
    // 对于一个尺寸固定的创意，返回 false。
    function get adExpanded():Boolean;

    // 创意是否可以跳过
    function get adSkippableState():Boolean;

    // 创意在当前状态的剩余时间。
    // 当剩余时间未知，例如用户正在交互时，可以返回 -2。
    // 但若剩余时间始终是未知，则说明该属性不可用，应返回 -1。
    // 剩余时间的单位是秒。
    function get adRemainingTime():Number;

    // 创意在当前状态的时长。
    // 当时长未知，例如用户正在交互，可以返回 -2。
    // 但若时长始终未知，说明该属性不可用，应返回 -1。
    function get adDuration():Number;

    // 创意的音量。值在 [0, 1] 之间。
    // 若不提供音量信息，则返回 -1。
    function get adVolume():Number;

    // 设置创意的音量。应该根据入参限制在 [0, 1] 之间。
    // 若不提供音量控制，则该 setter 应留空。
    function set adVolume(value:Number):void;

    // VPAID 创意是可以附带伴随广告信息的。
    // 如果这个属性有值，则应为 VAST 结果中 <AdCompanions>
    // 的字符串表述。否则返回空字符串。
    function get adCompanions():String;

    // 如果 VPAID 创意自带了 Icon，则返回 true。
    // 其他情况都应返回 false。
    function get adIcons():Boolean;

    // ------------ 方法 --------------

    // 这里讨论的是兼容 VPAID 2.0 协议的广告，返回 "2.0"
    function handshakeVersion(playerVPAIDVersion:String):String;

    // 请确保在该方法调用完成后，发送 "AdLoaded" 事件。
    // 应在这个方法内准备好创意所需的所有素材，例如获取创意视频 Metadata
    // 并根据 width 和 height 属性，将其缩放，居中展示。
    // 如果有额外的信息需要和播放器交互，将使用最后一个参数传递。
    // 例如，在我和优酷的合作中，优酷会传递给我一个链接字符串作为
    // environmentVars 的值，用于发送额外的用户交互追踪打点。
    function initAd(width:Number, height:Number, viewMode:String,
        desiredBitrate:Number, creativeData:String="",
        environmentVars:String=""):void;

    // 当外部播放器缩放的时候，可能会调用该方法，通知创意需要缩放。
    // 这里的 width 和 height 理论上是外部播放器允许的最大创意尺寸。
    // 例如，你可以根据这个尺寸做等比缩放。但为保证创意展现完整，
    // 缩放结果不应该超出这个尺寸。
    // 当缩放完成后，需要发送 "AdSizeChange" 事件，并确保
    // 该事件发送后，播放器检查 adWidth 和 adHeight 属性时，
    // 创意能够正确返回新的尺寸信息。
    function resizeAd(width:Number, height:Number, viewMode:String):void;

    // 当 initAd 方法完成，并发出 "AdLoaded" 事件之后，
    // 播放器便随时可以调用该方法启动创意。
    // 在该方法内做完所有操作开始播放创意时，应发送 "AdStarted" 事件。
    // 播放器应该只调用一次该方法。
    function startAd():void;

    // 播放器调用该方法终止或取消创意播放。
    // 在该方法内应清理所有素材，并发送 "AdStopped" 事件。
    // 播放器应该只调用一次该方法。
    function stopAd():void;

    // 暂停创意播放。若当前创意可以被暂停，则应发送 "AdPaused" 事件。
    // 播放器在调用该方法后如果没有接到 "AdPaused" 事件，
    // 便可以认为创意暂停失败或者无法暂停。
    function pauseAd():void;

    // 恢复创意播放。应发送 "AdPlaying" 事件。
    // 如果播放器在调用该方法后没有接到 "AdPlaying" 事件，
    // 则可以认为创意无法恢复播放。
    function resumeAd():void;

    // 在播放器调用以下两个方法后，都应发送 "AdExpandedChange" 事件，
    // 并更新 adExpanded 状态。
    // 一般创意本身有可展开、收起的内容，播放器可以调用这两个方法。
    // 当然，如果播放器不调用，创意本身也是可以自己调用
    // 但只要状态改变，就要发送 "AdExpandedChange" 事件。
    // 如果播放器调用 collapseAd 方法，创意必须要收到最小尺寸。
    function expandAd():void;
    function collapseAd():void;

    // 跳过当前创意。如果播放器在调用该方法时，
    // adSkippableState 属性是 false，则可以忽略此次调用。
    // 若可以跳过，则应该在清理完所有素材之后，
    // 发送 "AdSkipped" 事件。
    function skipAd():void;
  }
}

VPAID Events

在 Interface 一节的注释里，提到了一些事件。这些事件都是 VPAID 事件。若配合 VAST 3 规范，这里有一些事件是重合的。

在 VPAID 2 规范的 6.2 一节里，给出了所有事件；规范的 3.3 节详细描述了每一个事件。下面同样完整列出并作注释。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
package {

  import flash.events.Event;

  public class VPAIDEvent extends Event {

    // 播放器调用 initAd 方法，创意处理完所有初始化工作后，发送该事件。
    // 若无法完成初始化过程，则应发送 "AdError" 事件。
    // 所有其他事件都应在该事件发送之后发送。
    public static const AdLoaded:String = "AdLoaded";

    // 播放器调用 startAd 方法，创意开始播放时发送该事件。
    public static const AdStarted:String = "AdStarted";

    // 播放器调用 stopAd 方法，创意清理完所有素材后，发送该事件。
    // 创意不能主动发送该事件，去通知播放器调用 stopAd 方法。
    // 该事件发送后，创意再接到任何消息，都不应发送其他事件。
    public static const AdStopped:String = "AdStopped";

    // 播放器调用 skipAd 方法，创意清理完所有素材后，发送该事件。
    // 若支持低版本 VPAID，在该事件发出后立即发送 "AdStopped" 事件。
    public static const AdSkipped:String = "AdSkipped";

    // 通知播放器创意的线性属性变更。
    public static const AdLinearChange:String = "AdLinearChange";

    // 播放器调用 resizeAd 方法，创意完成缩放操作，并更新
    // adWidth 和 adHeight 属性后，发送该事件。
    public static const AdSizeChange:String = "AdSizeChange";

    // 通知播放器创意的扩展状态变更。
    // 例如，某些交互面板展开，从不可用变为可用状态时，应发送该事件。
    // 创意尺寸变更与该事件无关，应发送 "AdSizeChange" 事件。
    public static const AdExpandedChange:String = "AdExpandedChange";

    // 通知播放器创意的可跳过状态变更。
    public static const AdSkippableStateChange:String = "AdSkippableStateChange";

    // 该事件在 VPAID 2.0 中已废弃。
    public static const AdRemainingTimeChange:String = "AdRemainingTimeChange";

    // 通知播放器创意时长变更，请确保该事件发送前已经更新创意的
    // adDuration 和 adRemainingTime 属性。
    public static const AdDurationChange:String = "AdDurationChange";

    // 通知播放器创意的音量变更。
    public static const AdVolumeChange:String = "AdVolumeChange";

    // 通知播放器创意的用户可见部分开始。
    // 例如，一个前贴创意，在 "AdStart" 的同时应该触发该事件；
    // 再如，一个默认状态为 Overlay 非线性创意，在浮层一出现就应该触发该事件。
    public static const AdImpression:String = "AdImpression";

    // 以下 5 个事件分别在创意中的视频开始播放、播放至 1/4 处、播放至一半、
    // 播放至 3/4 处、完成播放时发送。
    public static const AdVideoStart:String = "AdVideoStart";
    public static const AdVideoFirstQuartile:String = "AdVideoFirstQuartile";
    public static const AdVideoMidpoint:String = "AdVideoMidpoint";
    public static const AdVideoThirdQuartile:String = "AdVideoThirdQuartile";
    public static const AdVideoComplete:String = "AdVideoComplete";

    // 当用户点击创意内，会产生页面跳转的地方时，发送该事件。
    // 可以带上点击跳转链接地址、追踪 ID 和是否需要播放器来开启新窗口
    // 这 3 个信息作为 data 一并发送。
    public static const AdClickThru:String = "AdClickThru";

    // 用户和创意有交互操作，但不需要发生页面跳转时，发送该事件。
    // 可以带上追踪 ID 作为 data 一并发送。
    public static const AdInteraction:String = "AdInteraction";

    // 以下 3 个事件同 VAST 3 中的 acceptInvitation，collapse，close。
    // 仅用于通知播放器发送相应的打点统计。
    public static const AdUserAcceptInvitation:String = "AdUserAcceptInvitation";
    public static const AdUserMinimize:String = "AdUserMinimize";
    public static const AdUserClose:String = "AdUserClose";

    // 播放器调用 pauseAd 方法，暂停所有动画和声音后，发送该事件。
    public static const AdPaused:String = "AdPaused";

    // 播放器调用 resumeAd 方法，恢复创意播放后，发送该事件。
    public static const AdPlaying:String = "AdPlaying";

    // 该事件可用于和播放器联调。
    public static const AdLog:String = "AdLog";

    // 创意发生致命错误时发送。
    public static const AdError:String = "AdError";

    private var _data:Object;

    public function VPAIDEvent(type:String, data:Object=null, bubbles:Boolean=false, cancelable:Boolean=false) {
      super(type, bubbles, cancelable);
      _data = data;
    }

    public function get data():Object {
      return _data;
    }

    override public function clone():Event {
      return new VPAIDEvent(type, data, bubbles, cancelable);
    }
  }
}

Security

为确保播放器能够和创意交互，在创意内需要配置 Security.allowDomain("*")。如果你知道你的创意只被某几个服务商加载，那么也可以配置具体的域名。但除了单独使用 "*" 之外， Security.allowDomain 方法并不支持通配符，所以配置具体域名的可能性比较小。

Video in VPAID Creative

一个常见的 VPAID 创意由两部分组成：视频和交互元素。创意的时长一般为视频的时长。当发生交互时，最常见的方式为视频暂停，并触发 AdDurationChange 事件。

在 VPAID Events 一节中提到的多数事件都是由播放器调用创意的一个方法，创意再发送对应事件。但视频播放事件是创意主动发送的。因此，这里需要一个视频播放控件，方便管理视频播放进度。

下面描述的视频控件有以下功能：

加载、播放视频；
提供视频的尺寸、时长信息；
追踪视频的播放进度，在 VPAID 描述的 5 个视频进度点发送通知；
可选择使用视频长度或用户指定的时长发送上一点所述通知。

这个控件作为一个 ActionScript 3 Class 使用，这里定义其名称为 AdVideoPlayer。

首先，是加载和播放视频的功能。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
// 使用以下 3 个私有变量来播放视频
private var _video:Video;
private var _nc:NetConnection;
private var _ns:NetStream;

// 用于追踪 metadata 信息
private var _isMetaDataApplied:Boolean = false;

// 用于追踪视频是否开始播放
private var _isVideoStarted:Boolean = false;

// 其中，_video 是需要被创意展现的对象，
// 因此提供一个 getter
public function get video():Video {
  return _video;
}

// 使用 load 方法，传递一个视频地址，以加载视频
public function load(url:String):void {
  resetProgressTimer();
  _isVideoStarted = false;
  _isMetaDataApplied = false;

  _nc = new NetConnection();
  _nc.connect(null);
  _ns = new NetStream(_nc);
  _ns.client = this;
  _ns.play(updateTbUgcUrl(url));
  _ns.addEventListener(AsyncErrorEvent.ASYNC_ERROR, asyncErrorHandler);

  _video = new Video();
  _video.attachNetStream(_ns);

  // 准备就绪后将视频暂停。
  _ns.pause();
}

接下去提供一个可选的 duration 属性，表示强制时长，单位为秒。假如创意中配置了这个属性，则忽略视频文件本身的时长，所有视频进度事件的发送，以 duration 为基准进行计算。否则，以视频本身时长为基准来计算。在看代码之前，先解释一下为什么需要这个属性。例如，视频文件本身有 20s，需要投放在两个媒体。媒体 A 要求创意时长为 15s，媒体 B 则为 20s。那么可以和两个媒体约定，在创意的 initAd 方法里，通过最后一个参数，告知创意所需的时长。创意拿到时长后，新建一个 AdVideoPlayer 实例（假设实例名为 adVideoPlayer），并判断当前投放媒体。若为 A，则配置 adVideoPlayer.duartion = 15；若为 B，则不配置该属性，或者配置 adVideoPlayer.duartion=20。这样，当创意投放在媒体 A 时，视频的 5 个进度事件将分别于 0s，3.75s，7.5s，11.25s 和 15s 处发送；当创意投放在媒体 B 时，视频的 5 个进度事件将分别于 0s，5s，10s，15s 和 20s 处发送。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
private var _duration:Number = 0;
private var _videoDuration:Number = -1;

// 创意通过 duration 获取视频时长。
// 假如该属性没有设置过，则返回 _videoDuration。
// 初始化 AdVideoPlayer 时，默认给 _videoDuration
// 设置 -1，和 VPAID 中不支持获取 duration 对应。
public function get duration():Number {
  if (_duration > 0) {
    return _duration;
  }
  else {
    return _videoDuration;
  }
}

public function set duration(value:Number):void {
  if (value > 0) {
    _duration = value;
  }
}

public function get videoDuration():Number {
  return _videoDuration;
}

在上述 duration 的 getter 里，还用到了一个私有变量，_videoDuration。这个变量仅在 duration 没有被配置的情况下会用到，用于返回视频的真实时长。当然，即使在配置了 duration 之后，仍可以通过 videoDuration 这个 getter 来获取视频真实时长。

这就说到了视频长度的来源。在上述 load 方法里，配置了 _ns.client = this。Flash 会自动在当前类的实例上，调用以下方法。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
public static const METADATA_FETCHED:String = "AdMetaDataFetched";
private var _width:Number = 320;
private var _height:Number = 240;

public function onMetaData(info:Object):void {
  if (!_isMetaDataApplied) {
    // 防止此方法可能多次被调用，导致信息变更
    _isMetaDataApplied = true;

    _width = info.width;
    _height = info.height;

    // 从 metadata 更新视频时长。
    _videoDuration = Number(info.duration);

    // 此处必须覆盖 Video 实例的尺寸。
    // 否则视频将以默认 320x240 拉伸缩放展现。
    // 这也是默认给 _width 和 _height 设置这两个值的原因，
    // 当 metadata 获取失败，返回默认的尺寸。
    _video.width = _width;
    _video.height = _height;

    dispatchEvent(new Event(METADATA_FETCHED));
  }
}

创意需要在播放器调用其 initAd 方法之后，准备好所有的素材，并发送 adLoaded 事件。那么，视频 metadata 成功获取后，便是一个合适的时间来发送这个事件。所以在上述 onMetaData 方法末尾，发送一个 METADATA_FETCHED 事件，供创意选择监听。

此外，上述 _width 和 _height 是否暴露都无所谓，因为最初的 _video 实例已经是公开属性。

下面就要处理视频的播放进度了。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
// 每 500ms 检查一次播放进度。
private const TIMER_STEP:Number = 500;

// 视频的当前播放时间。
private var _time:Number;

// 视频播放进度追踪 Timer。
private var _progressTimer:Timer;

// 以下 4 个状态，外加上述 _isVideoStarted，
// 用于处理视频进度事件。
private var _isFirstQuartilePassed:Boolean = false;
private var _isMidpointPassed:Boolean = false;
private var _isThirdQuartilePassed:Boolean = false;
private var _isVideoPlayCompleted:Boolean = false;

// 初始化进度追踪 Timer。
private function resetProgressTimer():void {
  if (_progressTimer) {
    _progressTimer.reset();
  }
  else {
    _progressTimer = new Timer(TIMER_STEP);
    _progressTimer.addEventListener(TimerEvent.TIMER, trackProgress);
  }
}

private function trackProgress(event:TimerEvent):void {
  // 因为视频播放完成并不代表创意结束，可能是通过 _duration
  // 来计算进度事件发送时间点的。因此视频结束后，时间可能继续往前。
  if (_isVideoPlayCompleted) {
    _time += TIMER_STEP / 1000;
  }
  else {
    _time = _ns.time;
  }

  var percent:Number = Math.round(_time / this.duration * 100);

  if (percent >= 25 && !_isFirstQuartilePassed) {
    _isFirstQuartilePassed = true;
    dispatchEvent(new VPAIDEvent(VPAIDEvent.AdVideoFirstQuartile));
  }

  if (percent >= 50 && !_isMidpointPassed) {
    _isMidpointPassed = true;
    dispatchEvent(new VPAIDEvent(VPAIDEvent.AdVideoMidpoint));
  }

  if (percent >= 75 && !_isThirdQuartilePassed) {
    _isThirdQuartilePassed = true;
    dispatchEvent(new VPAIDEvent(VPAIDEvent.AdVideoThirdQuartile));
  }

  if (percent >= 100) {
    _progressTimer.stop();
    dispatchEvent(new VPAIDEvent(VPAIDEvent.AdVideoComplete));
  }
}

那么如何知道视频结束？回顾之前的 _ns.client = this 配置，Flash 会在视频播放时自动调用下述方法。

1
2
3
4
5
6
7
8
9
10
11
12
13
public function onPlayStatus(status:Object):void {
  if (status.code === "NetStream.Play.Complete") {

    // 若 duration 未曾配置，则在视频播放完成时发送相应事件。
    if (_duration === 0) {
      dispatchEvent(new VPAIDEvent(VPAIDEvent.AdVideoComplete));
      if (_progressTimer) _progressTimer.stop();
    }

    _time = _ns.time;
    _isVideoPlayCompleted = true;
  }
}

至此，我们还缺一个视频开始播放的事件。在上述 load 方法末尾，准备好视频之后，先暂停了视频的播放。这是为了让创意能够先发送 adLoaded 事件，待播放器调用 startAd 方法时，创意再告知播放控件可以开始播放视频（即下述 resume 方法）。此时，应发送视频开始播放事件。

下面的代码将这个步骤和播放、暂停整合在一起。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
public function pause():void {
  _ns.pause();
  _progressTimer.stop();
}

public function resume():void {
  onVideoStarted();
  _ns.resume();
  _progressTimer.start();
}

private function onVideoStarted():void {
  if (_isVideoStarted) return;
  _isVideoStarted = true;
  dispatchEvent(new VPAIDEvent(VPAIDEvent.AdVideoStart));
  _progressTimer.start();
}

最后，提供一个清除当前视频的方法，供创意在 stopAd 和 skipAd 时调用。

1
2
3
4
5
6
7
8
public function clean():void {
  resetProgressTimer();
  _video.attachNetStream(null);

  _ns.removeEventListener(AsyncErrorEvent.ASYNC_ERROR, asyncErrorHandler);
  _ns.close();
  _nc.close();
}

该类的完整代码，见 Sample 一节末尾提供的压缩包。

有一点需要指出，不一定所有的视频都能成功获取到 metadata，或者获取到的 metadata 可能不包含上述逻辑所需信息。因此，在使用该类的时候，建议配置 duration 属性，并在创意内部添加 metadata 超时逻辑，避免 AdLoaded 事件没有发出。

Sample

最后提供一个简易的 VPAID 2 创意示例。要运行这个示例，你需要有一个支持 VPAID 2 的播放器。为方便起见，这里我会使用一个非常简单的播放器。 A simple VPAID 2 compliant player

示例中的创意使用 Video in VPAID Creative 一节里的类来播放视频，实现了 Interface 一节所述的接口，并发送 VPAID Events 一节所述的部分事件。

整体流程大致描述为：

播放器加载并使用 getVPAID 方法获取 VPAID 创意；
监听 AdLoaded 事件并调用创意的 initAd 方法；
监听 AdStarted 事件并调用创意的 startAd 方法；
监听视频播放相关的事件和用户交互导致时长变更的相关事件；
当创意时长发生变化时，对倒计时做出正确地处理；
以视频播放完成事件作为创意结束标识，移除创意。

由于 VPAID 2 协议中没有明确播放器如何确认创意播放完成，可能是 adRemainingTime 为 0 时，也可能是 AdVideoComplete 事件发送时，或者可以和媒体约定其他时间点。但必须确定这个点，避免创意提供方无法完成某些数据打点，或者媒体播放器无法结束创意。

下面提供完整的代码，包括：

VPAID 2 创意主体（creative.fla，creative.as）；
包含 VPAID 2 简易播放器的预览工具（demo.fla，demo.as）；
VPAID 2 Interface，Events，Wrapper。