نمایش آگهی بومی

پلاتفرم را انتخاب کنید: Android iOS Android (قدیمی)

وقتی آگهی بومی بار می‌شود، GMA Next-Gen SDK شنونده را برای قالب آگهی مربوطه فراخوانی می‌کند. سپس برنامه شما مسئول نمایش آگهی است، اگرچه لزوماً نباید این کار را فوراً انجام دهد. برای آسان‌تر کردن نمایش قالب‌های آگهی تعریف‌شده توسط سیستم، کیت توسعه نرم‌افزار چند منبع مفید ارائه می‌دهد که در زیر شرح داده شده است.

تعریف کردن کلاس NativeAdView

کلاس NativeAdView را تعریف می‌کند. این کلاس یک ViewGroup کلاس است و بالاترین سطح نگهدارنده برای کلاس NativeAdView است. هر نمای آگهی بومی حاوی دارایی‌های آگهی بومی است، مانند عنصر نمای MediaView یا عنصر نمای Title، که باید فرزند شیء NativeAdView باشد.

چیدمان XML

NativeAdView XML به پروژه اضافه کنید:

<com.google.android.libraries.ads.mobile.sdk.nativead.NativeAdView
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="wrap_content">
    <LinearLayout
    android:orientation="vertical">
        <LinearLayout
        android:orientation="horizontal">
          <ImageView
          android:id="@+id/ad_app_icon" />
          <TextView
            android:id="@+id/ad_headline" />
        </LinearLayout>
        <!--Add remaining assets such as the image and media view.-->
    </LinearLayout>
</com.google.android.libraries.ads.mobile.sdk.nativead.NativeAdView>

Jetpack Compose

  1. پوشه JetpackCompose Utilities را اضافه کنید. این پوشه شامل کمک‌کننده‌هایی برای ترکیب‌بندی دارایی‌ها و شیء NativeAdView است.

نوشتن NativeAdView:

  import com.google.android.gms.compose_util.NativeAdAttribution
  import com.google.android.gms.compose_util.NativeAdView

  @Composable
  /** Display a native ad with a user defined template. */
  fun DisplayNativeAdView(nativeAd: NativeAd) {
      NativeAdView {
          // Display the ad attribution.
          NativeAdAttribution(text = context.getString("Ad"))
          // Add remaining assets such as the image and media view.
        }
    }

مدیریت آگهی بومی بارشده

وقتی آگهی بومی بار می‌شود، رویداد فراخوانی را مدیریت کنید، نمای آگهی بومی را گسترش دهید، و آن را به سلسله‌مراتب نما اضافه کنید:

Kotlin

// Build an ad request with native ad options to customize the ad.
val adTypes = listOf(NativeAd.NativeAdType.NATIVE)
val adRequest = NativeAdRequest
  .Builder("/21775744923/example/native", adTypes)
  .build()

val adCallback =
  object : NativeAdLoaderCallback {
    override fun onNativeAdLoaded(nativeAd: NativeAd) {
      activity?.runOnUiThread {

        val nativeAdBinding = NativeAdBinding.inflate(layoutInflater)
        val adView = nativeAdBinding.root
        val frameLayout = myActivityLayout.nativeAdPlaceholder

        // Populate and register the native ad asset views.
        displayNativeAd(nativeAd, nativeAdBinding)

        // Remove all old ad views and add the new native ad
        // view to the view hierarchy.
        frameLayout.removeAllViews()
        frameLayout.addView(adView)
      }
    }
  }

// Load the native ad with our request and callback.
NativeAdLoader.load(adRequest, adCallback)

جاوا

// Build an ad request with native ad options to customize the ad.
List<NativeAd.NativeAdType> adTypes = Arrays.asList(NativeAd.NativeAdType.NATIVE);
NativeAdRequest adRequest = new NativeAdRequest
                                .Builder("/21775744923/example/native", adTypes)
                                .build();

