Get started with the Android TV ads library

The Android TV ads library provides a user interface for users to control their ad experience on Google TV. This guide explains how to integrate the Android TV ads library into your existing PAL Android TV app.

Prerequisites

  • Complete the Get Started guide
  • Android PAL SDK version 20.0.1 or higher

Ads transparency and controls

The Android TV ads library provides functionality to render ads transparency and controls features (AT&C) during ad breaks. When users interact with the TV Ads by Google icon during in-stream ads, the AT&C menu is rendered as a system overlay by the TV launcher app, showing a short URL, a quick response (QR code) to find out more about the ad and a button to stop showing the same ad.

The TV Ads by Google icon should be rendered using the same VAST icon rendering requirements as the AdChoices icon.

Alt text

Clicking the TV Ads by Google icon shows the user a short URL and QR code for the About this ad (ATA) webpage.

Alt text

Integrate the Android TV ads library

Import the ATV ads library

Add the following dependency for the Android TV ads library to your app-level Gradle file, normally app/build.gradle:

dependencies {
   ...
   implementation 'com.google.android.tv:tv-ads:1.0.0'
}

Declare AD_ID permission

In order for the Android TV ads library to access the Advertising ID, add the following line to your AndroidManifest.xml:

<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>

Integrate with the PAL SDK

The Android TV ads library uses the SignalCollector class to collect identifiers on the device required for requesting ads. The PAL SDK uses the NonceRequest.Builder class to read these signals and build a nonce.

Add the bold lines to your PAL app to set up the Android TV ads library to work with the PAL SDK:

