با کتابخانه تبلیغات Android TV شروع کنید

کتابخانه تبلیغات Android TV یک رابط کاربری برای کاربران فراهم می کند تا تجربه تبلیغات خود را در Google TV کنترل کنند. این راهنما نحوه ادغام کتابخانه تبلیغات Android TV را در برنامه PAL Android TV موجود خود توضیح می دهد.

پیش نیازها

• راهنمای شروع را کامل کنید
• Android PAL SDK نسخه 20.0.1 یا بالاتر

شفافیت و کنترل تبلیغات

کتابخانه تبلیغات Android TV عملکردی را برای شفافیت تبلیغات ارائه می دهد و ویژگی ها (AT&C) را در طول وقفه های تبلیغاتی کنترل می کند. هنگامی که کاربران با نماد تبلیغات تلویزیونی Google در حین تبلیغات درون جریانی تعامل برقرار می‌کنند، منوی AT&C به‌عنوان یک پوشش سیستمی توسط برنامه راه‌انداز تلویزیون نمایش داده می‌شود و نشانی اینترنتی کوتاه، یک پاسخ سریع (کد QR) را نشان می‌دهد تا اطلاعات بیشتری درباره آگهی پیدا کند. و دکمه ای برای توقف نمایش همان تبلیغ.

نماد تبلیغات تلویزیونی Google باید با استفاده از همان الزامات ارائه نماد VAST مانند نماد AdChoices ارائه شود.

با کلیک بر روی نماد تبلیغات تلویزیونی Google یک URL کوتاه و کد QR برای صفحه وب درباره این آگهی (ATA) به کاربر نشان می دهد.

کتابخانه تبلیغات Android TV را ادغام کنید

کتابخانه تبلیغات ATV را وارد کنید

وابستگی زیر را برای کتابخانه تبلیغات Android TV به فایل Gradle در سطح برنامه خود، معمولا app/build.gradle اضافه کنید:

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

مجوز 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 استفاده می کند.

برای راه‌اندازی کتابخانه تبلیغات Android TV برای کار با PAL 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();
    ...
  }

پاسخ VAST را تجزیه کنید

هنگامی که یک درخواست تبلیغ با سیگنال‌های کتابخانه تبلیغات Android TV انجام می‌شود، سرورهای تبلیغات Google یک پاسخ VAST حاوی برچسب <Icon> را با یک یا چند فرزند <IconClickFallbackImage> برای وضوح‌های مختلف صفحه ارسال می‌کنند. برای تجزیه VAST، دستورالعمل‌های پاسخ‌های VAST XML را تجزیه کنید.

در اینجا یک نمونه ساختار 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;
  }

AT&C را رندر کنید

کتابخانه تبلیغات Android TV یک روش AdsControlsManager.handleIconClick() برای ارائه یک منوی AT&C یا یک استاندارد VAST IconClickFallbackImage ارائه می کند.

قطعه زیر کتابخانه تبلیغات 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.0	16-05-2023	ورود به سیستم را اضافه می کند. پشتیبانی minSdk را به سطح API 21 کاهش می دهد. مدیریت خطا و وابستگی ها را برای رفع خرابی ها به روز می کند.
1.0.0-alpha02	17-11-2022	مانیفست Android را به‌روزرسانی می‌کند و به ویژگی Leanback اجازه می‌دهد اختیاری باشد.
1.0.0-alpha01	07-09-2022	انتشار اولیه