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

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

הערה: המחלקה NativeCustomFormatAd לא תומכת בקבלת האובייקט ResponseInfo או החבילה extras.

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

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

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

כדי לטעון מודעה מותאמת אישית שמוצגת באופן טבעי:

1. כוללים את NativeAdType.CUSTOM_NATIVE type כסוג מודעה ב-NativeAdRequest.

2. מגדירים את מזהה הפורמט של המודעה המותאמת בהתאמה אישית.

Kotlin

val adRequest =
  NativeAdRequest.Builder("AD_UNIT_ID", listOf(NativeAdType.CUSTOM_NATIVE))
    .setCustomFormatIds(listOf("CUSTOM_NATIVE_FORMAT_ID"))
    .build()

// Load the native ad with the ad request and callback.
NativeAdLoader.load(
  adRequest,
  object : NativeAdLoaderCallback {
    override fun onCustomNativeAdLoaded(customNativeAd: CustomNativeAd) {
      // TODO: Store the custom native ad.
    }

    override fun onAdFailedToLoad(adError: LoadAdError) {}
  },
)

Java

NativeAdRequest adRequest =
    new NativeAdRequest.Builder("AD_UNIT_ID", List.of(NativeAd.NativeAdType.CUSTOM_NATIVE))
        .setCustomFormatIds(Arrays.asList("CUSTOM_NATIVE_FORMAT_ID"))
        .build();

// Load the native ad with the ad request and callback.
NativeAdLoader.load(
    adRequest,
    new NativeAdLoaderCallback() {
      @Override
      public void onCustomNativeAdLoaded(@NonNull CustomNativeAd customNativeAd) {
        // TODO: Store the custom native ad.
      }

      @Override
      public void onAdFailedToLoad(@NonNull LoadAdError adError) {}
    });

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

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

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

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

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

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

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

בדוגמה הזו אפשר לראות איך להציג CustomNativeAd:

Kotlin

private fun displayCustomNativeAd(customNativeAd: CustomNativeAd, context: Context) {
  // Render the text elements.

  // The `customNativeAdBinding` is the layout binding for the ad container that
  // contains all `CustomNativeAd` assets.
  customNativeAdBinding.headline.text = customNativeAd.getText("Headline")
  customNativeAdBinding.caption.text = customNativeAd.getText("Caption")

  // If the main asset is an image, render it with an ImageView.
  val imageView = ImageView(context)
  imageView.adjustViewBounds = true
  imageView.setImageDrawable(customNativeAd.getImage("MainImage")?.drawable)
  imageView.setOnClickListener { customNativeAd.performClick("MainImage") }
  customNativeAdBinding.mediaPlaceholder.addView(imageView)

  // Render the ad choices icon.
  renderAdChoices(customNativeAd)

  // Record an impression.
  customNativeAd.recordImpression()
}

Java

private void displayCustomNativeAd(CustomNativeAd customNativeAd, Context context) {
  // Render the text elements.

  // The `customNativeAdBinding` is the layout binding for the ad container that
  // contains all `CustomNativeAd` assets.
  if (customNativeAdBinding != null) {
    customNativeAdBinding.headline.setText(customNativeAd.getText("Headline"));
    customNativeAdBinding.caption.setText(customNativeAd.getText("Caption"));

    ImageView imageView = new ImageView(context);
    imageView.setAdjustViewBounds(true);
    imageView.setImageDrawable(customNativeAd.getImage("MainImage").getDrawable());
    imageView.setOnClickListener(
        new View.OnClickListener() {
          @Override
          public void onClick(View v) {
            customNativeAd.performClick("MainImage");
          }
        });
    customNativeAdBinding.mediaPlaceholder.addView(imageView);

    // Render the ad choices icon.
    renderAdChoices(customNativeAd);

    // Record an impression.
    customNativeAd.recordImpression();
  }
}

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

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

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

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

Kotlin