public class VideoPlayerActivity extends Activity {
  ...
  private SignalCollector signalCollector;
  ...
  @Override
  public void onCreate(Bundle savedInstanceState) {
    ...
    signalCollector = new SignalCollector();
    ...
  }
  ...
  public generateNonceForAdRequest() {
    ...
    NonceRequest nonceRequest = NonceRequest.builder()
        ...
        .platformSignalCollector(signalCollector)
        .build();
    ...
  }

Parse VAST response

When an ad request is made with the Android TV ads library's signals, Google ad servers will send a VAST response containing the <Icon> tag with one or multiple <IconClickFallbackImage> children for different screen resolutions. Follow the parsing VAST XML responses instructions to parse the VAST.

Here is a sample VAST 4.2 structure of the <Icon> tag and its children, with the relevant data in bold.

<?xml version="1.0" encoding="UTF-8"?>
<VAST version="4.2">
 <Ad id="123456">
  <Wrapper>
   ...
   <Creatives>
    ...
    <Creative id="7891011" AdID="ABCD123456EF" sequence="1">
     ...
     <Linear>
      ...
      <Icons>
       ...
       <Icon program="TV Ads by Google" width="106" height="20" xPosition="24" yPosition="20"
        duration="00:00:10" offset="00:00:00" apiFramework="VAST" altText="Why This Ad?">
        <StaticResource creativeType="image/png">
         <![CDATA[https://imasdk.googleapis.com/formats/ata/gtv_ads_badge.png]]>
        </StaticResource>
        <IconClicks>
         ...
         <IconClickThrough><![CDATA[https://myadcenter.google.com]]></IconClickThrough>
         <IconClickFallbackImages>
          <IconClickFallbackImage width="950" height="600">
           <AltText>Sample alt text</AltText>
           <StaticResource creativeType="image/png">
            <![CDATA[https://google.com?atvatc=1&atvatcmd=Eg8KDQoLbXV0ZV9hZF91cmwKAgoA]]>
           </StaticResource>
          </IconClickFallbackImage>
          ...
         </IconClickFallbackImages>
        </IconClicks>
       </Icon>
       ...
      </Icons>
     ...
     </Linear>
     ...
    </Creative>
    ...
   </Creatives>
   ...
  </Wrapper>
  ...
 </Ad>
</VAST>

Similarly, <IconClickFallbackImages> can be parsed using the example VAST 3.0 structure in the PAL guide for parsing VAST 3.0 responses.

When parsing the VAST, create an IconClickFallbackImage object for each <IconClickFallbackImage> tag and populate it with the parsed data using IconClickFallbackImage.Builder. Similarly, use IconClickFallbackImages.Builder to pass the list of IconClickFallbackImage objects into an IconClickFallbackImages object representing the <IconClickFallbackImages> tag.

import com.google.android.tv.ads.IconClickFallbackImage;
import com.google.android.tv.ads.IconClickFallbackImages;
import java.util.Arrays;
...
  IconClickFallbackImages getIconClickFallbackImages(...) {
    // Use parsed VAST IconClickFallbackImages data to build a list of
    // IconClickFallbackImage objects.

    int parsedWidth;
    int parsedHeight;
    String parsedAltText;
    String parsedCreativeType;
    String parsedStaticResourceUri;
    // Read the <IconClickFallbackImage> node and its children to set
    // parsedWidth, parsedHeight, ...

    IconClickFallbackImages iconClickFallbackImages =
        IconClickFallbackImages.builder(
                Arrays.asList(
                    IconClickFallbackImage.builder()
                        .setWidth(parsedWidth)
                        .setHeight(parsedHeight)
                        .setAltText(parsedAltText)
                        .setCreativeType(parsedCreativeType)
                        .setStaticResourceUri(parsedStaticResourceUri)
                        .build()))
            .build();

    return iconClickFallbackImages;
  }

Render AT&C

The Android TV ads library provides an AdsControlsManager.handleIconClick() method for rendering an AT&C menu or a standard VAST IconClickFallbackImage.

The following snippet sets up the Android TV ads library to render the AT&C menu and VAST icon click fallback images.

import android.app.Activity;
import android.os.Bundle;
import android.view.View;
import com.google.android.tv.ads.AdsControlsManager;
import com.google.android.tv.ads.IconClickFallbackImage;
import com.google.android.tv.ads.IconClickFallbackImages;
import java.util.ArrayList;
import java.util.List;

public final class VideoPlayerActivity extends Activity {
  ...
  private AdsControlsManager adsControlsManager;
  ...
  @Override
  public void onCreate(Bundle savedInstanceState) {
    ...
    adsControlsManager = new AdsControlsManager(this);
    ...
  }
  ...

  /**
   * Called when the user interacts with any VAST Icon.
   * @param view.
   */
  public void onVastIconClicked(View view) {
    IconClickFallbackImages iconClickFallbackImages;
    // Populate the IconClickFallbackImages object from the parsed VAST data.
    ...
    adsControlsManager.handleIconClick(iconClickFallbackImages);
    ...
  }
}

Calling AdsControlsManager.handleIconClick() starts an Android Activity so standard lifecycle callbacks such as onPause() and onResume() can be used to listen to activity lifecycle changes.

[Optional] Provide custom fallback image renderer

If your app has special requirements, such as hardware restrictions or UX constraints, you can set a callback function using AdsControlsManager.setCustomFallbackImageRenderer(). The Android TV ads library will verify the fallback images to determine whether it can use the provided custom renderer. A custom rendering will only be used for VAST IconClickFallbackImage, and not the AT&C menu.

import android.app.Activity;
import android.os.Bundle;
import com.google.android.tv.ads.AdsControlsManager;
import com.google.android.tv.ads.CustomFallbackImageRenderer;
import com.google.android.tv.ads.IconClickFallbackImages;
import java.util.List;

public final class VideoPlayerActivity extends Activity {
  ...
  private AdsControlsManager adsControlsManager;
  ...
  @Override
  public void onCreate(Bundle savedInstanceState) {
    ...
    adsControlsManager = new AdsControlsManager(this);
    adsControlsManager.setCustomFallbackImageRenderer(
        new CustomFallbackImageRendererImpl());
    ...
  }

  private static class CustomFallbackImageRendererImpl implements CustomFallbackImageRenderer {
    @Override
    public void render(IconClickFallbackImages iconClickFallbackImages) {
      // Render the fallback images using a custom layout
      ...
    }
  }
  ...
}

Give Google feedback about the Android TV ads library

We are looking for feedback about your experience with integration and migration of Android TV apps. Contact your Google account manager to schedule a meeting with one of our engineers.

Release history

Version Release Date Notes
1.0.0 2023-05-16
  • Adds logging.
  • Lowers minSdk support to API level 21.
  • Updates error handling and dependencies to fix crashes.
1.0.0-alpha02 2022-11-17
  • Updates the Android Manifest allowing the Leanback feature to be optional.
1.0.0-alpha01 2022-09-07
  • Initial release.