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

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

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

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

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

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

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

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

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

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

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