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

בחירת פלטפורמה: Android iOS Android (גרסה קודמת)

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

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

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

טעינה של מודעה מותאמת אישית

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

Java

AdLoader adLoader = new AdLoader.Builder(this, "/21775744923/example/native")
    .forCustomFormatAd("12387226",
        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
          }
        })
    .forCustomFormatAd("12406343",
        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
          }
        })
    .build();

Kotlin

val adLoader = AdLoader.Builder(this, "/21775744923/example/native")
  .forCustomFormatAd(
    "12387226",
    { customFormatAd ->
      // Show the custom format and record an impression.
    },
    { customFormatAd, s ->
      // Handle the click action
    })
  .forCustomFormatAd(
    "12406343",
    { customFormatAd ->
      // Show the custom format and record an impression.
    },
    { customFormatAd, s ->
      // Handle the click action
    })
  .build()

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

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

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

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

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

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

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

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

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

  1. נכסי טקסט ונכסי תמונות זמינים דרך פונקציות ה-getter‏ getText() ו-getImage(), שמקבלות את שם השדה כפרמטר.
  2. אין מחלקה ייעודית של ViewGroup לרישום ב-Google, ולכן צריך לתעד חשיפות וקליקים באופן ידני.
  3. למודעה מותאמת אישית יש תוכן מדיה בגודל null אם המודעה לא מכילה נכס וידאו.

הנה דוגמה לפונקציה שמציגה 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() כדי להגדיר את תוכן המדיה בתצוגת המדיה. אם המודעה כוללת תוכן מדיה מסוג null, צריך לתכנן תוכניות חלופיות להצגת המודעה בלי סרטון.

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

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)
  }
}

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

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

עיבוד של הסמל של AdChoices

כחלק מהתמיכה ב-Digital Services Act (חוק השירותים הדיגיטליים, DSA), מודעות בהזמנה שמוצגות באזור הכלכלי האירופי (EEA) צריכות לכלול את הסמל של AdChoices וקישור לדף "בנוגע למודעה הזו" של Google. כשמטמיעים מודעות מותאמות אישית, אתם אחראים להציג את הסמל של AdChoices. מומלץ לבצע את השלבים לעיבוד ולהגדרה של רכיב ה-click listener של הסמל של AdChoices כשמעבדים את הנכסים העיקריים שמצורפים למודעה.

בדוגמה הבאה, אנחנו מניחים שהגדרתם רכיב <ImageView /> בהיררכיית התצוגות כדי להציג את הלוגו של AdChoices.

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android">
    <ImageView
        android:id="@+id/adChoices"
        android:layout_width="15dp"
        android:layout_height="15dp"
        android:adjustViewBounds="true"
        android:contentDescription="AdChoices icon." />
</LinearLayout>

בדוגמאות הבאות מוצג איך להציג את הסמל של AdChoices ולהגדיר את התנהגות הקליקים המתאימה.

Java

private AdSimpleCustomTemplateBinding customTemplateBinding;

private void populateAdView(final NativeCustomFormatAd nativeCustomFormatAd) {
  // Render the AdChoices icon.
  String adChoicesKey = NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW;
  NativeAd.Image adChoicesAsset = nativeCustomFormatAd.getImage(adChoicesKey);
  if (adChoicesAsset == null) {
    customTemplateBinding.adChoices.setVisibility(View.GONE);
  } else {
    customTemplateBinding.adChoices.setVisibility(View.VISIBLE);
    customTemplateBinding.adChoices.setImageDrawable(adChoicesAsset.getDrawable());

    // Enable clicks on AdChoices.
    customTemplateBinding.adChoices.setOnClickListener(
        new View.OnClickListener() {
          @Override
          public void onClick(View v) {
            nativeCustomFormatAd.performClick(adChoicesKey);
          }
        });
  }
  ...
}

Kotlin

private lateinit var customTemplateBinding: AdSimpleCustomTemplateBinding

private fun populateAdView(nativeCustomFormatAd: NativeCustomFormatAd) {
  // Render the AdChoices icon.
  val adChoicesKey = NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW
  val adChoicesAsset = nativeCustomFormatAd.getImage(adChoicesKey)
  if (adChoicesAsset == null) {
    customTemplateBinding.adChoices.visibility = View.GONE
  } else {
    customTemplateBinding.adChoices.setImageDrawable(adChoicesAsset.drawable)
    customTemplateBinding.adChoices.visibility = View.VISIBLE

    // Enable clicks on AdChoices.
    customTemplateBinding.adChoices.setOnClickListener {
      nativeCustomFormatAd.performClick(adChoicesKey)
    }
  }
  ...
}

תיעוד חשיפות ודיווח על קליקים

האפליקציה אחראית לתעד חשיפות ולדווח על אירועים מסוג קליק ל-Google Mobile Ads SDK (Legacy).

חשיפות של הקלטות

כדי לתעד חשיפה של מודעה מותאמת אישית, צריך להפעיל את השיטה recordImpression() של המודעה:

myCustomFormatAd.recordImpression();

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

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

כדי לדווח ל-SDK שהתרחש קליק על תצוגת נכס, צריך להפעיל את ה-method‏ performClick() של המודעה. ציינו את שם הנכס שעליו המשתמש לחץ באמצעות אותה מחרוזת שהגדרתם בממשק המשתמש של Ad Manager.

myCustomFormatAd.performClick("MainImage");

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

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

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

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

כדי להטמיע פעולת קליק בהתאמה אישית, צריך לספק OnCustomClickListener:

Java

AdLoader adLoader = new AdLoader.Builder(context, "/21775744923/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, "/21775744923/example/native")
    .forCustomFormatAd("10063170",
        { ad ->
            // Display the ad.
        },
        { ad, assetName ->
                Log.i("MyApp", "A custom click just happened for $assetName!")
    }).build()

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

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