איך להתחיל להשתמש בספריית המודעות של Android TV

ספריית המודעות של Android TV מספקת ממשק משתמש שמאפשר למשתמשים לשלוט בחוויית הצפייה במודעות ב-Google TV. במדריך הזה מוסבר איך לשלב את ספריית המודעות של Android TV באפליקציית PAL ל-Android TV הקיימת.

דרישות מוקדמות

• קוראים את המדריך תחילת העבודה
• Android PAL SDK מגרסה 20.0.1 ואילך

שקיפות ואמצעי בקרה במודעות

ספריית המודעות של Android TV מספקת פונקציונליות להצגת שקיפות של מודעות ולתכונות בקרה (AT&C) במהלך ההפסקות למודעות. כשמשתמשים מקישים על הסמל מודעות לטלוויזיה של Google במהלך הצגת מודעות וידאו In-stream, תפריט בקרת ההודעות והבקשות מוצג כשכבת-על של המערכת על ידי אפליקציית מרכז האפליקציות של הטלוויזיה. בתפריט מוצגים כתובת URL קצרה, קוד QR לקבלת מידע נוסף על המודעה ולחצן להפסקת הצגת אותה המודעה.

צריך להציג את הסמל של TV Ads by Google לפי אותן דרישות להצגת סמלי VAST כמו הסמל של AdChoices.

לחיצה על הסמל TV Ads by Google מציגה למשתמש כתובת URL קצרה וקוד QR לדף האינטרנט מידע על המודעה הזו (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 לגשת למזהה הפרסום, צריך להוסיף את השורה הבאה לקובץ 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> עבור רזולוציות מסך שונות. כדי לנתח את ה-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;
  }

עיבוד התנאים וההגבלות

בספריית המודעות של 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	הוספת רישום ביומן. הפחתת התמיכה ב-minSdk לרמת API ‏21. עדכונים בטיפול בשגיאות וביחסי התלות כדי לתקן קריסות.
1.0.0-alpha02	2022-11-17	עדכון של Android Manifest שמאפשר להפוך את התכונה Leanback לאפשרות אופציונלית.
1.0.0-alpha01	2022-09-07	הגרסה הראשונית.