eyewonder flash instream framework specification

/80 EyeWonder, Inc. 233 Peachtree St. NE, Harris Tower, 5th Floor Atlanta, GA 30303 p. 678.891.2038 f. 678.891.2017

www.eyewonder.com

EyeWonder Flash Instream Framework Specification

Version 2.7

Copyright 2009: EyeWonder, Inc

EyeWonder Instream Framework Specification ‐ Version 2.7 – Last modified 4/21/2009


www.eyewonder.com

Introduction This documentation describes the EyeWonder instream framework, an implementation of the Universal

Instream Framework specification (UIF).

This document is broken into two parts:

Part I. Overview. Contains high‐level details of what the control layer is and how it works. The

intended audience is product managers, project managers, and engineering departments.

Part II. Technical Guide. Contains the lower‐level technical details. The intended audience is

engineering departments integrating the framework into their Flash video player.



www.eyewonder.com

Table of Contents Part I. Overview ‐ EyeWonder Instream Framework Specification

Description

License

Formats

Functional overview

Features

Requirements

Deliverables

Implementation Overview

Implementation Steps Part II. Technical Guide ‐ EyeWonder Instream Framework Specification

Build. Adding Eyewonder’s Instream Framework

Integrate. EyeWonder Instream Framework Code Integration

Formats (more details)

Ad Creative Specs

EyeWonder Instream Framework Methods

EyeWonder Instream Tags

Actionscript 3 / Actionscript 2 Differences Part III. VAST Functionality

Overview

VAST Components/Features

Usage guide

Appendix A. Code Samples Appendix B. Player Design Considerations Appendix C. Troubleshooting Appendix D. Frequently Asked Questions Appendix E. Ad Call Logic Flow Appendix F. Sample Ad Code Appendix G. AdManager Appendix H. How to Synch Audio/Video Between Player and Ad Appendix I. Tag parser and AdTagService Appendix J. Positioning and Scaling


www.eyewonder.com

Part I. Overview




www.eyewonder.com

Part I. Overview EyeWonder Instream Framework Specification

Description The EyeWonder Flash Player Instream Framework is an interactive in‐video advertising implementation

that allows an Adobe Flash‐based video player to load interactive advertisements (rich media ads) into

video players with minimal player changes. It appears like a “virtual player” to advertisements with the

intention of abstracting player‐specific code so that Instream Advertisers always see a consistent control

layer (API) regardless of what publisher they run on.

For those also aware of the industry‐standard Universal Instream Framework, this specification

implements a large subset. The Universal Instream Framework is an industry‐standard group of exposed

methods being developed that is independent of the control layer. This specification is for a specific

control layer being provided for players that don’t already have one. Additionally, the framework

supports any vendor that can follow simple directions to create ads.

The framework also supports the IAB standard for linear video ads know as VAST. VAST is a defined ad

tag XML structure that can be run across multiple publishers and networks. The framework supports

the standards of playing FLV files as linear instream ads and includes event and impression tracking,

clickthrus and wrapper tags for redirecting to other tags.

What is great about the framework is it allows publishers to seamlessly add support for a common ad

API that advertisers can utilize between publishers and still get much or all of the functionality that was

previously built custom by each publisher. As a result, media buys can extend across publishers and

network, driving more dollars to the interactive video advertising space.

License The Eyewonder Flash Player Instream Framework is released under the BSD open‐source license. Please

see license.txt for the license.



www.eyewonder.com

Formats There are four common instream linear and non‐linear formats described in this documentation. Three

are the expandable ticker, bar and bug formats which exist unobtrusively tucked away until the users

interact with them. Additionally, standard in‐player banners and synched units can also be loaded by the

framework, though that probably isn’t necessary.

Demos can be viewed at http://www.eyewonder.com/is2/

Please see “Part II. Formats” for more details on the unique EyeWonder instream formats.

Functional overview The EyeWonder Instream Framework should be built into the player by the publisher and hooked up to existing player methods and variables. An ad call uses the EyeWonder Instream Framework functionality to request an XML tag from a publisher ad server call. EyeWonder’s Framework will request a SWF from the location specified in the tag. Additional information from the tag such as width and height will be used to position the advertisement within the player, based on positioning information the player methods provide to the interface.

Requirements Flash CS3+

Flash 8+, Actionscript 2 / Actionscript 3 video player

Rich Media/XML capable ad server

Creative

Publisher Player

Publisher

Ad Server

EyeWonder Instream

Framework

Player methods and variables



www.eyewonder.com

Features

Quick, easy integration and top‐level technical support team with many years experience in

interactive digital advertising.

Interactive ad formats: Non‐linear ads (Ticker, Bar, Bug). Linear ads with clickthrus and

interactive linear ads (Pre/Post/Midroll, and Takeovers).

Ads can be created by any vendor and advertiser if they follow standards provided here.

Can be built on‐top or next to existing functionality without breaking already supported

advertising functionality.

Supports Actionscript 2 and Actionscript 3.

Ad serving: Fully compatible with ad servers that support XML (tested in but not limited to Dart

For Publishers, 24/7 Real Media, and Atlas).

Positioning: When using standard tags, positioning information in the tag can be used to

position ad within the video area.

Optionally supports proportional scaling.

Abstraction of player code so that advertisers can rely on a consistent API between publishers.

Examples are: play/pause, audio volume sync, tracking hooks for some interactions and video

playback.

Supports fullscreen.

Handles tag parsing automatically for standard tag formats. Modular tag parser that can be

extended by publisher. Supports dynamic “magic” tag format detection.

Timing: Built‐in timer functionality. Pre‐programmed delays between ticker/bug call and

ticker/bug display.

Supports “cartridges” that allow custom 3rd‐party, publisher and other vendor content that

follows the standards described in this document.



www.eyewonder.com

Standard trace messages that can be inspected through a special page on any browser with no

custom enhancements. Additionally, there are multiple levels of verbosity.

Player can control linear ad position, and linear ads can report back video remaining time.

Supports VAST non‐linear format and provides bandwidth detection (also can define own

bandwidth)

Ability to either pass in a tag URL or pass in tag text already retrieved.

Supports redirect tags

Supports leave‐behinds*

Supports companion ads*

* Leave‐behinds use player functionality for the leave‐behind button, and UIF supports

enabling/disabling the ad. Companion ads are usually player‐specific and are not directly supported by

Eyewonder but can be provided by the publisher. Please reach out to your technical contact in both

cases.



www.eyewonder.com

Deliverables The deliverables you will receive to assist with setting up instream for your video player:

Deployment guide

Copy of EyeWonder Instream Framework code

AS2

AS3

Flex – While Flex uses AS3, the Framework has some modifications to be used in video

players created in Flex’s MXML language.

Test ads

Sample player

Creative Specs

VAST workflow diagram

The following items can be provided on request:

Test grid

EyeWonder’s AdWonder Component used to build EyeWonder advertisements.

AdWonder Reporting access.

EyeWonder requires deliverables not be shared with any parties not authorized by EyeWonder.

EyeWonder can provide specific documentation for any 3rd‐parties upon request or pre‐approve in

specific instances.

Implementation Overview To implement the EyeWonder Instream Framework in your video player, please follow these steps. An

EyeWonder representative will be assisting you with this process:

1.Plan: Prepare by exchanging contacts and documentation. Plan the project out with EyeWonder and

assign team members.

2.Build: Build unmodified EyeWonder Instream Framework into your Adobe Flash 8+ based video player



www.eyewonder.com

3.Integrate: Hook the EyeWonder Instream Framework up to existing player methods.

4.Test: Set up a test environment and begin testing sample EyeWonder test tags.

5.Certify: Collaboratively agree upon a set of final ad specifications/requirements and discuss process

steps of future campaigns.

Implementation Steps

1. Plan

Recommendations:

Determine if player code will be provided to EyeWonder for integration, or will be integrated on the

publisher’s end. Sign relevant NDAs.

Publisher provides a dedicated engineer or team leader contact, a product manager contact, and

sales contact (if applicable) to work with EyeWonder during all phases.

Some documentation of internal player methods thatare relevant to integrating the EyeWonder

Framework.

Dedicated test environment for player.

Review implementation instructions and samples from EyeWonder.

EyeWonder and publisher will discuss mutual expectations and come up with a plan for future steps.

As part of this, EyeWonder will most likely provide a set of questions and additionally answer publisher

questions. Example topics to discuss are:

Player specifications

Existing player methods for advertising

Ad serving capabilities

User experience



www.eyewonder.com

Timeline

Productizing

Industry Standards

2. Build

The first technical stage in the process is to build the EyeWonder Instream Framework code into the

player and test with one of the EyeWonder test ads. This is separate from the “Integrate” step because

the only goal is to have the ad display in the player.

Please see the Build – Adding The EyeWonder Instream Framework section below for more information.

3. Integrate

The next stage is to fully integrate the EyeWonder Instream Framework and ensure it works seamlessly

with the publisher video player and that the video player can at the very minimum handle the

Expandable Bug, Expandable Ticker, and Full Player Window ad formats. This is also the point at which

design considerations such as ad serving functionality come into affect.

Please see the Integrate – EyeWonder Instream Framework Code Integration section below for more

information.

4. Test

In order for the publisher to be considered to have implemented the EyeWonder Instream Framework

correctly, the publisher should self‐test using EyeWonder test ads and test grid for each of the formats:

Expandable Bug, Expandable Ticker, and Full Player Window. The EyeWonder developer assisting the

publisher will aid the publisher in performing these tests.

5. Certify

At this point, EyeWonder will certify the publisher for instream. This stage will involve working with the

EyeWonder certification team to verify successful tests with internal QA and verify final ad specs and

requirements.


www.eyewonder.com

Part II. Technical Guide




www.eyewonder.com

Part II. Technical Guide EyeWonder Instream Framework Specification

Build – Adding Eyewonder’s Instream Framework

In order to build EyeWonder's ad functionality into the player, the publisher should follow these steps or

something similar:

Create a new layer labeled “EyeWonder” on the player's root timeline and make sure the layer exists throughout the timeline (on every frame).

