VAST Ads Component

IV: Add Components for More Functionality

→

Fire App Builder supports the VAST ads template (Video Ad Serving Template). VAST is a standard protocol that supports different video advertisers. The Interactive Advertising Bureau (IAB) describes VAST as follows:

The IAB Digital Video Ad Serving Template (VAST) specification is a universal XML schema for serving ads to digital video players, and describes expected video player behavior when executing VAST-formatted ad responses. VAST 3.0 adds critical functionality that opens up the in-stream digital video advertising marketplace, reducing expensive technical barriers and encouraging advertisers to increase video ad spend. Digital Video Ad Serving Template (VAST) 3.0

For example, if you want to show DoubleClick ads in your app, you can do so through the VAST Ads Component.

The Scope of VAST Support
- Supported VAST Features
- VAST Features Not Supported
Tracking Events
The User Experience with VAST Ads
Configure VAST Ads
Launch Video Clicks in a MiniBrowser
- Using MiniBrowser in Other Components Besides Vast Ads

The Scope of VAST Support

The Fire App Builder integration of VAST does not include support for the entire VAST specification (which is immense). Only a subset of VAST features are supported by Fire App Builder. Additionally, the VAST integration in Fire App Builder is not officially certified by the IAB.

Supported VAST Features

Fire App Builder provides support for ad tags for VAST 3.0 and VMAP ads. Specifically, Fire App Builder supports all of the following:

Playing pre-roll, mid-roll, and post-roll ads for the VAST 2.0 and 3.0 schema
Linear ads
Resolving VMAP ad tags

(VMAP — Video Multiple Ad Playlist — contains references to other ad tags. The ad tags referenced by the VMAP ad could be a VAST format or another proprietary format. Fire App Builder supports parsing out only the VAST format. If you have another format you want to support, you can expand the VAST component to support it.)

VAST Features Not Supported

The following VAST features are not supported in Fire App Builder:

Non-linear ads such as skippable linear creatives, companion ads, or nonlinear ads
Any interactions within the ad
302 redirects

Tracking Events

During the Linear Video Ad playback, the VAST component triggers events for the following:

Impressions
Errors
Start (25%, mid, 75%, and complete)
Adbreaks

During video ads, users can play, pause, and click events VAST-based ads that play.

The following table lists the component's specific support for various events:

Tracking Events Supported

creativeView No

start Yes

midpoint Yes

firstQuartile Yes

thirdQuartile Yes

complete Yes

breakstart Yes

breakend Yes

error Yes

mute No

unmute No

pause No

rewind No

resume No

fullscreen No

expand No

collapse No

acceptInvitation No

close No

Tracking Events	Supported
`creativeView`	No
`start`	Yes
`midpoint`	Yes
`firstQuartile`	Yes
`thirdQuartile`	Yes
`complete`	Yes
`breakstart`	Yes
`breakend`	Yes
`error`	Yes
`mute`	No
`unmute`	No
`pause`	No
`rewind`	No
`resume`	No
`fullscreen`	No
`expand`	No
`collapse`	No
`acceptInvitation`	No
`close`	No

The User Experience with VAST Ads

Assuming you have pre-roll ads configured, after the user clicks the Watch Now button, the VAST ads template serves up ads for a short period of time.

The VAST ads template serves up video before the user's selected media starts to play. The screenshot here is just ad filler that would be replaced by a real ad when you configure VAST ads.

After the video ad finishes, the user's selected media begins to play.

Configure VAST Ads

Load the VAST ads component into your app. See the Add or Remove a Component for details about how to load a component into your app.
Remove any other ad components that are loaded in your app (such as FreeWheelAdsCompnent or PassThroughAdsComponent). See Add or Remove a Component for details.

Note: You can load only one component per interface. For example, you cannot load both the VAST Ads component and the Freewheel Ads component, because both components use the same IAds interface. For a list of the components by interface, see Components Overview.

Go to VastAdsComponent > res > values > values.xml > values.xml. Copy the ad_tag string and paste it into your app's custom.xml file (inside res > values). Here's an example:

<string name="ad_tag">"https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&amp;iu=/124319096/external/single_ad_samples&amp;ciu_szs=300x250&amp;impl=s&amp;gdfp_req=1&amp;env=vp&amp;output=vast&amp;unviewed_position_start=1&amp;cust_params=deployment%3Ddevsite%26sample_ct%3Dlinear&amp;correlator="</string>

For examples of supported ad tags, see IMA Sample Tags in this Google project.

Customize the value for the ad_tag string with your own VAST ads tag.

Note that in your VAST tag, the following characters must be encoded:

Character	Encoding
`"`	`"`
`'`	`'`
`<`	`<`
`>`	`>`
`&`	`&`

