Upgrading from IMA Flash SDK version 2

To upgrade to version 3 of the Google IMA Flash SDK (if you have already
integrated version 2 into your video player),
download and import
version 3 into your development environment using either the SDK Library
SWC or MXP
file. Package names can be used to easily distinguish version 2 classes from
their version 3 equivalents. For example:

Version 2: com.google.ads.instream.api

Version 3: com.google.ads.ima.api

Then, review the important changes in version 3 in the Changes to the
AdsLoader and AdsRequest and Changes to the AdsManager sections
below.

Note: If you will be using ads from AdSense or
Ad Exchange, refer to these
parameter descriptions
to create IMA SDK v3-compliant ad tags for your ad requests.

Changes to the AdsLoader and AdsRequest

AdsLoader

Instead of firing AdsLoadedEvent.ADS_LOADED, the AdsLoader
now fires an AdsManagerLoadedEvent.ADS_MANAGER_LOADED event. For
more details on this event, see the Changes to the AdsManager
section of this page.

To support additional playback scenarios, another method, contentComplete,
has been added to the AdsLoader. One such scenario involves using
a single player to display multiple pieces of content as well as ad rules post-roll
linear ads on a single page. To implement this, simply invoke contentComplete each
time your content has finished playing. Optionally, you may also provide its
content ID.

AdsRequest

The AdsRequest object now requires an adTagUrl
to be set for each request. All of the AdSense parameters that had
previously been set on the AdsRequest object have been moved
to the adTagUrl property. Refer to the
Override AdSense attributes
page in the DFP Small Business Help Center for more details on migrating your
AdSense parameters into your ad tag.

Each AdsRequest must also include the following video player
ad slot sizes:

linearAdSlotWidth

linearAdSlotHeight

nonLinearAdSlotWidth

nonLinearAdSlotHeight

The linear property values should match the video player size at the time
of the request. The non-linear property values should be the maximum amount
of player space available for an overlay ad.

adsResponse setter property

You can now use the adsResponse setter property to
inject any VAST XML response directly into an adsRequest.
This allows the SDK to display the ads contained within a valid VAST
response as if the SDK itself had made the VAST web request. To use this
feature, convert the VAST XML to a String and set the
adsResponse property before calling adsLoader.requestAds(adsRequest).

Changes to the AdsManager

The AdsManager has been redesigned in version 3. The significant
changes you need to understand when upgrading your implementation are
summarized in the following three sections.

getAdsManager

The ADS_MANAGER_LOADED event handler is invoked when a VAST
InLine response has been received. The AdsManager
object is no longer accessible via a property getter on the event. Instead,
use the getAdsManager() method,
passing it these
optional parameters. The difference in how
you would get the AdsManager object in version 2 versus version
3 is shown below:

Note: A single AdsManager
now handles all ad types. The individual AdsManagers that had been previously
used for each ad type (e.g., VideoAdsManager,
FlashAdsManager, etc.) have been removed.

Events

New events types have been added and some pre-existing events have been
renamed in version 3. The table below lists the events fired in version 3
compared to version 2. If you've already worked with VPAID ads, these new
events should be familiar to you. All event types listed are static constants
on the AdEvent class unless specified otherwise.

Note: Events marked with a red
asterisk * in
the table below must have event listeners registered before calling
init() or start().

Version 3

Version 2

AdErrorEvent.AD_ERROR *

AdErrorEvent.AD_ERROR

AD_METADATA

ALL_ADS_COMPLETED *

ALL_ADS_COMPLETE

CLICKED

CLICK

COMPLETED

COMPLETE

CONTENT_PAUSE_REQUESTED *

CONTENT_PAUSE_REQUESTED

CONTENT_RESUME_REQUESTED *

CONTENT_RESUME_REQUESTED

DURATION_CHANGED

EXPANDED_CHANGED

FIRST_QUARTILE

FIRST_QUARTILE

IMPRESSION

INTERACTION

LINEAR_CHANGED

LOADED

LOG

MIDPOINT

MIDPOINT

PAUSED

PAUSED

REMAINING_TIME_CHANGED

RESTARTED

RESUMED

SIZE_CHANGED

SKIPPABLE_STATE_CHANGED

SKIPPED

STARTED

STARTED

STOPPED

STOPPED

THIRD_QUARTILE

THIRD_QUARTILE

USER_ACCEPTED_INVITATION

USER_CLOSED

USER_CLOSE

USER_MINIMIZED

VOLUME_CHANGED

VOLUME_MUTED

VOLUME_MUTED

Methods

Many of the old VideoAdsManager and
FlashAdsManager APIs have been moved. These APIs are now
housed in the AdsManager class. This section discusses the
use of the methods in these APIs.

Preparing for playback

The load and play methods have been removed.
Instead, use handshakeVersion, init, and
start in your version 3 implementation.
The v3 Flash Advanced Topics page
provides more details on this topic.

Displaying ads

Instead of passing a container into the AdsManager as was done
in version 2, the version 3 AdsManager exposes an
adsContainer property that allows you to retrieve the object in
which the ads will be displayed. You may position this object as you wish.
Here's an example of how to position an overlay in the bottom center of
your video player.

Companion ads

You can now access the Ad interface through any
AdEvent fired by the AdsManager. Once you have
accessed the Ad interface, accessing the CompanionAd
interface is the same as it was in version 2. For companion ads which exist
in the same Flash environment (i.e., FlashCompanionAd), we've
removed the x and y positioning properties. Instead,
add the FlashCompanionAd.adsContainer to the companion ad display
slot as you did for the AdsManager. For a general discussion of
companion ad usage in the IMA, see
Companion Ads.

Cleaning up

Once you've received the ALL_ADS_COMPLETE event, be sure to
call adsManager.destroy() rather than
adsManager.unload(). Failure to do so may cause memory leaks
on your users' machines.