Add an import statement (import com.eyewonder.instream.InstreamFramework within the Actions pane of that layer.

Modify player so that it has a System.security.allowDomain("*"); call on the first frame of the root timeline. Please see Adobe Livedocs for more information on the call. See Appendix C for assistance on how to only give certain domains access.

Implement appropriate EyeWonder Instream Framework functions within InstreamFramework. Please see Part II ‐ Player EyeWonder Instream Framework Methods for a complete description of the EyeWonder Instream Framework..

Create an instance of the InstreamFramework class for every ad placement within the player.



www.eyewonder.com

Please see Appendix A, Sample 1 for the code that should be placed within the “EyeWonder” layer.

Simple Test for Rudimentary Functionality

The best way to test general EyeWonder Instream Framework functionality is to initially set up a the ad

to display but nothing more initially. Although in this test, user‐experience won't be optimal, general

functionality of the EyeWonder Instream Framework will be verified.

The first step is to program a test tag into a publisher server or ad server. The next step is to modify the

video call within the player to launch a preroll ad.

If done correctly, the EyeWonder test ad should appear, and video should load, and ad should remain

for more than 15 seconds if interacted with.

Please provide EyeWonder a demonstration that this step is completed.

Please see Appendix A, Sample 2 for an example of how a preroll is hooked into the player for

rudimentary testing.

Integrate ‐ EyeWonder Instream Framework Code Integration EyeWonder or certified partners will assist with steps in integrating the EyeWonder Instream Framework with the video player's own EyeWonder Instream Framework:

Add a call for InstreamFramework’s member function loadAdURL with the URL for the Publisher ad server call that will load the XML tag. Hook the call up to be initiated where appropriate (such as certain button presses).

Handle the call to sOnEndAd event when ad completes and hook that up to begin video play. We also recommend handling sOnError (which is only called for fatal errors) to trap errors and continue video play.

If modifying timer methods, ensure that ad removal timers and other ad removal events are set up to call a registered cleanup callback within the InstreamFramework class. If ads are not given a chance to clean up prior to removal of the objects within Flash, certain end of ad features, such as end‐ad trackers, can’t be processed.

Please see Part II ‐ Player EyeWonder Instream Framework Methods for a complete description of the EyeWonder Instream Framework..



www.eyewonder.com

EyeWonder Instream Framework methods publisher will always have to modify

A class named com.eyewonder.InstreamFramework is provided for overriding methods provided in the base class InstreamFramework inherits from. Do not modify the base class directly unless absolutely necessary. Sample code is provided in InstreamFramework as a starting point. The following methods should be modified by the publisher for correct end user experience within player and for ads to function correctly:

setVideoState getVideoState audioVolume setter audioVolume getter

EyeWonder Instream Framework methods publisher may want to modify

Since InstreamFramework comes with standard implemenation of the following methods, they should be replaced if the standard implementation isn't adequate for this specific player.

customInit getAdMovieClip removeAdMovieClip timerStop timerStart timerPause timerCountdownCompleted remainingTime customPublisherTagHandler

EyeWonder Instream Framework properties set by ads

eventData

EyeWonder Instream Framework methods publisher may need to call

setPlayerInformation loadAdURL endAd resizeNotify

Events that need to be handled

sOnError



www.eyewonder.com

sOnEndAd sOnStartFixedroll sOnStartOverlay

Additional debugging methods

pubTrace

setDebugLevel

Events that can be dispatched to the framework by the player

The following events can be dispatched to the framework and listened to by advertisements.

audioVolumeChanged

disableAd

enableAd

adVidPlay

adVidPause

adVidSeek

Optional publisher‐side tracking methods

trackExpand

trackContract

trackLoad

trackClose

trackInteraction

trackClickthru

trackStartOfVideo

trackFirstQuartileOfVideo

trackMidOfVideo

trackThirdQuartileOfVideo

trackEndOfVideo

Deprecated methods

endAdNotify – handle sOnEndAd instead setAudioState – Use setAudioVolume instead getAudioState – Use getAudioVolume instead



www.eyewonder.com

loadAdXML – deprecated – use loadAdURL



www.eyewonder.com

Formats (more details)

This is just a brief overview. Please refer to the accompanying “Creative Specs ‐ detailed ‐ Flash.pdf”

document for more detailed information. Demos can be viewed at http://www.eyewonder.com/is2/

There are 5 ad formats currently supported: Linear video ad (interactive and non/interactive), expanding

ticker, expanding bug, non‐expanding ticker.

Linear video ad (Interactive and non‐interactive)

Types: Interactive and Non‐Interactive

When present, content video playback is deferred until the ad

completes. Examples: Preroll, postroll, midroll.

Interactive linear: Provides a visible but non‐obtrusive call‐to‐action that indicates the preroll is

interactive. When the creative is clicked, the creative enters interactive mode instead of triggering a

clickthru. The interactive mode can contain clickthrus and other interactive portions.

Ticker (Non‐linear)

Types: Expanding ticker, Non‐expanding ticker



www.eyewonder.com

The ticker provides an unobtrusive mouse‐over or clickable bar with a call to action. On mouse‐over or

click, the ticker will expand to cover the entire video area, and pause the video. On contract, ticker will

return to original dimensions. Tickers can either be placed horizontally (generally on the bottom), or

vertically as a bar (generally on the right).

Bug (Non‐linear)

Types: Expanding bug

Ad appears as a page‐tear triangle in a corner of the video (usually the the upper‐right corner). A click

will pause the video and expand the ad to take up entire player area. Ad can then be contracted back

into the original page‐tear and video resumed.

Ad Specs

The following are recommended ad specs. Consistency across publishers will make it easier for

Advertisers to extend their buys. Please refer to the “Creative Specs ‐ detailed ‐ Flash.pdf” document for

more details. If you did not receive this, please request it from EyeWonder.



www.eyewonder.com

The framework is size agnostic (4:3 ratio or 16:9 ratio, etc). Common video sizes are 320x240,

480x360, 400x300, 640x480, 720x480, and 480x270, 800x600 and 1280x720 (fullscreen). Please

contact EyeWonder for video size recommendations.

No specific references to _root or _level0 within ad SWF (must be relative to ad’s timeline).

Companion ad unit is optional. Companion ad unit functionality will be provided by publisher.

Frequency capping, rotation, and geo‐targeting can be provided by EyeWonder or by publisher.

No explicit calls to Stage.align within the creative.

Creatives must support both players that share audio settings with the creative, and players that

don’t. For players that do, audio controls must either be hidden, or synched with the player.

EyeWonder Instream Framework Methods All player EyeWonder Instream Framework methods required by EyeWonder code should be defined

through an instance of the InstreamFramework, which implements InstreamFramework. Some of these

methods will be provided as placeholders within InstreamFramework and need to be implemented by

the publisher through references to their own player methods and variables (EyeWonder will assist with

this process). Every attempt should be made to have these methods available. All methods that are

expected to return information or an object should return null if unimplemented.

These methods provide a well‐defined boundary of which functionalities should be provided by the

player and which functionalities should be provided by EyeWonder’s ad code.

The suggested method for implementing these methods is to have them act as an interface for instream

ads, and do little more than call existing methods within the player.

A class named com.eyewonder.InstreamFramework is provided for overriding methods provided in the base class InstreamFramework inherits from. Do not modify the base class directly unless absolutely necessary. Sample code is provided in InstreamFramework as a starting point.

Class Instantiation

One instance of InstreamFramework should be created for each ad viewport within the player. The only difference between instantiating in Actionscript 2 and Actionscript 3 is that the Actionscript 3



www.eyewonder.com

framework requires an extra parameter for the constructor, which will define the root context for the instance. For more differences between Actionscript 2 and Actionscript 3, please refer to “Actionscript 2 / Actionscript 3 differences” Actionscript 2 Sample import com.eyewonder.instream.InstreamFramework; System.security.allowDomain("*"); var ewad = new InstreamFramework(); ewad.addEventListener("sOnError",Delegate.create(this,onError)); ewad.addEventListener("sOnEndAd",Delegate.create(this,onEndAd)); // ….. later ewad.loadAdURL(adServerURL); Actionscript 3 Sample import flash.system.Security; import com.eyewonder.instream.InstreamFramework; Security.allowDomain("*"); var ewad = new InstreamFramework(root_mc); ewad.addEventListener("sOnError", onError); ewad.addEventListener("sOnEndAd", onEndAd); // ….. later ewad.loadAdURL(adServerURL); Warning: In AS3, root_mc must be on stage before loadAdURL is called

InstreamFramework Public Methods That Should Be Implemented By Publisher

customInit():void

This method is called at the end of the constructor of the IInstreamFramework to allow publishers to

initialize their own variables. Note: This method will be called when the object is created, before it is

first referenced. If you want to wait to do any custom initiation, then you can create a custom method

to call from your player code.

setVideoState(state:Number):void

Pause or resume the player’s main video (and associated audio) based on the parameter passed in.

0=unknown, 1= stopped, 2= playing, 3=paused. Successive calls to this method with the same value as

the current state should have no affect. That is, they should be ignored.



www.eyewonder.com

Note: In the next major framework release, for standards compliancy, there will be a property called

videoState instead.

get VideoState():Number

Request the player’s video state. 0=unknown, 1= stopped, 2= playing, 3=paused.

Tracking methods: The following methods will be called by the creative advertisement and should be

modified by the publisher to track these events.

Note: In the next major framework release, for standards compliancy, there will be a property called

videoState instead.

setAudioState(state:Number):void

Deprecated: Use the audioVolume property instead. In the next major framework release,

setAudioState will not exist. Currently, setAudioState sets the audioVolume property to either 0 or

100.

getAudioState():Number

Deprecated: Use the audioVolume property instead. In the next major framework release,

setAudioState will not exist. Currently, setAudioState sets the audioVolume property to either 0 or

100.

audioVolume:Number (read/write property) Allows the creative to set/read the player’s audio based on value passed in. (value can be ‐1 or in the range of 0 to 100, 0 being muted, and ‐1 meaning “ignore”). This can provide a way to link audio controls in the ad to audio controls in the player, or may be ignored by the publisher. Additionally, when the audio volume is changed in the player, the player should dispatch the “audioVolumeChanged” event to the framework. View this as a virtual audio control from the ad’s perspective. Please also see Appendix H for more details. The following are provided as a convenience method for designers and provide a subset of setVideoState and getVideoState functionality for most common uses. These are meant to provide convenience to designers without removing the possibility to add additional video states for set/getVideoState on future versions of the standard. playVideo():void pauseVideo():void isPlaying:Boolean (read only property) isPaused (read only property) isStopped (read only property)



www.eyewonder.com

remainingTime(remaining:Number, total:Number):void

Tell the player remaining time for the preroll ad, and also send the total amount of time available.

Although this can be called for non‐linear expanded ads as well, players most likely will ignore it.

The ad should preferably call every 100ms.

Note: We highly recommend not sending trace/debug messages or updating UI on this call for

performance and stability reasons. Instead, it is recommended to set a data variable on the player,

return immediately, and update UI on a separate interval.

InstreamFramework Tracking Methods That May Be Modified By Publisher

The following are tracking methods to allow the publisher to do their own method. Note that

EyeWonder advertisements already track to the AdWonder Reporting system. However, for other

vendors that don’t have their own tracking capabilities, these methods will allow the publisher to post

numbers to ensure the publisher is able to provide the best quality service to their clients.

trackExpand() : void

Called when the ticker/bug expands.

Note: In the next major framework release, for standards compliancy, this will instead be an event.

trackContract() : void

Called when the ticker/bug contracts.


trackLoad() : void

Called when an ad loads. Publishers can track their impression here. This should only be called once per

ad load, and not when an ad is re‐enabled after being disabled (e.g. don’t call a 2nd time when clicking

on a “leave‐behind” unit. Publishers should make additional effort to suppress multiple calls to make

sure they aren’t double‐tracking calls to this method. The EyeWonder Instream Framework contains

sample cold to suppress double calls.



www.eyewonder.com

Note that to prevent omissions to this call by the vendor making impression numbers inaccurate, this

may be reported by publisher as “ad load” instead of impression and impression can be tracked when

loadAdURL is called.


trackClose() : void

Close button pressed within ad. Note: This call will only track the user interaction. It won’t perform any

action and should generally be followed with a call to endAd by the advertisement.


trackInteraction() : void

Miscellaneous interaction. This event does not do any change of state, including extending of timer ( in

order to provide more granularity). To both track and extend the timer, use a call to handleInteraction

followed by a call to trackInteraction.


trackClickthru() : void

User clicked through on the ad. Warning: the publisher should add a 2 second timeout before processing

this to prevent popup blocking to interfere with the landing page being displayed.


trackStartOfVideo() : void

Called when any of the ad’s videos are at 0%. This is for ad video, and not for the player’s content video.

Some ads will not have video and will not call this method.


trackFirstQuartileOfVideo() : void

Called when any of the ad’s videos are at 25%. This is for ad video, and not for the player’s content

video. Some ads will not have video and will not call this method.


trackMidOfVideo() : void



www.eyewonder.com

Called when any of the ad’s videos reach 50%. This is for ad video, and not for the player’s content



trackThirdQuartileOfVideo() : void




trackEndOfVideo() : void




InstreamFramework Public Methods That May Be Modified By Publisher

getPlayerInformation():Object

Note: In the next major framework release, getPlayerInformation will instead be replaced by a property

that returns a class instance to the PlayerInformation class.

Should return an object containing the following member variables and will be called by the EyeWonder

Instream Framework on ad load, and should be placement‐specific. If there are video changes (such as

video resizes) that will change any of these values, we recommend calling endAd on currently loaded

ads to remove them. It is not required to set any values on the return object for any variables below

which are not changed. The member variables are:

videoRect:Rectangle – A Flash 8 Rectangle object with x, y, width, and height set with the

position of the player’s video or the preferred container for an ad. Make sure this value is always

correct, otherwise ads will not be positioned properly.

maxPrerollTimer:Number ‐ The max amount of time a preroll should exist before the

EyeWonder Instream Framework will forcefully remove it. The EyeWonder Instream Framework

will use a default of 30. This value doesn’t not apply to expandable leave‐in type ads and it is the

player’s responsibility to call endAd to remove those.



www.eyewonder.com

maxInteractionTimerPause:Number – The max amount of time the ad can pause the timer when

a user interacts with the ad. To protect the publisher player from malformed ads, it’s

recommended that this value be set to something reasonable. We don’t recommend this value

be set to anything less than 30 seconds otherwise the player may remove the ad before the user

is finished with it, but before another interaction is registered.The existing EyeWonder Instream

Framework implementation will use its own default of 120 seconds.

allowedTypes:Strings – What types of instream ads the player will allow. This is reserved for

future use.

backgroundRect:Rectangle –Used to position the background behind an ad. Defaults to

videoRect.

backgroundColor:Number – Define the color of the background behind an ad. Defaults to black

0x000000.

backgroundAlpha:Number – Define the alpha of the background behind an ad. Default is 100%.

Example:

public function getPlayerInformation() : Object { debugMessage(2,"In getPlayerInformation()."); // TODO: Publisher should modify the following code for any values that need to be changed var info = new Object(); info.videoRect = new Rectangle(myVideo_mc._x,myVideo_mc._y,myVideo_mc._width,myVideo_mc._height); info.maxPrerollTimer=15; info.maxInteractionTimerPause=30;

return info; }

getCompanionAdInformation():Object

This is reserved and should not be used at this time. The framework DOES NOT currently support

companion ads and future companion ad support will need to be more robust than originally

envisioned for this method. Should return an object containing the following member variables and will

be requested upon ad load by the EyeWonder Instream Framework:

type:Number ‐ A number representing the type of companion ad. 0=none, 1=in‐player, 2=on‐

page.



www.eyewonder.com

dimensions:Rectangle ‐ If an in‐player companion unit, a string representing where the

companion ad is located.

localConnectionUUID:String – For non in‐player synched units, this allows the publisher to

provide both ads with a localconnection unique ID that they can use to synch up.

companionAdObjectRef:MovieClip – For in‐player synched units, a reference to the other

synched ads. This allows for ad to ad communication (through function calls) without relying on

local connection.

getAdMovieClip(mcPos:Rectangle):MovieClip

Grab a reference to a movie clip where the ad can insert itself. This allows the player to have control

over the layering of movie clips. EyeWonder will have default code within this function that sets up the

movie clip. The publisher can also set up the movie clip within the Flash authoring tool, and then pass

back a reference to the movieclip.

Note: If the publisher modifies this method, they should make sure they create the movie clip on the

highest layer possible.

removeAdMovieClip():void

This private method is already implemented to hide the movie clip created for the ad. This method

doesn’t destroy the movie clip, only removes the content within it and then hides it. The publisher can

override the functionality and write their own. This function should only be called by the endAd method.

timerStop():void

Stop EyeWonder Instream Framework’s built‐in timer to hide a preroll ad after a certain amount of time.

This should only be called on initiation for leave‐in type ads (ticker and bug) and generally timerPause

should be called by preroll (full video) ads on user‐interaction. This method may be modified to call

publisher code.

Note: In the next major framework release, all timer functionality will be in a separate class instance

bound to a variable in the instream framework class.

timerStart(seconds:Number):void

Begin counting down towards ad removal. This method will be automatically called by the EyeWonder

Instream Framework prior to ad request with a low number (e.g. 10 seconds) to protect against slow‐

loading or malformed ads, however ads will generally stop the timer for leave‐in type ads (ticker,

expandable), or call timerReset for preroll ads, which will restart the timer with the default preroll timer

value provided by the publisher. This method may be modified to call publisher code.



www.eyewonder.com

Note:endAd will clear this timer.



timerPause(seconds:Number):void

Stop player’s built‐in timer for a certain number of seconds. This allows for a safer way to delay ad

removal without risking a complete tie‐up of the player by a malfunctioning ad and should only be called

by preroll ads and shouldn’t be called by leave‐in type ads. This method may be modified to call

publisher code.



timerCountdownCompleted():void

This method is set up by default to call endAd, and generally shouldn’t be modified. However, it is

possible that this method may be called by an external timer handler created by the publisher if the

other timer handlers are modified. This handler generally need not be modified even if modifying other

timer methods.



customPublisherTagHandler():void This method is allows publishers to access the XML object and format (EW or VAST) of the XML. This method method should be used to access any custom nodes in the XML that UIF did not parse and handle. Note: Access the XML object in AS3 using E4X. For AS2, the XML is a ForX Object (AS2 version of E4X).

Please refer to the ForX documentation on how to access the XML data using ForX).

endAdNotify():void

Deprecated: Handle the sOnEndAd event instead.

beginVideoOnlyFixedroll(creativeFormat:String, adURL:String, adDuration:Number,

impr3rdParty:String, click3rdParty:String): void

Deprecated: Superseded by VAST tag support. beginVideoOnlyFixedroll has never been used.



www.eyewonder.com

This method is called if the ad tag is for a video‐only preroll/postroll/midroll as opposed to a SWF, which isn’t supported by the EyeWonder framework. The publisher may optionally hook this up to their own functionality. Otherwise, the sOnError event is passed by default. The reason this method needs to exist is because some publishers need FLV‐only tags in some cases as a first step towards integration for existing buys. As such, they can hook this up to their own functionality, and that’s the only level of integration they need to do initially, and from that point on can accept EyeWonder FLV‐only tags.

InstreamFramework Public Methods Implemented Only By EyeWonder

loadAdURL(url:String, adFormat:String):void

loadAdURL instantiates the tagParser (refer to Appendix I) so the ad can be loaded in the framework. First parameter is the URL to the ad tag. The framework can parse and load Eyewonder and VAST formatted tags. Second optional parameter defines the type of tag the URL is pointed to. The default value is “unknown” which instructs the parser to attempt to define the tag based off of the structure. Other values for adFormat can include “EW” & “VAST”. This method is always implemented by EyeWonder and should not be overwritten. It requests an EyeWonder or VAST ad. The URL should be an ad server call that will request an EyeWonder or VAST ad tag file. The EyeWonder tag format is owned by EyeWonder and will be created using the EyeWonder’s AdWonder Componenttechnology. VAST tag format is part of the IAB standards and is created by other ad servers that can respond with the VAST tag format. This function is usually called after the play button is pressed. loadAd method will call the registered cleanup function for an ad placement if there is already an ad loaded within the movie clip. Note: if the new video dimensions are too small for the ad, the advertisement will not be displayed. Warning: In AS3, root_mc must be on stage before loadAdXML is called Note: This method will attempt to call getAdMovieClip and if undefined, will set up the movie clip itself. loadAdXML(url:String):void

LoadAdXML is deprecated. Change all loadAdXML references to loadAdURL instead! loadAdXML will be removed in a later version (most likely v3.x and higher)! resizeNotify():void This method should be called if the dimensions of the video player changed. getPlayerInformation will

be called to determine new video dimensions and position and the ad will be repositioned. Note: if

scaling is enabled, then the ad will be scaled and positioned. Otherwise, if scaling is disabled, the ad will

not be displayed if it is too large for the player.



www.eyewonder.com

Note: In the next major framework release, for standards compliancy, this will instead be an event

(named something completely different).

pubTrace(msg:Object) : void

This method allows publishers to send debug messages to the EyeWonder QA panel located at

http://cdn.eyewonder.com/100125/QA/Reporting/receiving.html. Note: Only one copy of this page on

the same computer session will receive messages at any one time.

setDebugLevel(level:Number) : void

This method allows the publisher to change the debug level (verbosity) of the player (default is 2). We

recommend generally setting this to 2, and only changing it to 0 during the development phase if the

publisher wishes to silence trace messages caused by the EyeWonder Instream Framework. Once in

production. We recommend using 2 when putting live into production so EyeWonder can more easily

troubleshoot issues. Settings: 0=silent, 1=quiet, 2=verbose

endAd():void

A method called by the ad and processed immediately when ad is done playing. This function should not be altered, and we recommend handling the sOnEndAd event to continue video playback after completion of an ad. If the player would prefer using a function instead for the handler, then endAdNotify should be modified instead. registerAdCleanupCallback(callbackFunc:Function):void

This function should be called by the ad with a callback function reference. When the player will remove the ad for whatever reason, it should call endAd. endAd will in turn call the registered callback function in order to let the ad do some of its own internal cleanup (including calling tracking pixels). The callback function should not be called if the ad has already called directly by the Player. This function should only be called by the ad and not be called by the Publisher Player. Note: In the next major framework release, for standards compliancy, this will instead be an event sent

into the ad, for the ad to handle.

getAPIVersion():String This method is provided generally so that an ad can request the EyeWonder Instream Framework version of the EyeWonder Instream interface, and should generally not be called by the publisher. In no circumstances should this method be modified.



www.eyewonder.com

timerReset(void):void

This method is only available to preroll ads on initial load in order to restart the timer, and should not be

called by the publisher.



handleInteraction(void):void

This method is only available to ads to report user interaction and automatically pauses the timer (via a

call to timerPause) with the default value.This event does not do any tracking ( in order to provide more

granularity). To both track and extend the timer, use a call to handleInteraction followed by a call to

trackInteraction.

reportInteraction(void):void

Deprecated due to naming confusion with trackInteraction. Use handleInteraction instead.

eventData: Object (read/write property)

Used when an event is sent that indicates there is data available. For example, an ad should call this

after it receives an adVidSeek event (see InstreamFramework Events section below). The reason data

isn’t passed directly with events is to prevent cross‐language issues. Current data members should

always be kept most‐up‐to‐date and can be overwritten with new data. Therefore, in the future,

anything that can’t be overwritten will have to be implemented as a stack variable on top of eventData.

getEventData returns an object with the following members (note: More may be added at a future

date):

adVidSeekPosition: Number of milliseconds to use as a starting point to position the “stream pointer” in

ad video (ad video position). There are two special values: ‐2 means current ad video position

(convenience), ‐1 means to seek to the end. 0 means to seek to the beginning.

adVidSeekOffset: Number of milliseconds from linearSeekPosition to increment/decrement “stream

pointer” in ad video (ad video position). A negative number means to seek backwards, and a positive

number means to seek forwards.

InstreamFramework Events



www.eyewonder.com

sOnStartRequestAd

This is called prior to requesting the EyeWonder ad SWF listed within the XML tag. adURL is the URL to

the XML file being requested (usually an ad‐server call URL).

Note: This event will be renamed in the next major release.

sOnStartFixedroll

This is called when a fixedroll (pre/post/midroll) ad loads. If this event is received, the player should NOT

start the video. Note that the framework will automatically call pause for a fixedroll, however it’s better

that this is handled by the player to prevent the video from momentarily starting.


sOnStartOverlay

This is called when an overlay (ticker/bug) ad loads. If this event is received, the player should start the

video.


sOnStartPlayAd

This is called after successfully parsing the EyeWonder ad tag file. The adUrl is the URL of the SWF that

will be requested and adWidth/adHeight are the width and height of the ad returned by the EyeWonder

tag file. This is a good location for the player to call timerStart.


sOnEndAd

This is called when the ad completes. This is the location where it is best to call a function that resumes

playback of the video being requested.


sOnError

This is called when the ad has a fatal error, such as in XML parsing. It is also recommend to resume video

playback if this function is called, since the ad will not continue.


audioVolumeChanged event



www.eyewonder.com

Dispatch this event to the framework when the user changes the video player’s audio slider.

Example code: ewAd.dispatchEvent("audioVolumeChanged");

Please also see appendix H for more details.

disableAd event

Dispatch this event to the framework when you need to hide the ad without destroying it. Usually used

by leave‐behinds.

enableAd event

Dispatch this event to the framework when you need to bring back a hidden ad without destroying it.

Usually used by leave‐behinds.

adVidPlay

Called when the player wants to signal a linear ad to play its video. Note that linear ads usually start the

video automatically, so this usually is only necessary after the player has previously called adVidPause.

Non‐linear ads should honor this event when appropriate.

adVidPause

Called when the player wants to signal a linear ad to pause its video. Non‐linear ads should honor this

event when appropriate.

adVidSeek

Called when the player wants to signal the ad to change the video position. After the ad receives the

adVidSeek event, it should call method eventData() to retrieve the new ad video position value. Non‐

linear ads should honor this event when appropriate.

InstreamFramework Class

InstreamFramework is a class that inherits from InstreamFrameworkBase and will be distributed to the

Publisher. This class should be imported by the player, and there should be one instance of the class for

each ad placement. That is, if 2 ads are shown at the same time, there should be two instances of the

class. A reference to the instance of InstreamFramework will be passed to the ad SWF when loaded.



www.eyewonder.com

EyeWonder will provide a skeleton of this class which has some methods implemented. The publisher

will need to fill in the skeleton with calls to the appropriate EyeWonder Instream Frameworks within

their player. EyeWonder will assist with this process.



www.eyewonder.com

EyeWonder Instream Tags EyeWonder instream tags look different than standard XML tags. It is highly recommended that ad URLs

be trafficked as opposed to physical tag files to allow for greatest flexibility.

Tags contain some standard variables:

adURL: variable which contains the path to the loader asset. Publishers should always make sure to leave query strings in‐tact and not modify the URL provided when passed to loadAdURL. For instance, loader.swf?dataURL=http://cdn4.eyewonder.com/path/to/data/file should not be modified to remove everything after the question mark. Note: This URL may contain escape sequences, so it may not be possible to paste the URL directly into the browser to test. XML tags map contain the value & (which should be converted automatically by Flash to &) and text tags may contain the value %26 in the URL.

adComment: Any comment can be placed here. It is advisable to surround the comment with <!—XML comment tags ‐‐>

adInstreamType: Type of instream ad. Possibilities are: instream, bug, ticker, full, fixedroll. Note that fixedroll means either pre‐, mid‐, or post‐roll.

adURLCreativeFormat: The type of creative in adURL. This is generally SWF, but can also be FLV for video prerolls (which needs to be handled by the player). Note: Future Silverlight option may exist.

adAlignHorizontal: Where within the video area (or container) should the ad beplaced horizontally? (left, center, right)

adAlignVertical: Where within the video area (or container) should the ad b placed horizontally? (top, middle, bottom)

adDataUrl: This is reserved for later use and will not be used at this time. Please use the SWF query string for any data values.

adClickTagNames: This is reserved for later use. It is recommended vendors put clickTag names but they will not be used at this time. Clicktags can be either hard‐coded into the SWF, passed on the SWF URL in adURL as a flashvar param, or requested from an external file specific to the rich media vendor.

adClickPrepend: This is reserved for later use. Variable where the site can add any publisher click prepend tokens (e.g. %c) for the ad server to process. Do not remove [clickthru] since it is a placeholder for a URL. If [clickthru] is removed, the clickthru will be broken.

adImpr3rdParty: Not used – reserved for beginVideoOnlyFixedroll. Note:

beginVideoOnlyFixedroll has been superseded by VAST.

adClick3rdparty: Not used – reserved for beginVideoOnlyFixedroll. Note: beginVideoOnlyFixedroll has been superseded by VAST.

adTagVersion: The version of the tag. This is an identifier used by EyeWonder’s Framework for legacy support to determine how to handle the values. For instance, the ad may not be displayed, or some values from the tag may be ignored or adjusted. For the current



www.eyewonder.com

implementation, make sure this is set to 2.0 as shown in the example below. v2.0 tags will work in the v2.5.1 and higher framework.

Fixedroll‐only (Pre‐/mid‐/post‐ roll) variables:

Note: fixed‐roll functionality is not currently provided within the Framework, however tag URLs can be

processed by the Framework and custom hooks can be created into the player.

Note: This functionality is superseded by VAST

1. adDuration: How long the ad should show for (generally the length of the pre‐/post‐/post‐

roll video within the clickable creative.

2. adImpr3rdParty: 3rd party impression tracker. *

3. adClick3rdparty: 3rd party click tracker*

* For EyeWonder ads, this will only be filled in when the adURLCreativeFormat is SWF. Otherwise, these

trackers will be called from within the SWF. However, whenever present, these values should be

processed.

www.eyewonder.com

Example XML tag:

<instreamAd> <adURL>http://www.example.net/path/to/file.swf?clickTag1=a&clickTag2=b</adURL> <adComment></adComment> <adInstreamType>ticker</adInstreamType>

<adURLCreativeFormat>SWF</adURLCreativeFormat>  <adDuration/>  <adImpr3rdParty/> <adClick3rdParty/>  

<adAlignHorizontal>center</adAlignHorizontal> <adAlignVertical>bottom</adAlignVertical> <adWidth>320</adWidth> <adHeight>240</adHeight> <adClickTagNames>clickTag1,clickTag2</adClickTagNames> <adDataURL>http://www.example.net/path/ file.xml</adDataURL>

<adClickPrepend>[clickthru]</adClickPrepend> <adTagVersion>2.0</adTagVersion>

</instreamAd>

Note 1: If ads are being rotated on the rich media vendor side, then either they need to all be compatible with the adWidth, adHeight, adAlignHorizontal, and adAlignVertical values from the tag, or the tag itself needs to be rotated on the vendor’s side. For that reason, it’s best if vendors provide tag URLs to host themselves rather than providing actual tags. Redirect Tags:

Redirect tags are used to redirect an ad server call to a new ad server. The redirect tags can be used in

situations where the initial ad server has no ads to return. Instead of returning nothing it can redirect

UIF to another ad server that can have an ad to deliver.

Below is an example of a redirect tag:

<instreamAd> <adURL>redirect</adURL> <redirectURL>http://cdn1.eyewonder.com/200125/752457/1069602/1069602_tag.xml?ewbust=[timestamp]</redirectURL> <adClickPrepend>[clickthru]</adClickPrepend> <adDataURL /> <adTagVersion>2.0</adTagVersion> <adAlignHorizontal />



www.eyewonder.com

<adAlignVertical /> <adWidth /> <adHeight /> <adComment /> <adInstreamType /> <adClickTagNames />

</instreamAd>

Actionscript 2 / Actionscript 3 Differences (For the v2.5.1 Framework) Constructor

Actionscript2: No parameters. _root is used as the level 0 movieclip

Actionscript3: Root is passed in as a parameter. It is used as the default display list parent of any

movieclip objects being placed within the player.

Encapsulation

Actionscript2: Class

Actionscript3: Package + Class

Events

Actionscript2: Include EventDispatcher and use object notation to pass parameters (such as object.target, object.type and other parameters).

Actionscript3: Inherit from EventDispatcher. Pass no extra parameters other than event type. Movieclip hierarchies

Actionscript2: Use two movieClip objects, one to be the parent and hold variables, and one to contain the ad SWF. Use createEmptyMovieClip.

Actionscript3: Create a class that inherits from movieclip called adContainerParent which contains a Loader object.

Vendor‐specific functionality

Actionscript2: Defined on ad’s parent’s movieclip (_adContainerParent_mc)

Actionscript3: Defined in vendorCartridge (aside from deprecated legacy ew_instreamEndAd and ew_instreamObject)

Publisher‐specific methods presented to vendor

Actionscript2: Defined on ad’s parent’s movieclip (_adContainerParent_mc)

Actionscript3: Defined in publisherCartridge handleVendorCartridgeInsert

Actionscript2: Not defined.

Actionscript3: Method to call when a cartridge is inserted into the API.



www.eyewonder.com

getAdMovieclip

Actionscript2: Returns what will be used as adContainerParent

Actionscript3: Returns what will be used as the parent of adContainerParent VASTVideoScreen

Actionscript2: VAST ads require the use of the VASTVideoScreen (Refer to Using VASTVideoScreen with AS2 Integrations in Part III).

Actionscript3: Is not required. Accessing XML Data

Actionscript2: XML data can be accessed using the ForX class. Please refer to the ForX documentation for more details.

Actionscript3: Uses the standard E4X implementation in AS3.



www.eyewonder.com

Part III. VAST Functionality



www.eyewonder.com

Part III. VAST Functionality

Overview Publishers have the option of using VAST functionality, which is turned on and supported by default. VAST tags can be rotated with other UIF‐supported tags and loadAdURL will handle the detection of the different tags automatically.

About IAB VAST VAST is a standard XML ad tag defined by the IAB for linear instream ads. Specifics to the VAST standard and example xml structure can be found on the IAB website. The IAB divided the VAST tag into two sections of required information and optional information. Instream framework only accepts the required information in the VAST xml tag as defined in the VAST documentation.

Non‐Linear IAB tags (VPAID) The non‐linear version of VAST is known as VPAID. As of the writing of this document the VPAID standard is not finalized by the IAB. Therefore, it is not supported in this release of Instream Framework. When details of VPAID have been finalized future versions will support the non‐linear standard.

VAST Components/Features VideoAdScreen Publishers have an option to use their own VideoScreen object instead of Eyewonder’s VideoScreen object. Publishers wanting to use their own VideoScreen should instantiate it inside InstreamFramework’s createVASTAd method or external VAST module, and pass it along as a parameter to the VASTModule method signature. All custom VideoScreen objects must implement Eyewonder’s IVideoAdScreenModule interface to ensure that it complies with the necessary properties and methods required for a successful implementation.

AdTagService AdTagService is a service class accessed by UIF for loading ad tags through its loadAdXMLURL method. When the load is complete, AdTagService notifies UIF so it can start parsing the data. Data is retrieved from the AdTagService’s adTagData property in AS3 and adTagDataE4X property in AS2.

Bandwidth/detection Currently, we rely on a 3rd‐party image files (JPEG, PNG, BMP & GIF ) to be provided, which is set to a specific file size. This URL should be publisher‐specific and located on the publisher’s server. However, it is also possible for a publisher to perform their own bandwidth detection and pass UIF the detected bandwidth. We do not currently use the FMS server as a form of bandwidth detection for streaming to increase reliability, because the FMS server being used for bandwidth detect would need to be the one for the exact mediafile being used, which is a chicken‐and‐egg problem since the code has not yet



www.eyewonder.com

detected bandwidth. Additionally, it is safer if the bandwidth is detected from a known source like the publisher’s hosting network. However, in the future, we may possibly use first streaming mediafile (and in AS3, could also request part of the video if only progressive exists) if we come up with a robust way to do this. setupURIArrays() Stores progressive and streaming media file URLs in arrays setupFileURI() Finds the appropriate video Mediafile based on bandwidth amount and preferred delivery method

UIF stores references to the publisher’s bandwidth detect URL ( _bandwidthDetectProgressiveURL) , preferred delivery method (_preferredDeliveryMethod) and qualityFirst (_qualityFirst). These variables are passed along to the VastModule which then stores them inside the VideoScreen. Bandwidth is detected by using the publisher’s bandwidth detect URL. Once bandwidth is detected, the VideoScreen object selects the appropriate MediaFile based on the bandwidth amount and the preferred delivery method. If _qualityFirst is set to true and the closestProgressive bitrate equals the closestStreaming bitrate, then the media file chosen is based on the preferred delivery method. If the closestProgressive bitrate is greater than the closest streaming bitrate, then the media file chosen is closest Progressive. Otherwise, if the closestStreaming bitrate is greater than the closest progressive bitrate, then the media file chosen is the closest streaming. If quality first is set to false, then the media file chosen is based upon the preferred delivery method. To allow a VAST video ad module to perform bandwidth detection and play the appropriate media file, publishers must pass additional parameters to UIF’s method signature. These variables include: bwDetectProgressiveURL, bwDetectStreamingServer, preferredDeliveryMethod, and qualityFirst.

Refer to Setting preferences and init variables.

How the Correct Media File is Selected VAST allows the advertiser to define multiple URLs to their video files including support for multiple bitrates and the delivery methods of streaming and progressive downloads. This allows for many different combinations for video files for the framework to select from. While the framework selects what bitrates to use from the bandwidth detection class (described above), the delivery method (streaming vs. progressive) is set using preferredDeliveryMethod and qualityFirst parameters. preferredDeliveryMethod :String The framework determines which bitrate to play based off of the bandwidth of the user (described above) and the qualitlyFirst parameter, mentioned below. However, the publisher defines their preferred delivery method as either progressive or streaming in the constructor of Instream Framework (below). Based on the preferred delivery method the framework will play the correct URL.



www.eyewonder.com

InstreamFramework( root_mc:MovieClip, bwDetectProgressiveURL:String = null, bwDetectStreamingServer = null, preferredDeliveryMethod:String = null, qualityFirst:Boolean = true);

The parameter preferredDeliveryMethod is defined as either “streaming” or “progressive”. In addition to preferredDeliveryMethod, qualityFirst also affects how the framework decides on which URL to play. When a VAST tag has both streaming and progressive URLs plus the publisher has set preferredDeliveryMethod to “streaming” and to qualityFirst to false, the framework will always use the streaming URLs for the video ad. The same is respectively true for defining progressive as the preferred delivery method. However, when qualityFirst is set to true, this situation no longer applies. If the VAST tag does not contain the preferred delivery method the framework plays the other delivery method. qualityFirst:Boolean If set to true, the framework will look at both of the bitrates of the progressive and streaming URLs and will use the highest quality video suitable for the given bandwidth regardless of the preferred delivery method. For example, the publisher defines streaming as the preferred method. However, the VAST tag contains URLs to progressive videos with higher bitrates. If the user of the player has a fast connection, the framework with select the highest quality video and play the progressive video for the ad. If the VAST tag has the same bitrates for both progressive and streaming, the framework will use the preferred delivery method in the player.

Scaling/Sizing of VAST Video Ad VAST video width/height The VAST tag defines the height and width of the video. However, the framework has different ways to scale and position the ad. Note: The video height and width are required by the VAST standard, however if the framework doesn’t find a width and height in the VAST tag then it will default to reading the height and width from the video metadata. If the metadata isn’t present, then sOnError is called. adContainerParent The adContainerParent is the holder for all the ads in the framework and is the same size and position of the player’s video screen. It gets the sizing and positioning values from the getPlayerInformation method in Instream Framework. The following variables can be defined by the publisher in the framework to help with scaling and positioning of VAST ads relative to the adContainerParent. _scaleVAST:Boolean If set to true the framework will scale the video proportionally to the adContainerParent. If the VAST video and adContainerParent aspect ratios are different the framework will letterbox the VAST video.



www.eyewonder.com

If set to false the VAST video will be sized according the height and width defined in the tag. _bandwidth:Number This is a public variable in InstreamFramework that allows the publisher to provide their own bandwidth value. positionVAST:Boolean If set to true the framework will center the VAST video ad in the adParentContainer. This only affects the video if it is not being scaled. If set to false the framework will position the VAST video ad to the upper right‐hand corner of adParentContainer.

Tracking Events The framework automatically tracks the events defined in the VAST tag, however the publisher might also what to independently track all of the VAST events. To do this InstreamFramework provides methods that are called by the VAST module when the event happens. Below is a list of all methods. The publisher needs to implement their own tracking code in the method.

trackLoad() Called when VAST module loads into InstreamFramework trackStartOfVideo() Called on the start of the video trackFirstQuartile() Called when 25% of the video passed trackMidOfVideo() Called when 50% of the video passed trackThirdQuartile() Called when 75% of the video passed trackEndOfVideo() Called when 100% of the video passed trackClickthru() Called when user clicks on the video ad

Tagparser See Tagparser Appendix I.

Usage guide

Using VASTVideoScreen with AS2 Integrations Since AS2 cannot dynamically build a video screen, any integration using AS2 VAST will need to import the VASTVideoScreen for ads to work correctly. Failure to use the VASTVideoScreen results in the player loading the VAST ad with sound but no video images.



www.eyewonder.com

The assets come in swc and fla format and there are two methods to import the VASTVideoScreen into your project. The fla method outlined below is the preferred method since it makes player sharing easier between developers.

FLA (preferred method):

1. Open the VASTVideoScreen FLA file 2. Drag a copy of both Library Items (VASTVideoPlayer and VASTVideo) from the resource FLA to

the library of your video player. 3. Publish the video player and test a VAST tag. 4. You should see the video and not just audio at this point.

SWC:

1. Navigate to: o Macintosh: /hardDrive/Users/”Your_User_Name”/Library/Application

Support/Adobe/Flash CSx/en/Configuration/Components/ o Windows: C:\Documents and Settings\”Your_User_Name”\Local Settings\Application

Data\Adobe\Flash CSx\en\Configuration\Components 2. Place the VASTVideoScreen.SWC file in the above directory. 3. Launch Flash. 4. Click Window/Components in the Flash interface to open the components window. 5. Click the options button for the components panel and select reload. This will cause Flash to

check for and load the SWC file that was added. 6. Expand the Standard Components section and you will find the VASTVideoScreen Component

there. 7. Drag the VASTVideoScreen Component to the Library of your Video Player. 8. Publish the video player and test a VAST tag. 9. You should see the video and not just audio at this point.

The VASTVideoScreen assets only needs to be present in your library, since the VAST module will dynamically attached the video screen to the stage at run‐time.

Setting preferences and init variables This section talks about setting the preferences and init variables of InstreamFramework. Below is the constructor of InstreamFramework.

InstreamFramework( root_mc:MovieClip, bwDetectProgressiveURL:String = null, bwDetectStreamingServer = null, preferredDeliveryMethod:String = null, qualityFirst:Boolean = true);

Streaming/Progressive preferences



www.eyewonder.com

preferredDeliveryMethod:String Lets publishers define “streaming” or “progressive” as the preferred method of delivery for the video file. If null the framework will default to “progressive” as the preferred method. qualityFirst:Boolean If set to true overrides the preferredDeliveryMethod if the other method has higher bitrate video files. Custom bandwidth detect URLs The framework detects the user’s band with by downloading a small swf and reading the bandwidth from that download. In order to work the framework needs a URL pointing the small swf. bwDetectProgressiveURL:String URL to a swf that will be used by the bandwidth detection class to determine the bandwidth. This can only be an image file (png, gif, or jpeg) and cannot be a swf. sOnError will be called if it is an unexpected type. bwDetectStreamingServer:String URL to a streaming server that will be used by the bandwidth detection class to determine the bandwidth. Not currently used.

Accessing Arbitrary VAST data within player UIF only parses and handles required attributes and values from a VAST ad tag. For example, inside the Wrapper element, VASTAdTagURL is required and is therefore parsed, but the CompanionAdTag is not required and is not parsed. However, publishers can access non‐required elements using the AdTagService’s adTagData property from inside UIF. adTagData returns the root node of the VAST ad tag. Access required and non‐required elements through standard E4X syntax in AS3 and ForX syntax in AS2 (see appendix for example). AS3 adTagData.Ad.Wrapper.CompanionAds.CompanionAdTag.URL; AS2 var wrapper:XMLNode = forx.getPathNode("VideoAdServingTemplate.Ad.Wrapper.CompanionAds"); CompanionAdTag = forx.getPathValue("CompanionAds.URL", wrapper); Refer to ForX documentation on how to access data in XML using ForX.



www.eyewonder.com

Using VAST as a runtime module There a two ways to run a VAST module. By default, the module comes built into UIF. However, it is possible for a publisher to create a standalone module and load that external swf directly into UIF. To load an external VAST module:

Start inside InstreamFrameworkBase createVASTAd() method.

Comment out _adContainer_mc and _adContainerParent_mc.addChild(_adContainer_mc).

Uncomment _adURL = _vastModule and _adContainerParent_mc.loadClip(_adURL).

Store the URL to the VAST module inside the _vastModule property.

UIF Limited to 10 VAST wrappers per ad call Wrappers have the potential to link to each other and therefore create an endless loop of VAST wrappers. Wrappers also call tracking impressions on loading and this has the potential for a denial of service attack on the two ad servers. To prevent this UIF will only allow 10 wrappers to be used per ad call. Upon reaching the 11th wrapper, UIF will call sOnError and play the content video. 10 wrappers should be enough to satisfy most publishers. If more wrappers are needed, the InstreamFrameworkBase.as will have to be modified.



www.eyewonder.com

Appendices



www.eyewonder.com

Appendix A. Code Samples

Sample 1 Build

Sample player actionscript code within the root timeline that loads the EyeWonder Instream Framework

object and optionally binds event handlers to it. This is from “Build ‐ Adding the EyeWonder Instream

Framework”.

import com.eyewonder.instream.InstreamFramework;

System.security.allowDomain("*"); // Note: * is Flash 8+ only var ewAd = new InstreamFramework(this /*Only for AS3*/, “http://www.example.com/url/to/bw.swf”, “http://www.example.com/url/to/bw.swf”, “progressive”, true); /* The following handlers are available (We recommend at least providing handlers for sOnEndAd and sOnError): */ // ewAd.addEventListener("sOnEndAd", this); // ewAd.addEventListener("sOnError", this); // ewAd.addEventListener("sOnStartRequestAd", this); // ewAd.addEventListener("sOnStartPlayAd", this); // function sOnEndAd(event:Object) {} // function sOnError(event:Object) {} // function sOnStartRequestAd (event:Object) {} // function sOnStartPlayAd (event:Object) {}

Sample 2 – Simple Test for Rudimentary Functionality Sample player actionscript code within the root timeline that loads the EyeWonder Instream Framework

object and optionally binds event handlers to it. This is from “Simple Test for Rudimentary

Functionality”.

For illustration, assume that a method playVideo is called every time a user requests a new video and

provides some UI functionality:

function playVideo(videoNum:Number) {

if (isVideoPlaying()) // Check whether a video is playing { stopVideo(); // Stop a currently playing video



www.eyewonder.com

disableButtons(); // Disable player buttons during preroll }

setCurrentVideo(videoNum); // Set the video based on user choice beginPlay(); // Start the video

}

In order to request a test ad, break playVideo into two functions, one of which are called after the ad

completes. Modify the initial function to request an ad. The following example assumes that ewAd is an

instance of InstreamFramework and that urlToTag contains an URL to the EyeWonder provided test tag

deliverable stored on a publisher server:

function playVideo(videoNum:Number) {

if (isVideoPlaying()) // Check whether a video is playing { stopVideo(); // Stop a currently playing video disableButtons(); // Disable player buttons during preroll } currentVideo = videoNum; // Back up chosen video num ewAd.loadAdURL(urlToTag, “EW”); // Begin preroll add

}

var currentVideo:Number;

function playContinue() { setCurrentVideo(currentVideo);// Set the video based on user choice beginPlay(); // Start the video }

ewAd.addEventListener("sOnEndAd", playContinue); // Handle the end of ad



www.eyewonder.com

Appendix B. Player Design Considerations The following recommendations for publishers are provided in order to ensure that integration is easy

to roll out and maintain. Although most publisher players are already built, future redesigns should put

the following into consideration:

Modularity One of the most important design considerations is to make the player developed in a modular fashion.

What this means is specifically UI and functional code is separated as much as possible and that

functionality which the EyeWonder Instream Framework will interact with is abstracted in a way that

will work as seamlessly as possible.Furthermore, code that is better abstracted is usually easier to

debug, maintain, and can allow publishers to easily remove chunks of proprietary code (for instance

skinning code) before sending code snippets to EyeWonder to help troubleshoot integration issues

(Note: code snippets aren’t required for integration).

For instance, instead of having to add EyeWonder Instream Framework code within setVideoState to

modify the UI on pause/unpause of video (e.g. toggle play button’s appearance), it makes much more

sense to abstract the code to update to play/pause the video and update the UI within a method

provided by the player, and have setVideoState only call that method.

Not Modular

The following code has too much redundancy.

Player code

bPlay_btn.onRelease = function() { // Toggle if (!_isVideo) return;

_isPaused = !_isPaused;

if (_isPaused) {

bPauseImg_mc._visible = true; bPlayImg_mc._visible = false; doPause();

} else {



www.eyewonder.com

bPauseImg_mc._visible = false; bPlayImg_mc._visible = true; doPlay(); } }

Publisher‐modified EyeWonder Instream Framework code

public function setVideoState(state : Number):void /* 1= stopped, 2=playing, 3=paused */ { if (_root._isVideo) return;

if (state == 3 || state == 1) { _root.bPauseImg_mc._visible = true; _root.bPlayImg_mc._visible = false; _root.doPause(); } else { _root.bPauseImg_mc._visible = false; _root.bPlayImg_mc._visible = true; _root.doPlay(); } }

Modular

This code is a lot easier to read and makes integration a lot easier. Additionally, providing snippets for

troubleshooting purposes usually doesn’t expose too much proprietary code.

Player code

bPlay_btn.onRelease = function() { // Toggle if (!_isVideo) return;

_isPaused = !_isPaused;

if (_isPaused) {



www.eyewonder.com

pauseVideo(); } else {

playVideo(); }

}

Publisher modified EyeWonder Instream Framework code

public function setVideoState(state : Number):void /* 1= stopped, 2=playing, 3=paused */ { if (_root._isVideo) return;

if (state == 3 || state == 1) { pauseVideo(); } else { playVideo(); } }

Call methods

One consideration is how ads are going to be called. Let’s assume, so we handle the most complex case,

that a particular player has feeds, so the question is how will ads be programmed into the feeds. One

common solution is to set up an ad server instance, and then use that ad server placement to rotate

tags. Then a custom node can be placed in the feed to identify the ad for that particular video.

Since videos can be set up within the player in different zones or content types, such as “Sports”,

“Music”, etc the same thing can be done on the ad server – e.g. a different placement/zone within the

ad server.



www.eyewonder.com

Fullscreen

Make sure when implementing fullscreen that you take into consideration whether the ad should be

scaled or not. Preferably, the ad should not be scaled, but instead should be positioned within the video

area.

Menus

Make sure no player menus obscure the advertisement.

Testing/Debugging We suggest designing the player so it can be tested/debugged within the Flash environment. Certain

functionality may have to be disabled, however the general functionality to show videos and instream

ads will still function. This allows the player to be single‐stepped through to find the cause of a particular

issue.

Another thing to look into is making sure the player works when the Fiddler HTTP proxy tool is open.

Fiddler is a useful tool for debugging connection issues.

It’s always the best idea when testing to build the player with debugging information. More details are

provided here:

http://livedocs.adobe.com/flash/9.0/UsingFlash/help.html?content=WS3e7c64e37a1d85e1e229110db3

8dec34‐7fbf.html



www.eyewonder.com

Finally, we recommend adding trace messages to methods within the player, along with sending them

out through localconnection using the EW EyeWonder Instream Framework method pubTrace which is

described in Part II ‐ Player EyeWonder Instream Framework Methods.

Appendix C. Troubleshooting

The following are known potential issues the video player engineers should be aware of:

Issue one ‐ Player ID/Name attribute:

The player name and ID attribute should be set to what would be a valid Javascript variable name,

otherwise Javascript errors will occur in Internet Explorer when EyeWonder ads are loaded.

Symptoms:

Javascript error with message: ’sample’ is undefined and the Internet Explorer Script Debugger will show

code like this line: __flash__addCallback(sample-playlist-player, "ew_isAvailable");

Cause:

This is due to the way Flash implements External Interface to reference the object ID through the

window object, and External Interface functionality is used by EyeWonder ads.

Solution:

If the object tag has the following code <object id="sample-playlist-player " … then change it to

<object id="sample-playlist-player " … (elipses signify omitted code)

Issue two–3rd Party Tracker request failing:

Symptoms:

Requests for 3rd party tracker from creative doesn’t complete. An HTTP proxy shows 404 errors

containing crossdomain.xml or the crossdomain.xml file on the tracking server doesn’t have the correct

domains listed. This will also result in cookies not being dropped.

Cause:

If there’s a requirement to write out a 3rd party tracker of any type, whether from the publisher or an

agency, the server for that 3rd party tracker will need to have a crossdomain.xml file on the root of the



www.eyewonder.com

domain the tracker is requested from that gives access to the player’s domain, and potentially

eyewonder.com domains in some cases. This is because in most cases, due to Flash player script access

restrictions and lack of a JS tag, EyeWonder code will only be able to write out the tracker from within

Flash.

http://kb.adobe.com/selfservice/viewContent.do?externalId=tn_14213&sliceId=2

Solution:

Set up a crossdomain.xml file containing the URLs of all players. The most simple crossdomain.xml looks

like the following, and will make sense for networks, however to improve security, it may be necessary

to narrow down the domains further:

<cross-domain-policy>

<allow-access-from domain="*" secure="false"/>

</cross-domain-policy>

This is even more secure:

<cross-domain-policy>

<allow-access-from domain="*.eyewonder.com" secure="false"/>

<allow-access-from domain="*.eyewonderlabs.com" secure="false"/>

</cross-domain-policy>

To pin down security even further, the most common EyeWonder domains are:

eyewonder.com

ss.eyewonder.com

cdn.eyewonder.com

cdns.eyewonder.com

cdn1.eyewonder.com

cdn2.eyewonder.com

cdn4.eyewonder.com



www.eyewonder.com

apps.eyewonderlabs.com

www.eyewonderlabs.com

projects.eyewonder.com

If narrowing down the domains, please remember that the domains for the players will need to be in

crossdomain.xml.

Domains for other 3rd party and 4th party vendors will need to be added, so we recommend keeping this

list in an external database called by the player.

Additionally, there were security changes in Flash Player 9.0.115.0 that require crossdomain.xml

response headers have "Content‐type:text/xml". Additionally, there could be other changes that may

affect anything but the most basic crossdomain.xml file. Please see:

http://www.adobe.com/devnet/flashplayer/articles/fplayer9_security.html for more information.

Issue three–Main video does not pause/play as expected when creative interacted

with:

System.security.allowDomain must be used in the root timeline of the player in order to ensure the

EyeWonder Instream Framework has access to the elements necessary in order pause/play the video

player.

Symptoms:

When test creative known to work in most cases is loaded in the player, it does not pause the video

when ad expands.

Cause:

If the code in the EyeWonder Instream Framework looks correct, then this could be because

System.security.allowDomain wasn’t used on the root of the player.

Solution:

Add EyeWonder domains to a System.security.allowDomain. As of Flash version 8, either an insecure *

(wildcard) entry can be used, or each domain has to be explicitly entered in and wildcards cannot be

used in place of subdomains. More information available at:



www.eyewonder.com

http://livedocs.adobe.com/flash/8/main/wwhelp/wwhimpl/common/html/wwhelp.htm?context=LiveD

ocs_Parts&file=00002647.html

Example:

System.security.allowDomain("eyewonder.com","ss.eyewonder.com",

"cdn.eyewonder.com", "cdns.eyewonder.com", "cdn1.eyewonder.com",

"cdn2.eyewonder.com", "cdn4.eyewonder.com", "apps.eyewonderlabs.com",

"www.eyewonderlabs.com", "projects.eyewonder.com");

See issue two for a campaign list.

Domains for other 3rd party and 4th party vendors will need to be added, so we recommend keeping this

list in an external database called by the player.

Issue four–Successive ad calls have issues:

If clickthrus on successive ad calls are broken with video malfunctions or other issues, there are some

things to look into.

Symptoms:

If the first call using the EyeWonder Instream Framework works and successive calls don’t.

Cause:

There are two potential causes for this:

An EyeWonder Instream Framework older than version than 1.2.3

Creating a new instance of the EyeWonder Instream Framework for each video call.

Failing to call endAd and forecefully removing the ad’s movie clip instead of letting the

Framework unload it.

Solution:

There should only be one instance of the EyeWonder Instream Framework for the player, and calls to

loadAdURL will automatically unload the previous ad. Since only one copy of an ad can be open at any

one time, creating a new InstreamFramework instance (e.g. ewAd) each time an ad is loaded will cause

problems.



www.eyewonder.com

Issue five–Simultaneous ad calls have issues:

If multiple EyeWonder advertisements are loaded simultaneously, ads will not display.

Symptoms:

Two ads are loaded into the player, and they appear to interfere with each other. For instance, videos

from one ad appears to play in another, or clickthrus in one ad are being called from another.

Cause:

Multiple ads created with the AdWonder Component cannot be loaded into the same player

simultaneously. They can only be loaded sequentially using the same InstreamFramework instance (e.g.

ewAd). This is due to a limitation in the component.

Solution:

For EyeWonder ads, load only one ad at a time. If an in‐flash companion unit is needed, then either it

will needed to be built into the overlay for the instream unit, or will need to be built without the

AdWonder Component (but still can be trafficked through EyeWodner)

Issue six–Alignment issues:

Symptoms:

Player content may go out of alignment (e.g. no longer be centered in the player, or have the center of

the content appear on the top/left of the player instead of the center. In rare cases, content may

disappear completely, yet still be called/loaded. In some cases, the advertisement will still be positioned

properly. This issue may manifest all the time, or only when the player is fullscreen or loaded outside of

HTML, or for certain Flash player versions.

Cause:

One potential cause is that advertisements are setting Stage.align. because it can interfere with

alignment settings within the player, since Stage.align applies to all content within the player. E.g. the

following should not be called from within an advertisement:

Stage.align = "TL";

Solution:



www.eyewonder.com

Remove all calls to Stage.align within the creative FLA. EyeWonder’s AdWonder Componentdoesn’t call

Stage.align for instream advertisements.

Issue seven–Ad clickthrough popup blocking in Firefox with Flash plugin 9.0.115.0:

There were changes in the Flash plugin 9.0.115.0 that caused Firefox’s popup blocker to block clickthrus

that weren’t blocked in previous versions of the Flash plugin. This issue has not been reproduced on the

Macintosh and we have only seen it on Windows. It has been reported to Adobe.

Symptoms:

On Windows, Firefox will block popups for instream ads loaded in your player when you are using the

Flash plugin version 9.0.115.0 and if you then uninstall the plugin and downgrade to 9.0.47.0, you no

longer see the issue. You can verify this by either looking at the solution and checking whether or not

you have the necessary changes to fix the issue, or by following the instructions below:

1) Uninstalling your Flash plugin (using Add/Remove programs on Windows).

2) Verify the Flash plugin is properly uninstalled by trying to go to a page containing Flash and

verifying that it prompts you to install the plugin (do not install it)

3) Grab 9.0.47.0 from the Flash player archive

http://kb.adobe.com/selfservice/viewContent.do?externalId=tn_14266&sliceId=2

4) Install 9.0.47.0

