本頁面由 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 電視廣告」圖示互動時，TV 啟動器應用程式會將 AT&C 選單以系統重疊方式呈現，顯示短網址、快速回應 (QR code) 以便進一步瞭解廣告，以及停止顯示相同廣告的按鈕。

Google 電視廣告圖示應採用與 AdChoices 圖示相同的 VAST 圖示算繪規定。

替代文字

點選「Google 電視廣告」圖示後，系統會向使用者顯示「關於這則廣告」 (ATA) 網頁的短網址和 QR code。

替代文字

整合 Android TV 廣告程式庫

匯入 ATV 廣告程式庫

將 Android TV 廣告程式庫的以下依附元件新增至應用程式層級 Gradle 檔案 (通常為 app/build.gradle)：

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

宣告 `AD_ID` 權限

為了讓 Android TV 廣告程式庫存取 Advertising ID，請在 AndroidManifest.xml 中加入以下程式碼行：

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

與 PAL SDK 整合

Android TV 廣告程式庫會使用 SignalCollector 類別，在裝置上收集要求廣告所需的 ID。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 廣告伺服器會傳送 VAST 回應，其中包含 <Icon> 代碼，以及一或多個 <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>

同樣地，您也可以使用 PAL 指南中的 VAST 3.0 範例結構，剖析 <IconClickFallbackImages>。

剖析 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()) 來監聽活動生命週期變更。

[選用] 提供自訂備用圖片轉譯器

如果應用程式有特殊需求 (例如硬體限制或使用者體驗限制)，您可以使用 AdsControlsManager.setCustomFallbackImageRenderer() 設定回呼函式。Android TV 廣告程式庫會驗證備用圖片，判斷是否可以使用提供的自訂轉譯器。自訂算繪作業只會用於 VAST IconClickFallbackImage，而非 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
      ...
    }
  }
  ...
}

提供有關 Android TV 廣告庫的意見回饋

我們希望您能針對整合和遷移 Android TV 應用程式的體驗提供意見。請與 Google 客戶經理聯絡，安排與工程師的會議。

版本記錄

版本	發布日期	附註
1.0.1	2025-01-09	更新支援的廣告資訊公開和控制項格式。
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	第 1 版。

開始使用 Android TV 廣告庫 透過集合功能整理內容 你可以依據偏好儲存及分類內容。