本頁面由 Cloud Translation API 翻譯而成。

開始使用 Android TV 廣告庫

Android TV 廣告資料庫提供使用者介面，方便使用者控制 Google TV 的廣告體驗本指南說明如何整合 Android TV 加入現有的 PAL Android TV 應用程式

必要條件

完成開始使用指南
Android PAL SDK 20.0.1 以上版本

廣告資訊公開與控制選項

Android TV 廣告程式庫提供顯示廣告透明度的功能，在廣告插播期間控管功能 (AT&C)。使用者與電視廣告互動時，在串流內廣告播放期間， 圖示將以系統的形式呈現 AT&C 選單疊加在電視啟動器應用程式上，顯示簡短網址和快速回應 (QR code) ，進一步瞭解廣告以及停止顯示相同廣告的按鈕。

「Google 提供的電視廣告」圖示應以相同的 VAST 圖示顯示轉譯需求 AdChoices 圖示。

替代文字

使用者按一下「Google 提供的電視廣告」圖示，會看到以下應用程式的短網址和 QR code 「關於這則廣告」網頁。

替代文字

整合 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敬上類別，以便在請求廣告時所需的裝置上收集 ID。私刑 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() 可用來監聽活動生命週期變更

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

如果您的應用程式有特殊需求，例如硬體限製或使用者體驗您可以使用 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	更新允許 Leanback 特徵做為選用項目
1.0.0-alpha01	2022-09-07	第 1 版。