פורמטים מותאמים אישית של מודעות מותאמות

פורמטים מותאמים אישית של מודעות מותאמות

בנוסף לפורמטים המותאמים על ידי המערכת, בעלי אתרים ב-Ad Manager יכולים ליצור פורמטים משלהם של מודעות מותאמות על ידי הגדרת רשימות מותאמות אישית של נכסים. אלו נקראים פורמטים מותאמים אישית של מודעות מותאמות וניתן להשתמש בהם עם מודעות שמורות. כך בעלי אתרים יכולים להעביר נתונים מובְנים שרירותיים לאפליקציות שלהם. המודעות האלה מיוצגות על ידי האובייקט NativeCustomFormatAd.

טעינת פורמטים מותאמים אישית של מודעות מותאמות

במדריך זה מוסבר איך לטעון ולהציג פורמטים מותאמים אישית של מודעות מותאמות.

בניית AdLoader

בדומה למודעות מותאמות, פורמטים מותאמים אישית של מודעות מותאמות נטענים באמצעות המחלקה AdLoader:

Java

AdLoader adLoader = new AdLoader.Builder(context, "/6499/example/native")
    .forCustomFormatAd("10063170",
      new NativeCustomFormatAd.OnCustomFormatAdLoadedListener() {
          @Override
          public void onCustomFormatAdLoaded(NativeCustomFormatAd ad) {
              // Show the custom format and record an impression.
          }
      },
      new NativeCustomFormatAd.OnCustomClickListener() {
          @Override
          public void onCustomClick(NativeCustomFormatAd ad, String s) {
              // Handle the click action
          }
      })
    .withAdListener( ... )
    .withNativeAdOptions( ... )
    .build();

Kotlin

val adLoader = AdLoader.Builder(this, "/6499/example/native")
        .forCustomFormatAd("10063170",
            { ad ->
                // Show the custom format and record an impression.
            },
            { ad, s ->
            // Handle the click action
            })
        .withAdListener( ... )
        .withNativeAdOptions( ... )
        .build()

השיטה forCustomFormatAd מגדירה את AdLoader לבקשת פורמטים מותאמים אישית של מודעות מותאמות. יש שלושה פרמטרים שמועברים ל-method:

  • המזהה של הפורמט המותאם אישית של המודעות המותאמות שהלקוח AdLoader צריך לבקש. לכל פורמט מותאם אישית של מודעה מותאמת משויך מזהה. הפרמטר הזה מציין באיזה פורמט האפליקציה צריכה לבקש מ-AdLoader.
  • להפעיל OnCustomFormatAdLoadedListener כשמודעה נטענת בהצלחה.
  • אפשרות OnCustomClickListener להפעלה כשהמשתמש מקיש על המודעה או לוחץ עליה. למידע נוסף על המאזין הזה, קראו את הקטע "טיפול בקליקים ובחשיפות" שבהמשך.

מאחר שניתן להגדיר ליחידת מודעות אחת להציג יותר מפורמט אחד של קריאייטיב, ניתן לקרוא ל-forCustomFormatAd כמה פעמים עם מזהי פורמט ייחודיים, כדי להכין את הכלי לטעינת מודעות ליותר מפורמט אחד אפשרי של מודעות מותאמות.

מזהה של פורמט מותאם אישית של מודעות מותאמות

מזהה הפורמט שמשמש לזיהוי פורמט מותאם אישית של מודעות מותאמות מופיע בממשק המשתמש של Ad Manager בקטע Native (מודעה מותאמת) בתפריט הנפתח הצגה (הצגה):

כל מזהה של פורמט מותאם אישית של מודעה מותאמת מופיע לצד השם שלו. לחיצה על אחד מהשמות תעביר אתכם למסך פרטים שבו יופיע מידע על השדות של הפורמט:

מכאן ניתן להוסיף, לערוך ולהסיר שדות ספציפיים. שימו לב לשם של כל נכס. השם הוא המפתח המשמש לקבלת הנתונים של כל נכס בעת הצגת הפורמט המותאם אישית של המודעות המותאמות.

