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.
Clicking the TV Ads by Google icon shows the user a short URL and QR code for the About this ad (ATA) webpage.
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 |
|
| 1.0.0-alpha02 | 2022-11-17 |
|
| 1.0.0-alpha01 | 2022-09-07 |
|