private fun displayVideoCustomNativeAd(customNativeAd: CustomNativeAd, context: Context) {
  // Check whether the custom native ad has video content.
  val mediaContent = customNativeAd.mediaContent
  if (mediaContent != null && mediaContent.hasVideoContent) {
    // Render the media content in a MediaView.
    val mediaView = MediaView(context)
    mediaView.mediaContent = mediaContent
    customNativeAdBinding.mediaPlaceholder.addView(mediaView)
  } else {
    // Fall back to other assets defined on your custom native ad.
    val imageView = ImageView(context)
    imageView.adjustViewBounds = true
    imageView.setImageDrawable(customNativeAd.getImage("MainImage")?.drawable)
    customNativeAdBinding.mediaPlaceholder.addView(imageView)
  }

  // Record an impression.
  customNativeAd.recordImpression()
}

Java

private void displayVideoCustomNativeAd(CustomNativeAd customNativeAd, Context context) {
  // Check whether the custom native ad has video content.
  MediaContent mediaContent = customNativeAd.getMediaContent();
  if (mediaContent != null && mediaContent.getHasVideoContent()) {
    // Render the media content in a MediaView.
    MediaView mediaView = new MediaView(context);
    mediaView.setMediaContent(mediaContent);
    customNativeAdBinding.mediaPlaceholder.addView(mediaView);
  } else {
    // Fall back to other assets defined on your custom native ad.
    ImageView imageView = new ImageView(context);
    imageView.setAdjustViewBounds(true);
    imageView.setImageDrawable(customNativeAd.getImage("MainImage").getDrawable());
    customNativeAdBinding.mediaPlaceholder.addView(imageView);
  }

  // Record an impression.
  customNativeAd.recordImpression();
}

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

הצגת סמל AdChoices

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

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

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

<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 ואיך להגדיר את התנהגות הקליק המתאימה.

Kotlin

private fun renderAdChoices(customNativeAd: CustomNativeAd) {
  // Render the AdChoices image.
  val adChoiceAsset = customNativeAd.getImage(NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW)
  if (adChoiceAsset != null) {
    customNativeAdBinding.adchoices.setImageDrawable(adChoiceAsset.drawable)
    customNativeAdBinding.adchoices.visibility = View.VISIBLE
    customNativeAdBinding.adchoices.setOnClickListener {
      // Handle click. See the next section for more details.
      customNativeAd.performClick(NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW)
    }
  } else {
    customNativeAdBinding.adchoices.visibility = View.GONE
  }
}

Java

private void renderAdChoices(CustomNativeAd customNativeAd) {
  // Render the AdChoices image.
  Image adChoiceAsset =
      customNativeAd.getImage(NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW);
  if (adChoiceAsset != null) {
    if (customNativeAdBinding != null) {
      customNativeAdBinding.adchoices.setImageDrawable(adChoiceAsset.getDrawable());
      customNativeAdBinding.adchoices.setVisibility(View.VISIBLE);
      customNativeAdBinding.adchoices.setOnClickListener(
          new View.OnClickListener() {
            @Override
            public void onClick(View v) {
              // Handle click.
              customNativeAd.performClick(NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW);
            }
          });
    }
  } else {
    if (customNativeAdBinding != null) {
      customNativeAdBinding.adchoices.setVisibility(View.GONE);
    }
  }
}

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

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

האחריות על תיעוד החשיפות ודיווח על אירועי קליקים מוטלת על האפליקציה באמצעות GMA Next-Gen SDK.

תיעוד חשיפות

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

Kotlin

// Record an impression.
customNativeAd.recordImpression()

Java

// Record an impression.
customNativeAd.recordImpression();

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

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

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

Kotlin

imageView.setOnClickListener { customNativeAd.performClick("MainImage") }

Java

imageView.setOnClickListener(
    new View.OnClickListener() {
      @Override
      public void onClick(View v) {
        customNativeAd.performClick("MainImage");
      }
    });

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

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

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

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

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

Kotlin

customNativeAd.onCustomClickListener =
  object : OnCustomClickListener {
    override fun onCustomClick(assetName: String) {
      // Perform your custom action.
    }
  }

Java

customNativeAd.setOnCustomClickListener(
    new OnCustomClickListener() {
      @Override
      public void onCustomClick(@NonNull String assetName) {
        // Perform your custom action.
      }
    });

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

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