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

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

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

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

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

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

  1. צריך לכלול את הסוג NativeAdType.CUSTOM_NATIVE כסוג מודעה ב-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, בקטע מודעות מותאמות בתפריט הנפתח הצגה:

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

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

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

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

  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

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

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

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

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

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

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

Kotlin

// Record an impression.
customNativeAd.recordImpression()

Java

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

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

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

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

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

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