このページは Cloud Translation API によって翻訳されました。

Android TV 広告ライブラリのスタートガイド

Android TV 広告ライブラリは、ユーザーが Google TV で広告エクスペリエンスを制御するためのユーザーインターフェースを提供します。このガイドでは、Android TV 広告ライブラリを既存の PAL Android TV アプリに統合する方法について説明します。

前提条件

スタートガイドの手順を完了していること
Android PAL SDK バージョン 20.0.1 以降

広告の透明性と管理

Android TV 広告ライブラリには、ミッドロール挿入点中の広告の透明性とコントロール機能（AT&C）をレンダリングする機能が用意されています。ユーザーがインストリーム広告中に TV Ads by Google アイコンを操作すると、テレビランチャーアプリによって AT&C メニューがシステムオーバーレイとしてレンダリングされ、広告の詳細を確認するためのショート URL、クイックレスポンス（QR コード）、同じ広告の表示を停止するためのボタンが表示されます。

TV Ads by Google アイコンは、AdChoices アイコンと同じ VAST アイコンのレンダリング要件を使用してレンダリングする必要があります。

代替テキスト

[TV Ads by Google] アイコンをクリックすると、[この広告について]（ATA）ウェブページの短い URL と QR コードが表示されます。

代替テキスト

Android TV 広告ライブラリを統合する

ATV 広告ライブラリをインポートする

Android TV 広告ライブラリの次の依存関係をアプリレベルの Gradle ファイル（通常は app/build.gradle）に追加します。

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

`AD_ID` 権限を宣言する

Android TV 広告ライブラリが広告 ID にアクセスできるようにするには、AndroidManifest.xml に次の行を追加します。

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

PAL SDK と統合する

Android TV 広告ライブラリは、SignalCollector クラスを使用して、広告のリクエストに必要なデバイス上の ID を収集します。PAL SDK は、NonceRequest.Builder クラスを使用してこれらのシグナルを読み取り、ノンスを作成します。

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 広告サーバーは、さまざまな画面解像度に対応する 1 つ以上の <IconClickFallbackImage> 子を持つ <Icon> タグを含む VAST レスポンスを送信します。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>

同様に、<IconClickFallbackImages> は、VAST 3.0 レスポンスを解析するための 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;
  }

A&C をレンダリングする

Android TV 広告ライブラリには、AT&C メニューまたは標準の VAST IconClickFallbackImage をレンダリングするための AdsControlsManager.handleIconClick() メソッドが用意されています。

次のスニペットは、AT&C メニューと VAST アイコンのクリックフォールバック画像をレンダリングするように Android TV 広告ライブラリを設定します。

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() などの標準のライフサイクルコールバックを使用して、アクティビティのライフサイクルの変化をリッスンできます。

[省略可] カスタムのフォールバック画像レンダラを指定する

アプリにハードウェアの制限や UX の制約などの特別な要件がある場合は、AdsControlsManager.setCustomFallbackImageRenderer() を使用してコールバック関数を設定できます。Android TV 広告ライブラリは、フォールバック画像を検証して、指定されたカスタムレンダラを使用できるかどうかを判断します。カスタムレンダリングは、AT&C メニューではなく、VAST IconClickFallbackImage にのみ使用されます。

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 広告ライブラリに関するフィードバックを Google に送信する

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	初回リリース。

Android TV 広告ライブラリのスタートガイド コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。