NativeAdLoaderCallback adCallback = new NativeAdLoaderCallback() {
    @Override
    public void onNativeAdLoaded(NativeAd nativeAd) {
      if (getActivity() != null) {
        getActivity()
          .runOnUiThread(() -> {
            // Inflate the native ad view and add it to the view hierarchy.
            NativeAdBinding nativeAdBinding = NativeAdBinding.inflate(getLayoutInflater());
            NativeAdView adView = (NativeAdView) nativeAdBinding.getRoot();
            FrameLayout frameLayout = myActivityLayout.nativeAdPlaceholder;

            // Populate and register the native ad asset views.
            displayNativeAd(nativeAd, nativeAdBinding);

            // Remove all old ad views and add the new native ad
            // view to the view hierarchy.
            frameLayout.removeAllViews();
            frameLayout.addView(adView);
        });
      }
    }
};

// Load the native ad with our request and callback.
NativeAdLoader.load(adRequest, adCallback);

توجه داشته باشید که همه دارایی‌های یک آگهی بومی معین باید در چیدمان NativeAdView ارائه شوند. GMA Next-Gen SDK تلاش می‌کند وقتی دارایی‌های بومی خارج از طرح‌بندی نمای آگهی بومی ارائه می‌شوند، هشداری را ثبت کند.

کلاس‌های نمای آگهی همچنین روش‌هایی را ارائه می‌دهند که برای ثبت نمای استفاده‌شده برای هر دارایی فردی و یکی برای ثبت خود شیء NativeAd استفاده می‌شود. ثبت نماها به این روش به کیت توسعه نرم‌افزار اجازه می‌دهد تا به‌طور خودکار تکالیفی مثل موارد زیر را انجام دهد:

  • کلیک‌های ضبط
  • ثبت ظهورها وقتی اولین پیکسل در صفحه نمایان می‌شود
  • نمایش هم‌پوشانی AdChoices برای طرح‌آگهی‌های جایگزین بومی—درحال‌حاضر محدود به گروهی از ناشران منتخب

نمایش آگهی بومی

مثال زیر نحوه نمایش آگهی بومی را نشان می‌دهد:

Kotlin

private fun displayNativeAd(nativeAd: NativeAd, nativeAdBinding : NativeAdBinding) {
  // Set the native ad view elements.
  val nativeAdView = nativeAdBinding.root
  nativeAdView.advertiserView = nativeAdBinding.adAdvertiser
  nativeAdView.bodyView = nativeAdBinding.adBody
  nativeAdView.callToActionView = nativeAdBinding.adCallToAction
  nativeAdView.headlineView = nativeAdBinding.adHeadline
  nativeAdView.iconView = nativeAdBinding.adAppIcon
  nativeAdView.priceView = nativeAdBinding.adPrice
  nativeAdView.starRatingView = nativeAdBinding.adStars
  nativeAdView.storeView = nativeAdBinding.adStore

  // Set the view element with the native ad assets.
  nativeAdBinding.adAdvertiser.text = nativeAd.advertiser
  nativeAdBinding.adBody.text = nativeAd.body
  nativeAdBinding.adCallToAction.text = nativeAd.callToAction
  nativeAdBinding.adHeadline.text = nativeAd.headline
  nativeAdBinding.adAppIcon.setImageDrawable(nativeAd.icon?.drawable)
  nativeAdBinding.adPrice.text = nativeAd.price
  nativeAd.starRating?.toFloat().let { value ->
    nativeAdBinding.adStars.rating = value
  }
  nativeAdBinding.adStore.text = nativeAd.store

  // Hide views for assets that don't have data.
  nativeAdBinding.adAdvertiser.visibility = getAssetViewVisibility(nativeAd.advertiser)
  nativeAdBinding.adBody.visibility = getAssetViewVisibility(nativeAd.body)
  nativeAdBinding.adCallToAction.visibility = getAssetViewVisibility(nativeAd.callToAction)
  nativeAdBinding.adHeadline.visibility = getAssetViewVisibility(nativeAd.headline)
  nativeAdBinding.adAppIcon.visibility = getAssetViewVisibility(nativeAd.icon)
  nativeAdBinding.adPrice.visibility = getAssetViewVisibility(nativeAd.price)
  nativeAdBinding.adStars.visibility = getAssetViewVisibility(nativeAd.starRating)
  nativeAdBinding.adStore.visibility = getAssetViewVisibility(nativeAd.store)

  // Inform GMA Next-Gen SDK that you have finished populating
  // the native ad views with this native ad.
  nativeAdView.registerNativeAd(nativeAd, nativeAdBinding.adMedia)
}

