이 페이지는 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 메뉴가 TV 런처 앱에 의해 시스템 오버레이로 렌더링되어 짧은 URL, 광고에 대한 자세한 내용을 확인할 수 있는 빠른 응답 (QR 코드), 동일한 광고 표시를 중지하는 버튼을 표시합니다.

Google TV 광고 아이콘은 AdChoices 아이콘과 동일한 VAST 아이콘 렌더링 요구사항을 사용하여 렌더링해야 합니다.

대체 텍스트

Google TV 광고 아이콘을 클릭하면 사용자에게 이 광고에 대한 정보 (ATA) 웹페이지의 짧은 URL과 QR 코드가 표시됩니다.

대체 텍스트

Android TV 광고 라이브러리 통합

ATV 광고 라이브러리 가져오기

앱 수준 Gradle 파일(일반적으로 app/build.gradle)에 Android TV 광고 라이브러리의 다음 종속 항목을 추가합니다.

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 클래스를 사용하여 광고를 요청하는 데 필요한 기기의 식별자를 수집합니다. 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 광고 서버는 다양한 화면 해상도에 맞는 하나 이상의 <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;
  }

렌더링 이용약관

Android TV 광고 라이브러리는 AT&C 메뉴 또는 표준 VAST IconClickFallbackImage를 렌더링하는 AdsControlsManager.handleIconClick() 메서드를 제공합니다.

다음 스니펫은 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()와 같은 표준 수명 주기 콜백을 사용하여 활동 수명 주기 변경사항을 리슨할 수 있습니다.

[선택사항] 맞춤 대체 이미지 렌더러 제공

앱에 하드웨어 제한이나 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 광고 라이브러리에 관한 의견 보내기

Android TV 앱 통합 및 이전 경험에 관한 의견을 보내 주세요. Google 계정 관리자에게 문의하여 Google 엔지니어와의 회의를 예약하세요.

출시 내역

버전	출시일	참고
1.0.1	2025-01-09	지원되는 광고 투명성 및 제어 형식을 업데이트했습니다.
1.0.0	2023-05-16	로깅을 추가합니다. minSdk 지원을 API 수준 21로 낮춥니다. 비정상 종료를 수정하기 위해 오류 처리 및 종속 항목을 업데이트합니다.
1.0.0-alpha02	2022-11-17	Leanback 기능을 선택사항으로 허용하는 Android 매니페스트를 업데이트합니다.
1.0.0-alpha01	2022-09-07	첫 출시입니다.

Android TV 광고 라이브러리 시작하기 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.