Halaman ini diterjemahkan oleh Cloud Translation API.

Mulai menggunakan library iklan Android TV

Library iklan Android TV menyediakan antarmuka pengguna bagi pengguna untuk mengontrol pengalaman iklan mereka di Google TV. Panduan ini menjelaskan cara mengintegrasikan library iklan Android TV ke dalam aplikasi Android TV PAL yang ada.

Prasyarat

Selesaikan panduan Memulai
Android PAL SDK versi 20.0.1 atau yang lebih tinggi

Transparansi dan kontrol iklan

Library iklan Android TV menyediakan fungsi untuk merender transparansi iklan dan mengontrol fitur (AT&C) selama jeda iklan. Saat pengguna berinteraksi dengan ikon Iklan TV dari Google selama iklan in-stream, menu AT&C dirender sebagai overlay sistem oleh aplikasi peluncur TV, yang menampilkan URL singkat, respons cepat (kode QR) untuk mengetahui informasi selengkapnya tentang iklan, dan tombol untuk berhenti menampilkan iklan yang sama.

Ikon Iklan TV oleh Google harus dirender menggunakan persyaratan rendering ikon VAST yang sama dengan ikon AdChoices.

Teks alternatif

Mengklik ikon Iklan TV dari Google akan menampilkan URL singkat dan kode QR kepada pengguna untuk halaman web Tentang iklan ini (ATA).

Teks alternatif

Mengintegrasikan library iklan Android TV

Mengimpor library iklan ATV

Tambahkan dependensi berikut untuk library iklan Android TV ke file Gradle level aplikasi, biasanya app/build.gradle:

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

Mendeklarasikan izin `AD_ID`

Agar library iklan Android TV dapat mengakses ID Iklan, tambahkan baris berikut ke AndroidManifest.xml Anda:

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

Mengintegrasikan dengan PAL SDK

Library iklan Android TV menggunakan class SignalCollector untuk mengumpulkan ID di perangkat yang diperlukan untuk meminta iklan. PAL SDK menggunakan class NonceRequest.Builder untuk membaca sinyal ini dan membuat nonce.

Tambahkan baris tebal ke aplikasi PAL Anda untuk menyiapkan library iklan Android TV agar berfungsi dengan 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();
    ...
  }

Menguraikan respons VAST

Saat permintaan iklan dibuat dengan sinyal library iklan Android TV, server iklan Google akan mengirim respons VAST yang berisi tag <Icon> dengan satu atau beberapa turunan <IconClickFallbackImage> untuk resolusi layar yang berbeda. Ikuti petunjuk penguraian respons XML VAST untuk mengurai VAST.

Berikut adalah contoh struktur VAST 4.2 dari tag <Icon> dan turunannya, dengan data yang relevan dalam cetak tebal.

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

Demikian pula, <IconClickFallbackImages> dapat diuraikan menggunakan contoh struktur VAST 3.0 dalam panduan PAL untuk menguraikan respons VAST 3.0.

Saat mengurai VAST, buat objek IconClickFallbackImage untuk setiap tag <IconClickFallbackImage> dan isi dengan data yang diuraikan menggunakan IconClickFallbackImage.Builder. Demikian pula, gunakan IconClickFallbackImages.Builder untuk meneruskan daftar objek IconClickFallbackImage ke dalam objek IconClickFallbackImages yang mewakili tag <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;
  }

Merender AT&C

Library iklan Android TV menyediakan metode AdsControlsManager.handleIconClick() untuk merender menu AT&C atau IconClickFallbackImage VAST standar.

Cuplikan berikut menyiapkan library iklan Android TV untuk merender menu AT&C dan gambar penggantian klik ikon 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);
    ...
  }
}

Memanggil AdsControlsManager.handleIconClick() akan memulai Activity Android sehingga callback siklus proses standar seperti onPause() dan onResume() dapat digunakan untuk memproses perubahan siklus proses aktivitas.

[Opsional] Menyediakan perender gambar penggantian kustom

Jika aplikasi Anda memiliki persyaratan khusus, seperti batasan hardware atau batasan UX, Anda dapat menetapkan fungsi callback menggunakan AdsControlsManager.setCustomFallbackImageRenderer(). Library iklan Android TV akan memverifikasi gambar penggantian untuk menentukan apakah library dapat menggunakan perender kustom yang disediakan. Rendering kustom hanya akan digunakan untuk IconClickFallbackImage VAST, bukan menu 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
      ...
    }
  }
  ...
}

Memberikan masukan kepada Google tentang library iklan Android TV

Kami mencari masukan tentang pengalaman Anda terkait integrasi dan migrasi aplikasi Android TV. Hubungi Account Manager Google Anda untuk menjadwalkan pertemuan dengan salah satu engineer kami.

Histori rilis

Versi	Tanggal Rilis	Catatan
1.0.1	2025-01-09	Memperbarui format kontrol dan transparansi iklan yang didukung.
1.0.0	2023-05-16	Menambahkan logging. Menurunkan dukungan minSdk ke API level 21. Memperbarui penanganan error dan dependensi untuk memperbaiki error.
1.0.0-alpha02	2022-11-17	Memperbarui Manifes Android sehingga fitur Leanback bersifat opsional.
1.0.0-alpha01	2022-09-07	Rilis awal.

Mulai menggunakan library iklan Android TV Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.