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

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

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

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

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

פיתוח AdLoader

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

Java

AdLoader adLoader = new AdLoader.Builder(context, "/21775744923/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, "/21775744923/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:

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

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

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

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

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

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

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

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

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

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

עיבוד (רנדר) של סמל AdChoices

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

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

חשוב: צריך להגדיר את סמל AdChoices בגודל של לפחות 15 על 15 פיקסלים.

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

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

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

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

בהטמעה של האפליקציה, אפשר להשתמש ב-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.

תיעוד חשיפות

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

myCustomFormatAd.recordImpression();

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

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

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

myCustomFormatAd.performClick("MainImage");

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

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

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

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

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

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

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

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

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