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

בנוסף לפורמטים המותאמים שמוגדרים על ידי המערכת, בעלי תוכן דיגיטלי ב-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 בתפריט הנפתח Delivery:

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

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

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

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

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

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

הצגת סמל AdChoices

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

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

האפליקציה שלכם אחראית לתיעוד החשיפות ולדיווח על אירועי קליקים אל Google Mobile Ads 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");
      }
    });

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