5) Verify your Flash version with http://www.macromedia.com/software/flash/about/

6) Test the page that was having popups blocked and popups shouldn’t be blocked in 9.0.47.0 if

the issue is related

Note: This issue so far is only reproducible when the HTML that loads the player is served online. Local

versions of HTML don’t have this issue.

Cause:

It appears that this is caused by wmode set to window on Firefox/PC for Flash 9.0.115.0.

<embed wmode="window" src=… We have not received details from Adobe on the exact cause, however we have isolated the issue to be

the affect of some change between 9.0.47.0 and 9.0.115.0.



www.eyewonder.com

Solution:

You will need to modify your object / embed tag that loads in the Flash player to set the wmode to

opaque or transparent when the Flash plugin is less than 9.0.115.0. If the issue continues to happen, try

restarting the browser and clearing your cache. We suggest you do not set the object / embed tag to

wmode for Flash plugin less than 9.0.115.0 (see Note 1 below for more details).

<embed wmode="opaque" src=…

Note 1: fullscreen functionality will only work with wmode set to window for Flash plugins less than

version 9.0.115.0. Therefore, we suggest Flash version detection and to conditionally set wmode to

window for anything lower than 9.0.115.0 and opaque for anything 9.0.115.0 or greater. Sample flash

version detection code is provided in the included file “EyeWonder Flash Instream Control Layer

