เริ่มต้นใช้งานไลบรารีโฆษณา Android TV

คลังโฆษณา Android TV มีอินเทอร์เฟซผู้ใช้เพื่อให้ผู้ใช้ควบคุมประสบการณ์การใช้งานโฆษณาใน Google TV ได้ คู่มือนี้จะอธิบายวิธีผสานรวมคลังโฆษณา Android TV เข้ากับแอป PAL Android TV ที่มีอยู่

ข้อกำหนดเบื้องต้น

ความโปร่งใสและการควบคุมโฆษณา

ไลบรารีโฆษณา Android TV มีฟังก์ชันการทำงานเพื่อแสดงผลความโปร่งใสของโฆษณาและควบคุมฟีเจอร์ (AT&C) ระหว่างช่วงพักโฆษณา เมื่อผู้ใช้โต้ตอบกับไอคอนโฆษณาทีวีจาก Google ในระหว่างโฆษณาในสตรีม ระบบจะแสดงเมนู AT&C เป็นภาพซ้อนทับโดยแอป Launcher ของทีวี ซึ่งจะแสดง URL แบบสั้น คิวอาร์โค้ด (Quick Response) เพื่อดูข้อมูลเพิ่มเติมเกี่ยวกับโฆษณา และปุ่มหยุดแสดงโฆษณาเดียวกัน

ไอคอนโฆษณาทีวีโดย Google ควรแสดงผลโดยใช้ข้อกําหนดการแสดงผลไอคอน VAST เดียวกันกับไอคอนAdChoices

ข้อความ Alt

การคลิกไอคอนโฆษณาทีวีโดย Google จะแสดง URL แบบสั้นและคิวอาร์โค้ดของหน้าเว็บเกี่ยวกับโฆษณานี้ (ATA) ให้ผู้ใช้เห็น

ข้อความ Alt

ผสานรวมคลังโฆษณา Android TV

นําเข้าคลังโฆษณา ATV

เพิ่ม Dependency ต่อไปนี้สำหรับคลังโฆษณา Android TV ลงในไฟล์ Gradle ระดับแอป ซึ่งโดยปกติจะเป็น app/build.gradle

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

ประกาศสิทธิ์ AD_ID

หากต้องการให้คลังโฆษณา Android TV เข้าถึงรหัสการโฆษณา ให้เพิ่มบรรทัดต่อไปนี้ลงใน 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 จะส่งการตอบกลับ VAST ที่มีแท็ก <Icon> ที่มี <IconClickFallbackImage> ย่อยอย่างน้อย 1 รายการสําหรับความละเอียดหน้าจอที่แตกต่างกัน ทําตามวิธีการแยกวิเคราะห์การตอบกลับ VAST XML เพื่อแยกวิเคราะห์ VAST

ต่อไปนี้คือตัวอย่างโครงสร้าง VAST 4.2 ของแท็ก <Icon> และแท็กย่อย โดยมีข้อมูลที่เกี่ยวข้องเป็นตัวหนา

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

ข้อกำหนดและเงื่อนไขของ Render

คลังโฆษณา Android TV มีวิธีแสดงผลเมนู AT&C หรือ IconClickFallbackImage มาตรฐานของ VASTAdsControlsManager.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() จะเริ่มต้น Activity ของ Android เพื่อให้ใช้การเรียกกลับวงจรที่ทำงานตามปกติ เช่น onPause() และ onResume() เพื่อฟังการเปลี่ยนแปลงวงจรของกิจกรรมได้

[ไม่บังคับ] ระบุโปรแกรมแสดงผลรูปภาพสำรองที่กำหนดเอง

หากแอปมีข้อกําหนดพิเศษ เช่น ข้อจํากัดของฮาร์ดแวร์หรือข้อจํากัด UX คุณสามารถตั้งค่าฟังก์ชันการเรียกกลับได้โดยใช้ AdsControlsManager.setCustomFallbackImageRenderer() คลังโฆษณา Android TV จะยืนยันรูปภาพสำรองเพื่อระบุว่าสามารถใช้โปรแกรมแสดงผลที่กําหนดเองได้หรือไม่ ระบบจะใช้การแสดงผลที่กำหนดเองสำหรับ VAST IconClickFallbackImage เท่านั้น และจะไม่ใช้กับเมนู 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
      ...
    }
  }
  ...
}

แสดงความคิดเห็นเกี่ยวกับคลังโฆษณา Android TV กับ Google

เราต้องการความคิดเห็นเกี่ยวกับประสบการณ์ของคุณในการผสานรวมและการย้ายข้อมูลแอป Android TV โปรดติดต่อผู้จัดการฝ่ายดูแลลูกค้าของ Google เพื่อนัดหมายการประชุมกับวิศวกรของเรา

ประวัติรุ่น

เวอร์ชัน วันที่เผยแพร่ หมายเหตุ
1.0.1 2025-01-09
  • อัปเดตรูปแบบความโปร่งใสและการควบคุมโฆษณาที่รองรับ
1.0.0 2023-05-16
  • เพิ่มการบันทึก
  • ลดการรองรับ minSdk เป็น API ระดับ 21
  • อัปเดตการจัดการข้อผิดพลาดและทรัพยากร Dependency เพื่อแก้ไขข้อขัดข้อง
1.0.0-alpha02 2022-11-17
  • อัปเดตไฟล์ Manifest ของ Android เพื่อทำให้ฟีเจอร์ Leanback เป็นฟีเจอร์ที่ไม่บังคับ
1.0.0-alpha01 2022-09-07
  • การเผยแพร่ครั้งแรก