Developer Console

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

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

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

  1. 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.
  2. Remove any other ad components that are loaded in your app (such as FreeWheelAdsCompnent or PassThroughAdsComponent). See Add or Remove a Component for details.

  3. 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.

  4. 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
    " &quot;
    ' &apos;
    < &lt;
    > &gt;
    & &amp;
  5. 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:

  1. 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.
  2. In the Android view, expand Gradle Scripts and open the build.gradle (Module: VastAdsComponent) file.
  3. 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')
    }
    
  4. Expand the Gradle Scripts section again and open the settings.gradle (Project: Settings) file.
  5. 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')
    
  6. 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>
    
  7. 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