Specification_flashversion.js”.fd_wmodeOpaque will be true if wmode should be set to opaque.

Note 2: Using a wmode of “opaque” can slightly increase cpu load and slightly decrease performance

of the video player. However, with good hardware acceleration as is common on most newer systems,

the affects will be limited.

Issue eight– Ad does not display:

If the ad does not display, there could be many causes. The most common are listed below.

Cause:

Common causes:

System.security.allowDomain not set up properly in player.

Ad is too large for the player’s video area.

Call to loadAdURL is not being set up properly.

getPlayerInformation is returning invalid dimensions for the video area.

Ad is larger than video area. The framework will not display it in this case. Things to also look for:

Check for errors, and pass information about those errors to EyeWonder. Often, the cause can be determined by watching debugging output on http://cdn.eyewonder.com/100125/QA/Reporting/receiving.html Issue nine– Actionscript 3 specific issues:

In AS3, the movieclip passed in as the constructor to InstreamFramework needs to be visible on stage before loadAdURL is called and from that point forward.



www.eyewonder.com

Issue ten– Can’t hear the ad for VAST, but cannot see the ad:

Symptoms:

This issue is seen with AS2 VAST Linear Ads.

Cause:

Actionscript 2 does not allow dynamic building of video screens. Therefore, the VAST module needs

