Ta strona została przetłumaczona przez Cloud Translation API.

Pierwsze kroki z biblioteką reklam na Androidzie TV

Biblioteka reklam Android TV zawiera interfejs użytkownika, który pozwala kontrolować wyświetlanie reklam na Google TV. Z tego przewodnika dowiesz się, jak zintegrować bibliotekę reklam Androida TV z istniejącą aplikacją PAL na Androida TV.

Wymagania wstępne

Przeczytaj Przewodnik dla początkujących.
Pakiet SDK PAL na Androida w wersji 20.0.1 lub nowszej

Przejrzystość i ustawienia reklam

Biblioteka reklam Android TV zapewnia funkcje wyświetlania przejrzystości reklam i elementów sterujących (AT&C) podczas przerw na reklamy. Gdy użytkownicy wchodzą w interakcję z ikoną TV Ads by Google podczas reklam in-stream, menu AT&C jest renderowane jako nakładka systemowa przez aplikację do uruchamiania telewizora. Zawiera ono krótki URL, kod QR, który umożliwia uzyskanie dodatkowych informacji o reklamie, oraz przycisk, który pozwala zatrzymać wyświetlanie tej samej reklamy.

Ikona TV Ads by Google powinna być renderowana zgodnie z tymi samymi wymaganiami dotyczącymi renderowania ikony VAST co ikona AdChoices.

Tekst zastępczy

Po kliknięciu ikony Reklamy telewizyjne Google użytkownik zobaczy krótki adres URL i kod QR, które pozwolą mu otworzyć stronę Informacje o reklamie (ATA).

Tekst zastępczy

Integracja biblioteki reklam Androida TV

Importowanie biblioteki reklam ATV

Dodaj tę zależność do biblioteki reklam na Androida TV w pliku Gradle na poziomie aplikacji (zwykle app/build.gradle):

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

Zadeklaruj uprawnienie `AD_ID`

Aby biblioteka reklam Androida TV miała dostęp do identyfikatora wyświetlania reklam, dodaj ten wiersz do pliku AndroidManifest.xml:

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

Integracja z pakietem SDK PAL

Biblioteka reklam Androida TV używa klasy SignalCollector do zbierania identyfikatorów na urządzeniu, które są wymagane do żądania reklam. SDK usługi PAL korzysta z klasy NonceRequest.Builder, aby odczytywać te sygnały i tworzyć nonce.

Aby skonfigurować bibliotekę reklam Android TV do współpracy z pakietem SDK PAL, dodaj do aplikacji PAL wiersze pogrubione:

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

Analizowanie odpowiedzi VAST

Gdy żądanie reklamy jest wysyłane z użyciem sygnałów z biblioteki reklam Androida TV, serwery reklam Google wysyłają odpowiedź VAST zawierającą tag <Icon> z jednym lub wieloma elementami podrzędnymi <IconClickFallbackImage> dla różnych rozdzielczości ekranu. Aby przeanalizować odpowiedź serwera reklam VAST w formacie XML, wykonaj te instrukcje.

Oto przykładowa struktura VAST 4.2 tagu <Icon> i jego elementów podrzędnych. Odpowiednie dane są oznaczone pogrubieniem.

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

Podobnie <IconClickFallbackImages> można przeanalizować, korzystając z przykładowej struktury VAST 3.0 w przewodniku PAL na temat analizowania odpowiedzi VAST 3.0.

Podczas analizowania pliku VAST utwórz obiekt IconClickFallbackImage dla każdego tagu <IconClickFallbackImage> i wypełnij go za pomocą przeanalizowanych danych za pomocą parametru IconClickFallbackImage.Builder. Podobnie użyj obiektu IconClickFallbackImages.Builder, aby przekazać listę obiektów IconClickFallbackImage do obiektu IconClickFallbackImages, który reprezentuje 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;
  }

Renderowanie AT&C

Biblioteka reklam Androida TV udostępnia metodę AdsControlsManager.handleIconClick() renderowania menu AT&C lub standardowego parametru VAST IconClickFallbackImage.

Ten fragment kodu konfiguruje bibliotekę reklam Android TV, aby renderować menu AT&C i obrazy zastępcze dla kliknięć ikony 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);
    ...
  }
}

Wywołanie AdsControlsManager.handleIconClick() uruchamia funkcję Activity na Androidzie, więc standardowe wywołania cyklu życia, takie jak onPause() i onResume(), można wykorzystać do nasłuchiwania zmian w cyklu życia aktywności.

[Opcjonalnie] Podanie niestandardowego renderera obrazu zastępczego

Jeśli Twoja aplikacja ma specjalne wymagania, takie jak ograniczenia sprzętowe lub ograniczenia związane z UX, możesz ustawić funkcję wywołania zwrotnego za pomocą funkcji AdsControlsManager.setCustomFallbackImageRenderer(). Biblioteka reklam Androida TV zweryfikuje obrazy zastępcze, aby ustalić, czy może użyć dostarczonego niestandardowego modułu renderującego. Renderowanie niestandardowe będzie używane tylko w przypadku parametru VAST IconClickFallbackImage, a nie 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
      ...
    }
  }
  ...
}

Przesyłanie opinii do Google na temat biblioteki reklam na Androidzie TV

Chcielibyśmy poznać Twoje wrażenia związane z integracją i migracją aplikacji na Androida TV. Aby umówić spotkanie z jednym z naszych inżynierów, skontaktuj się z menedżerem konta Google.

Historia wersji

Wersja	Data wydania	Uwagi
1.0.1	2025-01-09	Aktualizacje obsługi przejrzystości reklam i formatów ustawień.
1.0.0	2023-05-16	Dodaje logowanie. Obsługa minSdk została obniżona do poziomu API 21. Aktualizuje obsługę błędów i zależność, aby naprawić problemy z zawieszaniem się.
1.0.0-alpha02	2022-11-17	Zaktualizowano plik manifestu Androida, aby umożliwić opcjonalne korzystanie z funkcji Leanback.
1.0.0-alpha01	2022-09-07	Pierwsza wersja.

Pierwsze kroki z biblioteką reklam na Androidzie TV Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.