To enable users to play, pause, and click events within your ad, open your app's custom.xml file (inside res > values) and add the following:
```
<bool name="enable_key_events_on_ad_view">true</bool>
<bool name="enable_play_state_overlay_on_ad_view">true</bool>
```
This enables the play/pause button on the ad renderer and allows the play/pause/center buttons to work. (By default this feature is turned off.) To enable events to open in a web browser, see the next section: Launch Video Clicks in a MiniBrowser.

When you run your app, the VAST ad will play as configured.

Launch Video Clicks in a MiniBrowser

Fire App Builder provides a WebView module called MiniBrowser to support user interaction, primarily for ad clicks. When users click links in your VAST ad, the MiniBrowser can open with the destination pages. (The MiniBrowser can also be extended for use by other modules.)

To add MiniBrowser support for VAST ads:

Follow the instructions in the previous section, Configure VAST Ads. Make sure you complete the last step (#5), where you enable users to play, pause, and click events within ads.
In the Android view, expand Gradle Scripts and open the build.gradle (Module: VastAdsComponent) file.

In the dependencies object, add compile project(':MiniBrowser') as shown in red below:

dependencies {
    compile fileTree(dir: 'libs', include: ['*.jar'])
    compile files('libs/mfXerces.jar')
    compile 'com.android.support:appcompat-v7:23.3.0'

    androidTestCompile('com.android.support.test:runner:0.4') {
        exclude group: 'com.android.support', module: 'support-annotations'
    }
    androidTestCompile('com.android.support.test:rules:0.4') {
        exclude group: 'com.android.support', module: 'support-annotations'
    }
    androidTestCompile 'junit:junit:4.12'

    compile project(':ModuleInterface')
    compile project(':AdsInterface')
    compile project(':DynamicParser')
    compile project(':Utils')
    compile project(':MiniBrowser')
}

Expand the Gradle Scripts section again and open the settings.gradle (Project: Settings) file.

Add the following MiniBrowser entries as shown in red below:

include ':app', ':AdobeMobileLibrary',
        /* Frameworks */
        ':TVUIComponent',
        ':UAMP',
        /* Libraries */
        ':ContentModel',
        ':ContentBrowser',
        ':DynamicParser',
        ':DataLoader',
        ':Utils',
        ':Calligraphy',
        ':MiniBrowser',
        /* Interfaces */
        ':AuthInterface',
        ':AdsInterface',
        ':AnalyticsInterface',
        ':ModuleInterface',
        ':PurchaseInterface',
        /* Implementations */
        ':VastAdsComponent',
        ':AMZNMediaPlayerComponent',
        ':AdobePrimetimeFireTvSdkAuthComponent',
        ':OmnitureAnalyticsComponent',
        ':AmazonInAppPurchaseComponent'

/* Frameworks */
project(':TVUIComponent').projectDir = new File(rootProject.projectDir, '../TVUIComponent/lib')
project(':UAMP').projectDir = new File(rootProject.projectDir, '../UAMP')

/* Libraries */
project(':ContentModel').projectDir = new File(rootProject.projectDir, '../ContentModel')
project(':ContentBrowser').projectDir = new File(rootProject.projectDir, '../ContentBrowser')
project(':DynamicParser').projectDir = new File(rootProject.projectDir, '../DynamicParser')
project(':DataLoader').projectDir = new File(rootProject.projectDir, '../DataLoader')
project(':Utils').projectDir = new File(rootProject.projectDir, '../Utils')
project(':Calligraphy').projectDir = new File(rootProject.projectDir, '../TVUIComponent/Calligraphy')
project(':MiniBrowser').projectDir = new File(rootProject.projectDir, '../MiniBrowser')

In your app's custom.xml file, add the following elements inside resources:

<string name="browser_class_name">com.amazon.android.minibrowser.WebViewHandlerActivity</string>
<bool name="enable_key_events_on_ad_view">true</bool>
<bool name="enable_play_state_overlay_on_ad_view">true</bool>
<bool name="enable_browser_support_on_ad_view">true</bool>

Click Sync now to resync Gradle.

Now when you have click events that launch web views, the events will launch through the MiniBrowser.

Using MiniBrowser in Other Components Besides Vast Ads

MiniBrowser is mainly intended for interactivity with Vast ads. However, you can use the MiniBrowser for other components as well. To do so, you would follow the same general steps in the previous section (Launch Video Clicks in a MiniBrowser), but instead of making modifications in the VastAdsComponents folder, you would make the modifications in the component folder you're adding MiniBrowser to. Then send an intent for the startActivity for com.amazon.android.MiniBrowser.WebViewHandlerActivity class with the required URI.

The MiniBrowser has a separate Amazon licensing requirement, which you can read in the terms_of_use.html file (in app > resources).

Last updated: Jan 16, 2018