a video screen to be present on the stage or in the library.

Solution:

Import in the VASTVideoScreen asset into the player fla. The asset comes in swc and fla format and there are two methods to import the VASTVideoScreen into your project. The fla method outlined below is the preferred method since it makes player sharing easier between developers.

FLA (preferred method):

5. Open the VASTVideoScreen FLA file 6. Drag a copy of both Library Items (VASTVideoPlayer and VASTVideo) from the resource FLA

to the library of your video player. 7. Publish the video player and test a VAST tag. 8. You should see the video and not just audio at this point.

SWC:

10. Navigate to: o Macintosh: /hardDrive/Users/”Your_User_Name”/Library/Application

Support/Adobe/Flash CSx/en/Configuration/Components/ o Windows: C:\Documents and Settings\”Your_User_Name”\Local

Settings\Application Data\Adobe\Flash CSx\en\Configuration\Components 11. Place the VASTVideoScreen.SWC file in the above directory. 12. Launch Flash. 13. Click Window/Components in the Flash interface to open the components window. 14. Click the options button for the components panel and select reload. This will cause Flash to

check for and load the SWC file that was added. 15. Expand the Standard Components section and you will find the VASTVideoScreen

Component there. 16. Drag the VASTVideoScreen Component to the Library of your Video Player. 17. Publish the video player and test a VAST tag. 18. You should see the video and not just audio at this point.



