此页面由 Cloud Translation API 翻译。

开始使用 Android TV 广告库

Android TV 广告库提供了一个界面，供用户控制 Google TV 上的广告体验。本指南介绍了如何集成 Android TV 添加到您现有的 PAL Android TV 应用中。

前提条件

完成入门指南
Android PAL SDK 20.0.1 或更高版本

广告透明度和控制

Android TV 广告库提供了呈现广告透明度和在广告插播期间控制功能 (AT&C)。当用户与电视广告互动时 “由 Google 提供”图标，则 AT&C 菜单会以系统的形式显示由电视启动器应用叠加显示，其中显示了一个短网址、一条快速回复（二维码），了解有关该广告的更多信息，以及一个用于停止展示同一广告的按钮。

Google 提供的电视广告图标应使用相同的 VAST 图标来呈现呈现要求作为 AdChoices 图标。

替代文本

点击 Google 提供的电视广告图标后，用户会看到一个简短的网址和二维码 关于此广告 (ATA) 网页上。

替代文本

集成 Android TV 广告库

导入 ATV 广告库

将 Android TV 广告库的以下依赖项添加到您的应用级 Gradle 文件（通常为 app/build.gradle）：

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

声明 `AD_ID` 权限

为了让 Android TV 广告库能够访问 ID，请将以下行添加到您的 AndroidManifest.xml 中：

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

与 PAL SDK 集成

Android TV 广告库使用 SignalCollector 类来收集在设备上请求广告所需的标识符。《PAL》 SDK 使用 NonceRequest.Builder 类来读取这些信号并构建 Nonce。

将粗体几行添加到您的 PAL 应用，以设置 Android TV 广告库与 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();
    ...
  }

解析 VAST 响应

使用 Android TV 广告库的信号发出广告请求后，Google 广告服务器会发送一个包含 <Icon> 代码的 VAST 响应，此代码为针对不同屏幕分辨率的多个 <IconClickFallbackImage> 子元素。遵循解析 VAST XML 响应的步骤说明来解析 VAST

以下是 <Icon> 代码及其子级的 VAST 4.2 结构示例，相关数据以粗体显示。

<?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>

同样，可以使用示例 VAST 3.0 解析 <IconClickFallbackImages> 结构（参见 PAL 指南中关于解析 VAST 3.0 的内容）响应。

解析 VAST 时，创建一个 IconClickFallbackImage 对象，并使用解析的<IconClickFallbackImage> 使用 IconClickFallbackImage.Builder。同样，使用 IconClickFallbackImages.Builder 将 IconClickFallbackImage 对象列表传递到 IconClickFallbackImages 代表 <IconClickFallbackImages> 标记的对象。

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;
  }

渲染 AT&C

Android TV 广告库提供了 AdsControlsManager.handleIconClick() 方法呈现 AT&C 菜单或标准 VAST IconClickFallbackImage。

以下代码段会设置 Android TV 广告库，以呈现 AT&C 和 VAST 图标点击后备图片

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);
    ...
  }
}

调用 AdsControlsManager.handleIconClick() 会启动 Android Activity，因此标准生命周期回调 onPause() 和 onResume() 可用于监听 activity 生命周期更改。

[可选] 提供自定义后备图片渲染程序

如果您的应用有特殊要求，例如硬件限制或用户体验要求您可以使用 AdsControlsManager.setCustomFallbackImageRenderer()。 Android TV 广告库会验证后备图片，以确定它可以使用提供的自定义渲染程序。系统只会使用自定义呈现而不是 AT&C 菜单。

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

向 Google 提供有关 Android TV 广告库的反馈

我们希望就集成和 Android TV 应用的迁移。如需预约，请联系您的 Google 客户经理与一位工程师开会。

发布版本历史记录

版本	发布日期	备注
1.0.0	2023-05-16	添加日志记录。将 minSdk 支持降至 API 级别 21。更新了错误处理和依赖项以修复崩溃问题。
1.0.0-alpha02	2022-11-17	更新 Android 清单，以允许 Leanback 则是可选功能。
1.0.0-alpha01	2022-09-07	初始版本。