פורמטים מותאמים אישית של מודעות מותאמות לרשת המדיה

פורמטים מותאמים אישית של מודעות מותאמות שונים מפורמטים שמוגדרים על ידי המערכת, בכך שבעלי אתרים יכולים להגדיר בעצמם את רשימת הנכסים שמרכיבים את המודעה. לכן, תהליך ההצגה של תצוגה כזו שונה בכמה אופנים מפורמטים שהוגדרו על ידי המערכת:

  1. המחלקה NativeCustomFormatAd מיועדת לטפל בכל אחד מהפורמטים המותאמים אישית של מודעות מותאמות שהגדרתם ב-Ad Manager, ולכן היא לא כוללת את השם "getters" עבור הנכסים. במקום זאת, הוא מציע שיטות כמו getText ו-getImage שכוללות את שם השדה כפרמטר.
  2. אין סיווג ייעודי של צפייה במודעות כמו NativeAdView שאפשר להשתמש בו עם NativeCustomFormatAd. אתם יכולים להשתמש בכל פריסה שמתאימה לחוויית המשתמש שלכם.
  3. אין סיווג ייעודי של ViewGroup, כך שלא צריך לרשום אף אחת מהתצוגות שמשמשות אותך להצגת הנכסים שיצורפו למודעה. הפעולה הזו חוסכת כמה שורות קוד בזמן הצגת המודעה, אבל בהמשך תצטרכו לעשות קצת עבודה נוספת כדי לטפל בקליקים.

לפניכם פונקציה לדוגמה שמציגה NativeCustomFormatAd:

Java

public void displayCustomFormatAd (ViewGroup parent,
                                     NativeCustomFormatAd customFormatAd) {
    // Inflate a layout and add it to the parent ViewGroup.
    LayoutInflater inflater = (LayoutInflater) parent.getContext()
            .getSystemService(Context.LAYOUT_INFLATER_SERVICE);
    View adView = inflater.inflate(R.layout.custom_format_ad, parent);

    // Locate the TextView that will hold the value for "Headline" and
    // set its text.
    TextView myHeadlineView = (TextView) adView.findViewById(R.id.headline);
    myHeadlineView.setText(customFormatAd.getText("Headline"));

    // Locate the ImageView that will hold the value for "MainImage" and
    // set its drawable.
    Button myMainImageView = (ImageView) adView.findViewById(R.id.main_image);
    myMainImageView.setImageDrawable(
            customFormatAd.getImage("MainImage").getDrawable());

    ...
    // Continue locating views and displaying assets until finished.
    ...
}

Kotlin