www.eyewonder.com

The VASTVideoScreen assets only needs to be present in your library, since the VAST module will dynamically attached the video screen to the stage at run‐time.



www.eyewonder.com

Appendix D. Frequently Asked Questions

We are a publisher/network with multiple Flash player sizes. Are ads resizable? If not,

how do we use your ads on multiple player sizes?

Since Flash has improved when it comes to quality of scaling, we now include scaling code turned on by default. This was new for Framework version 2.5.5 and up. There is now a variable called _scaleEWFramework, which can be set to false to turn off scaling. For VAST, there is a separate variable described in Section III above. However, we recommend to include scaling and leave it turned on. In either case, when scaling is enabled or not, there is also positioning code that will position the creative inside the ad container. More details are provided in Appendix J.

We would like to do full‐screen ads.

Although creating separate ad placements for full‐screen will allow for the best use of the space by creative, it’s also possible to scale up creatives when going fullscreen. That is the most common scenario at this point. resizeNotify should be called if the video dimensions and position changes, including going full screen.

How do we create synched companion units?

There are two types of companion units. In‐Flash and In‐page. In‐page (standard banner) companion units should be programmed by the ad server to show up in unison, and if no companion unit is available for the ad. Due to technical limitations, in‐Flash companion units built by Eyewonder tools either need to be built by creating one large creative that overlays the entire player and has “windows” where controls are, or use a custom loader provided by Eyewonder. Note that this isn’t abnormal but Eyewonder will need to know up front. This doesn’t apply for ads built using 3rd party tools.

