Trang này được dịch bởi Cloud Translation API.

Bắt đầu sử dụng thư viện quảng cáo trên Android TV

Thư viện quảng cáo Android TV cung cấp giao diện người dùng để người dùng kiểm soát trải nghiệm quảng cáo trên Google TV. Hướng dẫn này giải thích cách tích hợp thư viện quảng cáo Android TV vào ứng dụng Android TV PAL hiện có của bạn.

Điều kiện tiên quyết

Xem hết hướng dẫn Bắt đầu sử dụng
SDK Android PAL phiên bản 20.0.1 trở lên

Tính minh bạch và chế độ kiểm soát quảng cáo

Thư viện quảng cáo Android TV cung cấp chức năng hiển thị tính minh bạch của quảng cáo và kiểm soát các tính năng (AT&C) trong khoảng nghỉ quảng cáo. Khi người dùng tương tác với biểu tượng Quảng cáo trên TV của Google trong quảng cáo trong luồng, trình đơn AT&C sẽ được hiển thị dưới dạng lớp phủ hệ thống của ứng dụng trình chạy TV, hiển thị URL ngắn, phản hồi nhanh (mã QR) để tìm hiểu thêm về quảng cáo và nút để ngừng hiển thị cùng một quảng cáo.

Biểu tượng Quảng cáo trên TV do Google phân phát phải được hiển thị bằng cách sử dụng các yêu cầu hiển thị biểu tượng VAST giống như biểu tượng AdChoices.

Văn bản thay thế

Khi nhấp vào biểu tượng Quảng cáo trên TV của Google, người dùng sẽ thấy một URL ngắn và mã QR dẫn đến trang web Thông tin về quảng cáo này (ATA).

Văn bản thay thế

Tích hợp thư viện quảng cáo Android TV

Nhập thư viện quảng cáo ATV

Thêm phần phụ thuộc sau đây cho thư viện quảng cáo Android TV vào tệp Gradle cấp ứng dụng, thường là app/build.gradle:

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

Khai báo quyền `AD_ID`

Để thư viện quảng cáo Android TV có thể truy cập vào Mã nhận dạng cho quảng cáo, hãy thêm dòng sau vào AndroidManifest.xml:

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

Tích hợp với SDK PAL

Thư viện quảng cáo Android TV sử dụng lớp SignalCollector để thu thập các giá trị nhận dạng trên thiết bị cần thiết để yêu cầu quảng cáo. SDK PAL sử dụng lớp NonceRequest.Builder để đọc các tín hiệu này và tạo một số chỉ dùng một lần.

Thêm các dòng in đậm vào ứng dụng PAL để thiết lập thư viện quảng cáo Android TV nhằm hoạt động với SDK PAL:

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

Phân tích cú pháp phản hồi VAST

Khi một yêu cầu quảng cáo được thực hiện bằng các tín hiệu của thư viện quảng cáo Android TV, máy chủ quảng cáo của Google sẽ gửi một phản hồi VAST chứa thẻ <Icon> với một hoặc nhiều <IconClickFallbackImage> con cho nhiều độ phân giải màn hình. Làm theo hướng dẫn phân tích cú pháp phản hồi XML VAST để phân tích cú pháp VAST.

Dưới đây là cấu trúc VAST 4.2 mẫu của thẻ <Icon> và các thẻ con của thẻ này, với dữ liệu liên quan được in in đậm.

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

Tương tự, bạn có thể phân tích cú pháp <IconClickFallbackImages> bằng cách sử dụng cấu trúc VAST 3.0 mẫu trong hướng dẫn PAL để phân tích cú pháp phản hồi VAST 3.0.

Khi phân tích cú pháp VAST, hãy tạo một đối tượng IconClickFallbackImage cho mỗi thẻ <IconClickFallbackImage> và điền dữ liệu đã phân tích cú pháp vào đối tượng đó bằng IconClickFallbackImage.Builder. Tương tự, hãy sử dụng IconClickFallbackImages.Builder để truyền danh sách đối tượng IconClickFallbackImage vào đối tượng IconClickFallbackImages đại diện cho thẻ <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;
  }

Điều khoản và điều kiện của Render

Thư viện quảng cáo Android TV cung cấp phương thức AdsControlsManager.handleIconClick() để hiển thị trình đơn AT&C hoặc IconClickFallbackImage VAST tiêu chuẩn.

Đoạn mã sau đây thiết lập thư viện quảng cáo Android TV để hiển thị trình đơn AT&C và hình ảnh dự phòng khi nhấp vào biểu tượng 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);
    ...
  }
}

Việc gọi AdsControlsManager.handleIconClick() sẽ khởi động Activity của Android để các lệnh gọi lại vòng đời tiêu chuẩn như onPause() và onResume() có thể được dùng để theo dõi các thay đổi trong vòng đời hoạt động.

[Không bắt buộc] Cung cấp trình kết xuất hình ảnh dự phòng tuỳ chỉnh

Nếu ứng dụng của bạn có các yêu cầu đặc biệt, chẳng hạn như hạn chế về phần cứng hoặc quy tắc ràng buộc về trải nghiệm người dùng, thì bạn có thể đặt hàm gọi lại bằng cách sử dụng AdsControlsManager.setCustomFallbackImageRenderer(). Thư viện quảng cáo Android TV sẽ xác minh hình ảnh dự phòng để xác định xem thư viện có thể sử dụng trình kết xuất tuỳ chỉnh được cung cấp hay không. Hoạt động hiển thị tuỳ chỉnh sẽ chỉ được dùng cho IconClickFallbackImage VAST chứ không phải trình đơn 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
      ...
    }
  }
  ...
}

Gửi ý kiến phản hồi cho Google về thư viện quảng cáo Android TV

Chúng tôi muốn biết ý kiến phản hồi của bạn về trải nghiệm tích hợp và di chuyển ứng dụng Android TV. Hãy liên hệ với người quản lý tài khoản của Google để lên lịch họp với một trong các kỹ sư của chúng tôi.

Lịch sử phát hành

Phiên bản	Ngày phát hành	Ghi chú
1.0.1	2025-01-09	Cập nhật các định dạng kiểm soát và tính minh bạch của quảng cáo được hỗ trợ.
1.0.0	2023-05-16	Thêm tính năng ghi nhật ký. Giảm mức hỗ trợ minSdk xuống API cấp 21. Cập nhật phần phụ thuộc và cách xử lý lỗi để khắc phục sự cố.
1.0.0-alpha02	2022-11-17	Cập nhật Tệp kê khai Android để cho phép tính năng Leanback là không bắt buộc.
1.0.0-alpha01	2022-09-07	Bản phát hành đầu tiên.

Bắt đầu sử dụng thư viện quảng cáo trên Android TV Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.