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

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

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

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

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

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

يجب عرض رمز إعلانات التلفزيون من 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.1'
}

الإفصاح عن إذن AD_ID

لكي تتمكّن مكتبة إعلانات Android TV من الوصول إلى Advertising ID، أضِف السطر التالي إلى 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 للعمل مع حزمة تطوير البرامج (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> واحد أو متعدّد لدرجات دقة شاشة مختلفة. اتّبِع تعليمات تحليل استجابات 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> واملأه بال data المحلَّلة باستخدام 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 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.1	2025-01-09	تعديلات على شفافية الإعلانات المتوافقة وأشكال عناصر التحكّم
1.0.0	2023-05-16	إضافة تسجيل خفض الحد الأدنى لإصدار حزمة تطوير البرامج (SDK) المتوافقة مع minSdk إلى المستوى 21 من واجهة برمجة التطبيقات تعديلات على معالجة الأخطاء والتبعيات لإصلاح الأعطال
1.0.0-alpha02	2022-11-17	تعديل بيان Android للسماح بأن تكون ميزة Leanback اختيارية
1.0.0-alpha01	2022-09-07	الإصدار الأولي