How do we do research study surveys (e.g. Insight Express, Comscore, etc)?

There are three methods for doing research studies we know of:

If an in‐page (standard banner) companion unit is available, then that unit can be given the research tag, and be synched up with the instream unit.

If “allowscriptaccess” is set to “always” on the player’s OBJECT and EMBED tag, then the instream object can write out the research tag within an absolutely positioned 1x1 pixel iframe on interaction.



www.eyewonder.com

The research tag can be programmed by the publisher, piggybacked in ROS placements, and a cookie can be set by the instream creative on interaction, without which the ROS placement’s research survey won’t

Does EyeWonder support leave‐behind units?

Some publishers have small leave‐behind units/buttons that the ads disappear to when closed. We support leave‐behind units although these are usually custom implementations and will require additional development time and additional time to build the creative for a campaign

How do we do third party tracking?

EyeWonder can embed 3rd party tracking calls into the creative or the publisher can provide methods to call after certain events, however this will require additional development time and additional time to build the creative for a campaign. Keep in mind EyeWonder has analogues of most tracking publishers would request that agencies/clients already have access to and publisher can also be provided access to. It’s preferable that if the publisher would like to have their own tracking, they adhere to no more than the following tracking method calls:

Begin ad video. Should be called whenever a user‐initiated ad video starts (or reaches 1%). If publisher wishes to track auto‐initiated video as well, we suggest separate calls should be provided for auto‐initiated video.

50% ad video. Should be called whenever a user‐initiated ad video reaches 50%. If publisher wishes to track auto‐initiated video as well, we suggest separate calls should be provided for auto‐initiated video.

End ad video. Should be called whenever a user‐initiated ad video reaches 100%. If publisher wishes to track auto‐initiated video as well, we suggest separate calls should be provided for auto‐initiated video.

Publisher impression tracker.

Publisher expand/contract trackers for ticker/bug. We recommend that the publisher have a test player for ensuring all events are called as expected. EyeWonder can provide reporting access or a copy of reporting data for comparison.

The EyeWonder Instream Framework is set up and working properly except the ad is

positioned on the top/left. How do I set up the ad to be positioned somewhere else?

Provide the video dimensions by setting the member variables on the info object in the framework method getPlayerInformation. You can either set the values explicitly or set the info object using values from variables or methods you defined on __root. Please let me know if you have any questions.

What do you recommend for specifications, creative guidelines? What length videos

should we use and how many placements should we create?



www.eyewonder.com

This discussion is out of the scope of the document, however we have a list of standard best practices we can go over with the publisher.



www.eyewonder.com

Appendix E. Ad Call Logic Flow

Refer to UIF‐VAST Workflow.docx for workflow diagram for the VAST module. Steps in Red are Ticker/Bug only. Steps in Blue are “Full video” (preroll) only.

Step Publisher Player EyeWonder Instream Framework Ad

1 User clicks play on player to request main video. Publisher player begins playing video.

2 Player begins playing user-requested content video.

3 Player makes request to ad server to retrieve tag URL. This will usually be an ad server call that the URL for the XML tag hosted by the vendor, so that the Publisher has the ability to schedule, rotate and geotarget. Publisher tracks impression.

4 Player makes request to loadAdURL(url, adFormat).

5

EyeWonder Instream Framework’s loadAdURL makes request for XML tag URL.

6 EyeWonder Instream Framework loads the parser and inspects “tag”. Is “tag” empty (ad frequency capped)?



www.eyewonder.com

If capped, skip to 13.

7 getPlayerInformation provides details on the video position and player settings.

getAdMovieClip returns a reference to a movie clip, usually set up by the EyeWonder Instream Framework.

8 EyeWonder Instream Framework requests ad SWF from location indicated in tag (may include EyeWonder capping, targeting, and rotation)

9 Ad begins playing. Ad tracks impression

10 On expand interaction, instream ad calls setVideoState(3) to pause player video. On contract interaction, instream ad calls setVideoState(2) to begin player video.

11 Publisher-defined code within setVideoState pauses and plays video.

12 endAd within EyeWonder Instream Framework is triggered either by ad, player (on new video), or EyeWonder Instream Framework (when timer runs out). EyeWonder