/**
* Determines the visibility of an asset view based on the presence of its asset.
*
* @param asset The native ad asset to check for nullability.
* @return [View.VISIBLE] if the asset is not null, [View.INVISIBLE] otherwise.
*/
private fun getAssetViewVisibility(asset: Any?): Int {
  return if (asset == null) View.INVISIBLE else View.VISIBLE
}

جاوا

private void displayNativeAd(ad: NativeAd, nativeAdBinding : NativeAdBinding) {
  // Set the native ad view elements.
  NativeAdView nativeAdView = nativeAdBinding.getRoot();
  nativeAdView.setAdvertiserView(nativeAdBinding.adAdvertiser);
  nativeAdView.setBodyView(nativeAdBinding.adBody);
  nativeAdView.setCallToActionView(nativeAdBinding.adCallToAction);
  nativeAdView.setHeadlineView(nativeAdBinding.adHeadline);
  nativeAdView.setIconView(nativeAdBinding.adAppIcon);
  nativeAdView.setPriceView(nativeAdBinding.adPrice);
  nativeAdView.setStarRatingView(nativeAdBinding.adStars);
  nativeAdView.setStoreView(nativeAdBinding.adStore);

  // Set the view element with the native ad assets.
  nativeAdBinding.adAdvertiser.setText(nativeAd.getAdvertiser());
  nativeAdBinding.adBody.setText(nativeAd.getBody());
  nativeAdBinding.adCallToAction.setText(nativeAd.getCallToAction());
  nativeAdBinding.adHeadline.setText(nativeAd.getHeadline());
  if (nativeAd.getIcon() != null) {
      nativeAdBinding.adAppIcon.setImageDrawable(nativeAd.getIcon().getDrawable());
  }
  nativeAdBinding.adPrice.setText(nativeAd.getPrice());
  if (nativeAd.getStarRating() != null) {
      nativeAdBinding.adStars.setRating(nativeAd.getStarRating().floatValue());
  }
  nativeAdBinding.adStore.setText(nativeAd.getStore());

  // Hide views for assets that don't have data.
  nativeAdBinding.adAdvertiser.setVisibility(getAssetViewVisibility(nativeAd.getAdvertiser()));
  nativeAdBinding.adBody.setVisibility(getAssetViewVisibility(nativeAd.getBody()));
  nativeAdBinding.adCallToAction.setVisibility(getAssetViewVisibility(nativeAd.getCallToAction()));
  nativeAdBinding.adHeadline.setVisibility(getAssetViewVisibility(nativeAd.getHeadline()));
  nativeAdBinding.adAppIcon.setVisibility(getAssetViewVisibility(nativeAd.getIcon()));
  nativeAdBinding.adPrice.setVisibility(getAssetViewVisibility(nativeAd.getPrice()));
  nativeAdBinding.adStars.setVisibility(getAssetViewVisibility(nativeAd.getStarRating()));
  nativeAdBinding.adStore.setVisibility(getAssetViewVisibility(nativeAd.getStore()));

  // Inform GMA Next-Gen SDK that you have finished populating
  // the native ad views with this native ad.
  nativeAdView.registerNativeAd(nativeAd, nativeAdBinding.adMedia);
}

/**
* Determines the visibility of an asset view based on the presence of its asset.
*
* @param asset The native ad asset to check for nullability.
* @return {@link View#VISIBLE} if the asset is not null, {@link View#INVISIBLE} otherwise.
*/
private int getAssetViewVisibility(Object asset) {
    return (asset == null) ? View.INVISIBLE : View.VISIBLE;
}

رونهاد AdChoices