public fun displayCustomFormatAd (parent: ViewGroup,
                                customFormatAd: NativeCustomFormatAd) {
    val adView = layoutInflater
            .inflate(R.layout.ad_simple_custom_format, null)

    val myHeadlineView = adView.findViewById<TextView>(R.id.headline)
    myHeadlineView.setText(customFormatAd.getText("Headline"));

    // Locate the ImageView that will hold the value for "MainImage" and
    // set its drawable.
    val myMainImageView = adView.findViewById(R.id.main_image);
    myMainImageView.setImageDrawable(
            customFormatAd.getImage("MainImage").drawable;

    ...
    // Continue locating views and displaying assets until finished.
    ...
}

מודעת וידאו מותאמת לפורמטים מותאמים אישית של מודעות מותאמות

כשאתם יוצרים פורמט מותאם אישית, אפשר להגדיר אותו כפורמט שמתאים לווידאו.

ביישום האפליקציה, תוכלו להשתמש ב-NativeCustomFormatAd.getMediaContent() כדי לקבל את תוכן המדיה. לאחר מכן צריך להתקשר למספר setMediaContent() כדי להגדיר את תוכן המדיה בתצוגת המדיה כתצוגה של המדיה. אם המודעה לא כוללת תוכן וידאו, צריך ליצור תוכניות חלופיות להצגת המודעה בלי סרטון.

הדוגמה הבאה בודקת אם המודעה כוללת תוכן וידאו, ומציגה תמונה במקומה אם אין סרטון זמין:

Java

// Called when a custom native ad loads.
@Override
public void onCustomFormatAdLoaded(final NativeCustomFormatAd ad) {

  MediaContent mediaContent = ad.getMediaContent();

  // Assumes you have a FrameLayout in your view hierarchy with the id media_placeholder.
  FrameLayout mediaPlaceholder = (FrameLayout) findViewById(R.id.media_placeholder);

  // Apps can check the MediaContent's hasVideoContent property to determine if the
  // NativeCustomFormatAd has a video asset.
  if (mediaContent != null && mediaContent.hasVideoContent()) {
    MediaView mediaView = new MediaView(mediaPlaceholder.getContext());
    mediaView.setMediaContent(mediaContent);
    mediaPlaceholder.addView(mediaView);

    // Create a new VideoLifecycleCallbacks object and pass it to the VideoController. The
    // VideoController will call methods on this object when events occur in the video
    // lifecycle.
    VideoController vc = mediaContent.getVideoController();
    vc.setVideoLifecycleCallbacks(
        new VideoController.VideoLifecycleCallbacks() {
          @Override
          public void onVideoEnd() {
            // Publishers should allow native ads to complete video playback before
            // refreshing or replacing them with another ad in the same UI location.
            super.onVideoEnd();
          }
        });
  } else {
    ImageView mainImage = new ImageView(this);
    mainImage.setAdjustViewBounds(true);
    mainImage.setImageDrawable(ad.getImage("MainImage").getDrawable());
    mediaPlaceholder.addView(mainImage);
    mainImage.setOnClickListener(
        new View.OnClickListener() {
          @Override
          public void onClick(View view) {
            ad.performClick("MainImage");
          }
        });
  }
}

Kotlin

// Called when a custom native ad loads.
NativeCustomFormatAd.OnCustomFormatAdLoadedListener { ad ->

  val mediaContent = ad.mediaContent

  // Apps can check the MediaContent's hasVideoContent property to determine if the
  // NativeCustomFormatAd has a video asset.
  if (mediaContent != null && mediaContent.hasVideoContent()) {
    val mediaView = MediaView(mediaPlaceholder.getContest())
    mediaView.mediaContent = mediaContent

    val videoController = mediaContent.videoController

    // Create a new VideoLifecycleCallbacks object and pass it to the VideoController. The
    // VideoController will call methods on this object when events occur in the video
    // lifecycle.
    if (videoController != null) {
      videoController.videoLifecycleCallbacks =
        object : VideoController.VideoLifecycleCallbacks() {
          override fun onVideoEnd() {
            // Publishers should allow native ads to complete video playback before refreshing
            // or replacing them with another ad in the same UI location.
            super.onVideoEnd()
          }
        }
    }
  } else {
    val mainImage = ImageView(this)
    mainImage.adjustViewBounds = true
    mainImage.setImageDrawable(ad.getImage("MainImage")?.drawable)

    mainImage.setOnClickListener { ad.performClick("MainImage") }
    customTemplateBinding.simplecustomMediaPlaceholder.addView(mainImage)
  }
}

למידע נוסף על התאמה אישית של חוויית הווידאו של מודעה מותאמת מותאמת אישית, אפשר לעיין במאמר MediaContent.

הורידו את הדוגמה לעיבוד בהתאמה אישית ב-Ad Manager כדי לראות דוגמה פעילה של מודעת וידאו מותאמת לפעולה.

קליקים וחשיפות בפורמטים מותאמים אישית של מודעות מותאמות

בפורמטים מותאמים אישית של מודעות מותאמות, האפליקציה שלכם אחראית לתיעוד חשיפות ולדיווח על אירועי קליקים ל-Google Mobile Ads SDK.

תיעוד חשיפות

כדי לתעד חשיפה של מודעה בפורמט מותאם אישית, צריך לבצע קריאה ל-method recordImpression ב-NativeCustomFormatAd המתאים:

myCustomFormatAd.recordImpression();

אם האפליקציה שלכם תפעיל בטעות את השיטה פעמיים באותה מודעה, ה-SDK מונע באופן אוטומטי תיעוד של חשיפה כפולה בבקשה אחת.

דיווח על קליקים

כדי לדווח ל-SDK על כך שהתרחש קליק בתצוגת נכס, צריך לקרוא ל-method performClick ב-NativeCustomFormatAd המתאים ולהזין את שם הנכס שעליו המשתמש לחץ. לדוגמה, אם יש לכם נכס בפורמט המותאם אישית שנקרא "MainImage" ואתם רוצים לדווח על קליק על ImageView שתואם לנכס הזה, הקוד ייראה כך:

myCustomFormatAd.performClick("MainImage");

לתשומת ליבכם, אין צורך לקרוא לשיטה הזו עבור כל תצוגה מפורטת שמשויכת למודעה שלכם. אם היה שדה אחר בשם 'Caption' שהיה אמור להופיע, אבל המשתמש לא לחץ עליו או הקיש עליו, האפליקציה לא הייתה צריכה להפעיל את performClick עבור התצוגה של הנכס.

תגובה לפעולות מותאמות אישית של קליקים

כשלוחצים על מודעה בפורמט מותאם אישית, מתבצע ניסיון לבצע שלוש תגובות אפשריות מה-SDK לפי הסדר הבא:

  1. צריך להפעיל את OnCustomClickListener מ-AdLoader, אם צוין מזהה כזה.
  2. לכל אחת מכתובות ה-URL של קישורי העומק במודעה, נסו לאתר מקודד תוכן ולהתחיל את הראשון לפתרון.
  3. פותחים דפדפן ומנווטים לכתובת היעד המסורתית של המודעה.

השיטה forCustomFormatAd מקבלת OnCustomClickListener. אם מעבירים אובייקט מאזין, ה-SDK מפעיל את שיטת onCustomClick שלו ולא מבצע פעולה נוספת. עם זאת, אם מעבירים ערך null בתור ה-listener, ה-SDK חוזר לקישור העומק ו/או לכתובות היעד שרשומים במודעה.

פונקציות ה-C listener בהתאמה אישית של קליקים מאפשרות לאפליקציה להחליט מה הפעולה הטובה ביותר לבצע בתגובה לקליק, בין אם מדובר בעדכון ממשק המשתמש, הפעלת פעילות חדשה או רישום של הקליק בלבד. הנה דוגמה שפשוט מתעדת את ביצוע הקליק:

Java

AdLoader adLoader = new AdLoader.Builder(context, "/6499/example/native")
    .forCustomFormatAd("10063170",
      new NativeCustomFormatAd.OnCustomFormatAdLoadedListener() {
        // Display the ad.
      },
      new NativeCustomFormatAd.OnCustomClickListener() {
          @Override
          public void onCustomClick(NativeCustomFormatAd ad, String assetName) {
            Log.i("MyApp", "A custom click just happened for " + assetName + "!");
          }
      }).build();

Kotlin

val adLoader = AdLoader.Builder(this, "/6499/example/native")
    .forCustomFormatAd("10063170",
        { ad ->
            // Display the ad.
        },
        { ad, assetName ->
                Log.i("MyApp", "A custom click just happened for $assetName!")
    }).build()

אולי נראה מוזר שקיימים מאזינים לקליקים מותאמים אישית. אחרי הכול, האפליקציה שלכם אמרה ל-SDK שקרה קליק, אז למה ה-SDK צריך לחזור ולדווח על כך לאפליקציה?

רצף המידע הזה שימושי מכמה סיבות, אבל הדבר החשוב ביותר הוא שה-SDK נשאר בשליטה על התגובה לקליק. לדוגמה, הוא יכול לבצע פינג אוטומטי לכתובות URL למעקב של צד שלישי שהוגדרו עבור הקריאייטיב, ולטפל במשימות אחרות מאחורי הקלעים, ללא קוד נוסף.