www.eyewonder.com

Instream Framework triggers sOnEndAd event and calls registered ad cleanup method is called. Note: Calling a new ad on the same EyeWonder Instream Framework object also calls endAd automatically.

13 Player plays main video if not already playing.

EyeWonder Instream Framework hides the ad’s movieclip by setting _visible to false.

Appendix F. Sample ad code

Note that this code is just for general illustration and should be considered extremely out of date. If you

would like to see more up‐to‐date sample code, please request standalone creatives to view.

Ads should generally be set up with one placeholder frame at the beginning of the timeline, and one

placeholder frame at the end. A transparent layer should be added to each of these frames to take up

space so that ad sizes are reported correctly.



www.eyewonder.com

Timeline

Sample ad (loaded outside of a player)



www.eyewonder.com

Code

function playerVideoPause() { EW.sendToPanel("Pausing player video"); this.uif_instreamObject.setVideoState(3); } function playerVideoPlay() { EW.sendToPanel("Playing player video"); this.uif_instreamObject.setVideoState(2); } function end_IS() // kill the ad { EW.sendToPanel("function end_IS called"); if (closeInterval != -1) clearInterval(closeInterval); this.uif_instreamObject.endAd(); // Clear out anything actively running. } var closeInterval:Number = -1; function handleInteraction() // Call when an interaction happens to reset timer for ad removal. { EW.sendToPanel("function handleInteraction called");

this.uif_instreamObject.trackInteraction(); this.uif_instreamObject.handleInteraction(); } function impression3rdParty() // Only call this ONCE { // TODO: Add any publisher-specific or 3rd party impression tracking calls here //EW.addRequest("http://...") } function closeButtonPressed() // Called by on(release) in button actions { EW.trackInteraction("Close");

this.uif_instreamObject.trackClose(); gotoAndPlay("done"); } function contractButtonPressed() // Called by on(release) in button actions { EW.trackInteraction("Contract"); handleInteraction();

this.uif_instreamObject.trackContract(); gotoAndPlay("contract"); } function interactionHandler() // handle any interaction to delay ad removal timer { handleInteraction(); } function onClickthru() // handler for clickthru event listener { handleInteraction();

this.uif_instreamObject.trackClickthru(); gotoAndPlay("end_contract"); }



www.eyewonder.com

function midOfVideoHandler() { EW.sendToPanel("function midOfVideoHandler called");

this.uif_instreamObject.trackMidOfVideo(); /* Do any creative state changes below */ } function endOfVideoHandler() { EW.sendToPanel("function endOfVideoHandler called");

this.uif_instreamObject.trackEndOfVideo(); /* Do any creative state changes below */ } function startOfVideoHandler() { EW.sendToPanel("function startOfVideoHandler called");

this.uif_instreamObject.trackStartOfVideo(); /* Do any creative state changes below */ }

Appendix G. AdManager

AdManager is a framework that provides a solution to sequencing ads. It implements the Instream

Framework and provides a wrapper for publishers to hook in their own sequencing code for preroll,

overlay, and postroll capabilities.

The EyeWonder framework does not control sequencing. It is purely an interface between the

ad and player and used to load an ad in a single placement. That being said, the AdManager can

be used by the publisher to make sequencing of ads easier. It contains a skeleton that the

publisher can fill in.

AdManager is optional to use, but recommended.



www.eyewonder.com

Appendix H. How To Sync Audio/Video Sync Between Player and Ad

Audio

The following is a description of how to allow audio to be synched between player and ad. Usually, the

audio volume control will be on the player, not the creative. However, they can also be present in both

places and synched.

audioVolume property – Is read/written by the ad. This can be considered as a “virtual audio

control” from the ad’s perspective. The ad should read this property when it first loads its

video, and then also any time it receives the audioVolumechanged event.

o When written by ad, the player can optionally change the entire player volume and

adjust its slider.

o When read by the ad, the player should return the entire player volume, based on the

slider.

audioVolumeChanged event – Is dispatched by player to framework when a user changes the

audio volume slider and is listened to on framework by ad.

Player audio slider

Framework “virtual” audio

slider

Ad volume setting

audioVolumeChanged audioVolumeChanged

audioVolume audioVolume



www.eyewonder.com

Appendix I. Tagparser and AdTagService When loading an ad URL, publishers have the option of specifying whether the ad is of VAST (VAST) format, Eyewonder (EW) format, or an unknown format. UIF will perform a check to see if the supplied format matches the format of the actual tag provided. If “EW” is provided, but the tag is of “VAST” format an error be thrown. If “VAST” is provided, but the tag is of “EW” format an error will be thrown. However, if “unknown” is provided, UIF will check to see if it is an Eyewonder ad. If it is not an Eyewonder ad, UIF will check to see if it is a VAST ad. When the correct format is detected UIF loads the corresponding ad. Conversely, if neither an Eyewonder ad nor VAST ad is detected UIF will throw an error. TagParser also checks the tags if they are frequency capped or invalid XML. In either case InstreamFramework will dispatch a “sOnError” event. AdTagService is a service class accessed by UIF for loading ad tags through its loadAdXMLURL method. When the load is complete, AdTagService notifies UIF so it can start parsing the data. Data is retrieved from the AdTagService’s adTagData property in AS3 and adTagDataE4X property in AS2.

Appendix J. Scaling and Positioning

This is specific to non‐VAST functionality. For VAST scaling, please see the Part III on VAST earlier in the document. Often, creatives need to be run that aren’t built exactly to the size of the video player. For example, scaling is important when a single player is used across a large network where it’s impossible to predict player sizes. Scaling, when positioning is ignored, works similar to a “letterbox”. However, unlike the normal letterbox scenario where a video is centered, the creative can also be positioned within the content . When the ad is lettered boxed a colored background is placed behind the ad to block the content video. Even with scaling, for maximum quality we recommend grouping players into multiple placement sizes. That way, there won’t be as much wasted space or chance of poor quality or visual artifacts from scaling. Video players can use ad server placements to distinguish, and the framework’s automatic positioning will ensure the ads are in the correct space. For example, if there are four video sizes: 320x240 (4:3), 480x270 (16:9), 800x600 (4:3) and 1280x720 (16:9). Then two placements can be created, one for the two smaller sizes, and one for the two larger sizes. What the player developer needs to do Do not directly change the ad container size. UIF will do this for you.



www.eyewonder.com

When the player changes sizes of the video area, or goes fullscreen, it needs to make sure the videoRect value returned by getPlayerInformation reflect the new video area size. For instance, if the data getPlayerInformation returns is pulled from data stored in the player, then it should return data that reflects the change. Then the player should call resizeNotify on the player when the dimensions of the ad container (usually the video screen) change. To avoid assumptions, there is no code in the framework to detect when the player goes fullscreen, so the expectation is that the player will notify the framework just as if the player had resized. Additionally, note that sometimes when players go fullscreen, they scale up their full user interface instead of resizing the video screen. Please make sure that the values returned by getPlayerInformation reflect whichever method was chosen so that the ad properly fits in the fullscreen user interface. How scaling works Two important methods within the Eyewonder framework to take into consideration for scaling are the following:

resizeNotify

getPlayerInformation The bulk of the scaling code is in resizeNotify. However, it’s important for the publisher to modify getPlayerInformation to return the correct ad container dimensions. The modifications should be made in InstreamFramework.as, which modifies InstreamFrameworkBase.as. Note that scaling is proportional, so if there is not an exact fit, the framework needs to position the ad. When the variable _scaleEWFramework is set to true, then the framework compares the ad size (returned from the Eyewonder tag) with the size of the videoRect (ad container) returned from getPlayerInformation. Based on that, the framework scales the ad. Prior to doing the scaling operation, if the aspect ratio of the ad container and ad don’t match, then the framework does a calculation to determine if the width or height should be used as the constraint based on which would lead to the best use of available space and result in a proportional scale. The constraint is then used to determine what dimension should be set to the full width/height of the container to determine the scaling ratio for the other dimension. The actual logic is: IF [ad width] divided by [container width] is greater or equal to [ad height] divided by [container height] THEN use width as the constraint ELSE use height as the constraint Note that since ads, especially contracted tickers, have transparent areas and Flash doesn’t consider transparent areas as part of the height and width calculation that the framework has some adjustments for that. It’s therefore important to make sure that the ad sizes returned in the tag are valid.



www.eyewonder.com

<adAlignHorizontal>center</adAlignHorizontal> <adAlignVertical>bottom</adAlignVertical> <adWidth>320</adWidth> <adHeight>240</adHeight> The above is an excerpt of a tag with positioning values that are common for a ticker. Note that the sizes represent the fully expanded size, not the ticker size when contracted. How positioning works Positioning is always done whether or not scaling is enabled. If scaling is enabled, then the final scaled ad is positioned. Otherwise, if scaling is disabled, then the unscaled creative is positioned. The two methods getPlayerInformation and resizeNotify that apply for positioning are the same as scaling. The bulk of the logic is again in resizeNotify. The logic for positioning is pretty straight‐forward, so it won’t be discussed further beyond to reiterate that when scaling is enabled, the scaled creative is positioned based on the new size after being scaled. Note: If scaling is disabled, the ad will not be displayed if it is too large for the ad container. Here are some examples and the results:



www.eyewonder.com

Scenario Scenario 1 Scenario 2 Scenario 3 Scenario 4 Scenario 5

Type ticker ticker ticker linear linear

alignment (from

tag)

bottom,center bottom,center bottom,center middle,center middle,center

Ad size (from tag) 320x240 320x240 400x300 320x240 640x480

Ad container size

(video screen size)

480x270 480x270 320x240 480x270 500x400

Scaling enabled? y n y n y

Constraint

calculated by

framework

height N/A width* N/A width

Scale amount 112.5% N/A 80% N/A 78.125%

Resulting size and

position in ad

container (in

absolute pixels)

Size:360x270

Position:

(60,0)

Size:320x240

Position:

(80,30)

Size: 320x240

Position: (0,0)

Size:360x270

Position:

(80,15)

Size:500x375

Position:

(0,52.5)

* Because aspe ratio of ad container and ad match, the width is used as the default constraint.



www.eyewonder.com

Positioning with scaling enabled Vertically and horizontally centered linear ad:

Bottom‐aligned ticker:

320x240 video 480x270 video screen

Ad unit (320x240) Ad unit (320x240)

Contracted tickerContracted ticker

320x240 video screen 480x270 video screen




www.eyewonder.com

Positioning with scaling disabled Vertically and horizontally centered linear ad:

Bottom‐aligned ticker:

Changing the position, size, color & alpha of the letterbox background. When the ad is lettered boxed a background will appear behind the ad to block the content video. This creates a cleaner looking ad presentation. The publisher has many options to change the look and the positioning of this background in getPlayerInformation(). info.backgroundRect: Rectangle ‐ Positioning & Size: By default the background is positioned and sized by info.videoRect property (Rectangle) in getPlayerInformation(). If the background needs to be positioned or sized differently info.backgroundRect property is used to move and size the background. info.backgroundColor: Number ‐ Color By default the color of the background is 0x000000 (black). This property can be set to any hex color number. info.backgroundAlpha: Number ‐ Alpha:


Ad unit (320x240)

Contracted ticker

Ad unit (320x240)

Contracted ticker





www.eyewonder.com

By default the alpha is set to 100%. AS2 uses an alpha value range of 0 ‐ 100. AS3 uses a range of 0 ‐ 1.