وقتی آگهی جایگزین برگردانده می‌شود، رونهاد AdChoices به‌عنوان نمای آگهی توسط کیت توسعه نرم‌افزار اضافه می‌شود. اگر برنامه‌تان از آگهی‌های بومی برای پر کردن فضای آگهی استفاده می‌کند، در گوشه دلخواه نمای آگهی بومی‌تان فضایی برای درج خودکار نشان‌واره AdChoices درنظر بگیرید. همچنین، مهم است که هم‌پوشانی AdChoices دیده شود، بنابراین رنگ‌های پس‌زمینه و تصاویر را به‌درستی انتخاب کنید. برای اطلاعات بیشتر درباره ظاهر و عملکرد هم‌پوشانی، به رهنمودهای پیاده‌سازی آگهی‌های بومی برنامه‌ای مراجعه کنید.

ارجاع آگهی برای آگهی‌های بومی برنامه‌ای

هنگام نمایش آگهی‌های بومی برنامه‌ای، باید اسناد آگهی را نمایش دهید تا نشان دهید که این نما یک آگهی است. در رهنمودهای خط‌مشی ما اطلاعات بیشتری کسب کنید.

کلیک‌های شناسه مجازی

هیچ گرداننده کلیک سفارشی‌ای را در هیچ نمایی روی یا درون نمای آگهی بومی پیاده‌سازی نکنید. کلیک‌ها روی دارایی‌های نمای آگهی توسط کیت توسعه نرم‌افزار مدیریت می‌شود، به‌شرطی که نماهای دارایی را به‌درستی پر و ثبت کنید.

برای گوش دادن به کلیک‌ها، GMA Next-Gen SDK فراخوانی کلیک را پیاده‌سازی کنید:

Kotlin

private fun setEventCallback(nativeAd: NativeAd) {
  nativeAd.adEventCallback =
    object : NativeAdEventCallback {
      override fun onAdClicked() {
        Log.d(Constant.TAG, "Native ad recorded a click.")
      }
    }
}

جاوا

private void setEventCallback(NativeAd nativeAd) {
  nativeAd.setAdEventCallback(new NativeAdEventCallback() {
      @Override
      public void onAdClicked() {
        Log.d(Constant.TAG, "Native ad recorded a click.");
      }
  });
}

ImageScaleType

کلاس MediaView هنگام نمایش تصاویر، خصوصیت ImageScaleType دارد. اگر می‌خواهید نحوه مقیاس‌بندی تصویر را در MediaView تغییر دهید، ImageView.ScaleType مربوطه را بااستفاده از روش setImageScaleType() MediaView تنظیم کنید:

Kotlin

nativeAdViewBinding.mediaView.imageScaleType = ImageView.ScaleType.CENTER_CROP

جاوا

nativeAdViewBinding.mediaView.setImageScaleType(ImageView.ScaleType.CENTER_CROP);

MediaContent

کلاس MediaContent داده‌های مربوط به محتوای رسانه‌ای آگهی بومی را نگه می‌دارد که بااستفاده از کلاس MediaView نمایش داده می‌شود. وقتی که خصوصیت MediaView mediaContent با نمونه MediaContent تنظیم شده باشد:

  • اگر دارایی ویدیویی دردسترس باشد، میان‌گیری می‌شود و پخش آن در MediaView شروع می‌شود. با بررسی hasVideoContent() می‌توانید متوجه شوید که دارایی ویدیویی دردسترس است یا نه.

  • اگر آگهی حاوی دارایی ویدیویی نباشد، دارایی mainImage بارگیری می‌شود و به‌جای آن در MediaView قرار می‌گیرد.

افزودن خلاصه خلاقانه

در برنامه‌های گپ هوش مصنوعی و مکالمه‌ای، GMA Next-Gen SDK دارایی خلاصه خلاقانه (creativeSummary) برای طرح‌آگهی ارائه می‌دهد. می‌توانید آگهی‌ها را با پیام مقدماتی در جریان‌های گپ برنامه‌تان ادغام کنید.

افزودن نمای نوشتار به چیدمان

TextView را برای دارایی خلاصه آگهی در طرح‌بندی دربرگیرنده NativeAdView اضافه کنید:

<TextView
    android:id="@+id/ad_creative_summary"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:textSize="13sp" />

پر کردن و ثبت کردن نما

TextView را با creativeSummary پر کنید و آن را با ویژگی creativeSummaryView در شیء NativeAdView ثبت کنید. ثبت نما، ردیابی کلیک خودکار را برای دارایی خلاصه طرح‌آگهی فعال می‌کند.

Kotlin

private fun populateCreativeSummary(
  nativeAd: NativeAd,
  nativeAdBinding: NativeAdBinding,
  nativeAdView: NativeAdView,
) {
  val summary = nativeAd.creativeSummary
  if (summary == null) {
    nativeAdBinding.adCreativeSummary.visibility = View.GONE
    return
  }

  nativeAdBinding.adCreativeSummary.text = summary
  nativeAdBinding.adCreativeSummary.visibility = View.VISIBLE
  nativeAdView.creativeSummaryView = nativeAdBinding.adCreativeSummary
}

جاوا

private void populateCreativeSummary(
    NativeAd nativeAd, NativeAdBinding nativeAdBinding, NativeAdView nativeAdView) {
  String summary = nativeAd.getCreativeSummary();
  if (summary == null) {
    nativeAdBinding.adCreativeSummary.setVisibility(View.GONE);
    return;
  }

  nativeAdBinding.adCreativeSummary.setText(summary);
  nativeAdBinding.adCreativeSummary.setVisibility(View.VISIBLE);
  nativeAdView.setCreativeSummaryView(nativeAdBinding.adCreativeSummary);
}

پیگیری کلیک و نوشتار اصلاح‌شده

  • پرداخت مستقیم: وقتی رشته دقیق creativeSummary ارائه‌شده توسط کیت توسعه نرم‌افزار را پرداخت می‌کنید، آن را در ویژگی creativeSummaryView داخل محفظه NativeAdView ثبت کنید تا رسیدگی به کلیک کیت توسعه نرم‌افزار فعال شود.
  • مقدمه‌های اصلاح‌شده: اگر برنامه‌تان نوشتار مکالمه‌ای سفارشی را در خلاصه آگهی اصلاح، خلاصه، یا به آن اضافه می‌کند، نوشتار اصلاح‌شده را خارج از ظرف NativeAdView قرار دهید.

نابود کردن آگهی

پس‌از نمایش آگهی بومی، آگهی را ازبین ببرید. مثال زیر یک آگهی بومی را ازبین می‌برد:

Kotlin

nativeAd.destroy()

جاوا

nativeAd.destroy();

کد آگهی بومی آزمایشی

آگهی‌های فروخته‌شده مستقیم

اگر می‌خواهید آگهی‌های بومی فروخته‌شده مستقیم را آزمایش کنید، می‌توانید از این شناسه واحد آگهی Ad Manager استفاده کنید:

/21775744923/example/native

این واحد آگهی برای ارائه آگهی‌های نمونه نصب برنامه و محتوا، و همچنین قالب آگهی بومی سفارشی با دارایی‌های زیر پیکربندی شده است:

  • Headline (text)
  • MainImage (image)
  • زیرنویس (نوشتار)

شناسه الگوی قالب آگهی بومی سفارشی 10063170 است.

آگهی‌های بومی پرکننده

تأمین آگهی Ad Exchange به گروهی از ناشران منتخب محدود است. برای آزمایش رفتار آگهی‌های پر کردن فضای بومی، از این واحد آگهی «مدیر آگهی» استفاده کنید:

/21775744923/example/native-backfill

این برنامه آگهی‌های نصب برنامه و محتوای نمونه را که شامل هم‌پوشانی AdChoices است ارائه می‌دهد.

به‌یاد داشته باشید که قبل‌از فعال شدن، کدتان را به‌روز کنید تا به شناسه‌های واحد آگهی و الگوی واقعی‌تان ارجاع دهد.

مراحل بعدی

موضوعات زیر را کاوش کنید:

مثال

برنامه نمونه را که نحوه استفاده از GMA Next-Gen SDK را نشان می‌دهد بارگیری و اجرا کنید.