إعلانات مدمجة مع المحتوى

عند تحميل إعلان مُدمَج مع المحتوى، تستدعي حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة (الإصدار التجريبي) أداة معالجة الأحداث الخاصة بشكل الإعلان المعنيّ. ويكون تطبيقك مسؤولاً بعد ذلك عن عرض الإعلان، مع أنّه ليس بالضرورة أن يعرضه على الفور. لتسهيل عرض أشكال الإعلانات المحدّدة من النظام، توفّر حزمة SDK بعض المراجع المفيدة، كما هو موضّح أدناه.

تحديد فئة NativeAdView

حدِّد فئة NativeAdView. هذا الصف هو صف ViewGroup وهو الحاوية ذات المستوى الأعلى لصف NativeAdView. يحتوي كل عرض لإعلان مدمج مع المحتوى على مواد عرض خاصة بهذا النوع من الإعلانات، مثل عنصر العرض MediaView أو عنصر العرض Title، ويجب أن يكونا عنصرَين ثانويَين للكائن NativeAdView.

تنسيق XML

أضِف ملف XML NativeAdView إلى مشروعك:

<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

أدرِج وحدة JetpackComposeDemo/compose-util التي تتضمّن أدوات مساعدة لإنشاء NativeAdView ومواد العرض الخاصة به.

باستخدام الوحدة compose-util، أنشئ 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("ca-app-pub-3940256099942544/2247696110", 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)

Java

// 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("ca-app-pub-3940256099942544/2247696110", 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. تحاول حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة (الإصدار التجريبي) تسجيل تحذير عند عرض مواد عرض الإعلانات المدمجة مع المحتوى خارج تخطيط عرض الإعلان المدمج مع المحتوى.

توفّر فئات عرض الإعلانات أيضًا طرقًا تُستخدَم لتسجيل طريقة العرض المستخدَمة لكل مادة عرض فردية، وطريقة لتسجيل العنصر NativeAd نفسه. يتيح تسجيل طرق العرض بهذه الطريقة لحزمة تطوير البرامج (SDK) معالجة مهام تلقائيًا، مثل:

  • تسجيل النقرات
  • تسجيل مرّات الظهور عندما تكون وحدة البكسل الأولى مرئية على الشاشة
  • عرض تراكب "خيارات الإعلان"

عرض الإعلان المدمج مع المحتوى

يوضّح المثال التالي كيفية عرض إعلان مدمج مع المحتوى:

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 Google Mobile Ads SDK (beta) 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
}

Java

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 Google Mobile Ads SDK (beta) 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;
}

تراكب "خيارات الإعلان"

تضيف حزمة تطوير البرامج (SDK) شارة "خيارات الإعلان" إلى كلّ مشاهدة للإعلان. اترك مساحة في الزاوية المفضّلة من طريقة عرض الإعلان الأصلي لشعار "خيارات الإعلان" الذي يتم إدراجه تلقائيًا. من المهم أيضًا أن تكون شارة "خيارات الإعلان" ظاهرة بوضوح للمستخدمين، لذا يجب اختيار ألوان الخلفية والصور بشكل مناسب. لمزيد من المعلومات عن مظهر التراكب ووظيفته، يُرجى الاطّلاع على أوصاف حقول الإعلانات المدمجة مع المحتوى.

التصنيف كإعلان

يجب عرض تصنيف الإعلان للإشارة إلى أنّ المشاهدة هي إعلان. مزيد من المعلومات في إرشادات السياسة

التعامل مع النقرات

لا تنفِّذ أي معالجات نقرات مخصّصة على أي طرق عرض فوق طريقة عرض الإعلان الأصلي أو بداخلها. تتعامل حزمة تطوير البرامج (SDK) مع النقرات على مواد عرض الإعلان طالما أنّك تملأ مواد عرض الإعلان وتسجّلها بشكل صحيح.

للاستماع إلى النقرات، نفِّذ وظيفة معاودة الاتصال للنقرات في "حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة" (الإصدار التجريبي):

Kotlin

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

Java

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

Java

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

MediaContent

تحتوي الفئة MediaContent على البيانات المرتبطة بمحتوى الوسائط الخاص بالإعلان الأصلي، والذي يتم عرضه باستخدام الفئة MediaView. عند ضبط السمة MediaView mediaContent باستخدام مثيل MediaContent:

  • إذا كانت مادة عرض الفيديو متاحة، يتم تخزينها مؤقتًا ويبدأ تشغيلها داخل MediaView. يمكنك معرفة ما إذا كانت مادة عرض الفيديو متوفرة من خلال التحقّق من hasVideoContent().

  • إذا لم يكن الإعلان يتضمّن مادة عرض فيديو، يتم تنزيل مادة العرض mainImage ووضعها داخل MediaView بدلاً من ذلك.

إيقاف عرض إعلان

بعد عرض إعلان مدمج مع المحتوى، عليك إتلاف الإعلان. يوضّح المثال التالي كيفية إيقاف عرض إعلان أصلي:

Kotlin

nativeAd.destroy()

Java

nativeAd.destroy();

الخطوات التالية

يمكنك الاطّلاع على المواضيع التالية:

مثال

نزِّل تطبيق المثال وشغِّله، وهو يوضّح كيفية استخدام حزمة SDK لإعلانات Google على الأجهزة الجوّالة (الإصدار التجريبي).