بدء استخدام مكتبة إعلانات Android TV

توفّر مكتبة إعلانات Android TV واجهة مستخدم تتيح للمستخدمين التحكّم في تجربة الإعلان على Google TV يشرح هذا الدليل كيفية دمج Android TV مكتبة الإعلانات في تطبيق PAL Android TV الحالي.

المتطلبات الأساسية

• إكمال دليل البدء
• الإصدار 20.0.1 من حزمة تطوير البرامج (SDK) لنظام التشغيل Android PAL أو إصدار أحدث

شفافية الإعلانات وعناصر التحكّم فيها

توفّر مكتبة إعلانات Android TV وظائف لعرض شفافية الإعلانات عناصر التحكّم (AT&C) أثناء الفواصل الإعلانية. عندما يتفاعل المستخدمون مع الإعلانات التلفزيونية من Google أثناء عرض الإعلانات، يتم عرض قائمة AT&C كنظام ظهور عنوان URL مختصر وردّ سريع (رمز استجابة سريعة) يظهر على سطح الفيديو بجانب تطبيق مشغّل التلفزيون لمعرفة مزيد من المعلومات عن الإعلان وزر لإيقاف عرض الإعلان نفسه.

يجب عرض رمز الإعلانات التلفزيونية من Google باستخدام رمز VAST نفسه. متطلبات العرض مثل AdChoices .

يؤدي النقر على رمز الإعلانات التلفزيونية من Google إلى عرض عنوان URL قصير ورمز استجابة سريعة للمستخدم صفحة لمحة عن هذا الإعلان (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"/>

الدمج مع حزمة تطوير البرامج (SDK) الخاصة بنظام PAL

تستخدم مكتبة إعلانات Android TV SignalCollector الفئة لجمع المعرّفات على الجهاز المطلوب لطلب الإعلانات. فريق PAL تستخدم حزمة SDK NonceRequest.Builder لقراءة هذه الإشارات وإنشاء رقم غير متكرر.

أضِف الأسطر الخطيرة إلى تطبيق 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، سينتج عن ذلك سترسل الخوادم استجابة VAST تحتوي على علامة <Icon> مع علامة عدة أطفال <IconClickFallbackImage> لدرجات دقة مختلفة للشاشة. متابعة استجابات XML الخاصة بنموذج VAST للتحليل التعليمات لتحليل نموذج عرض إعلانات الفيديو (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;
  }

عرض 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() يمكن استخدامها للاستماع إلى تغير مراحل النشاط.

[اختياري] توفير عارض صور احتياطي مخصّص

إذا كانت هناك متطلبات خاصة لتطبيقك، مثل قيود الأجهزة أو تجربة المستخدم القيود، يمكنك تعيين دالة استدعاء باستخدام 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
      ...
    }
  }
  ...
}

تقديم ملاحظات إلى Google عن مكتبة إعلانات Android TV

نتطلّع إلى معرفة ملاحظاتك بشأن عملية الدمج نقل بيانات تطبيقات Android TV. تواصَل مع مدير حسابك على Google لتحديد موعد. لاجتماع مع أحد مهندسينا.

سجلّ الإصدارات

الإصدار	تاريخ الإصدار	ملاحظات
1.0.0	2023-05-16	يضيف التسجيل. خفض دعم minSdk إلى المستوى 21 من واجهة برمجة التطبيقات. يعمل على تحديث معالجة الأخطاء والتبعيات لإصلاح الأعطال.
1.0.0-alpha02	2022-11-17	تحديث بيان Android بما يسمح Leanback أن تكون الميزة اختيارية.
1.0.0-alpha01	2022-09-07	الإصدار الأولي.