تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

عرض NativeAd

عند تحميل إعلان مُدمَج مع المحتوى، تستدعي "حزمة تطوير البرامج (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.
        }
    }

التعامل مع إعلان aad الأصلي الذي تم تحميله

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

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)

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("/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. تحاول حزمة "SDK لإعلانات Google على الأجهزة الجوّالة" تسجيل تحذير عند عرض مواد العرض المدمجة مع المحتوى خارج تنسيق عرض الإعلان المدمج مع المحتوى.

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

تسجيل النقرات
تسجيل مرّات الظهور عندما يكون أول بكسل مرئيًا على الشاشة
عرض تراكب AdChoices لمواد إبداعية ممتلئة الشاشة في الفيديوهات السابقة ، وهي متاحة حاليًا لمجموعة محدّدة من الناشرين

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

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

تحديد مصدر الإعلانات للإعلانات المدمجة مع المحتوى الآلية

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

مثال على الرمز البرمجي

في ما يلي خطوات عرض إعلان مدمج مع المحتوى:

أنشئ مثيلًا لفئة NativeAdView.
لكلّ مادة عرض إعلان يتم عرضها:
1. املأ عرض مادة العرض بمادة العرض في عنصر الإعلان.
2. سجِّل عرض مادة العرض باستخدام فئة NativeAdView.
سجِّل عنصر الإعلان في فئة NativeAdView.

في ما يلي مثال على دالة تعرِض NativeAd:

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 the Google Mobile Ads 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
}

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 the Google Mobile Ads 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;
}

في ما يلي المهام الفردية:

تضخيم التنسيق

Kotlin

 // Remove all old ad views when loading a new native ad.
 binding.nativeViewContainer.removeAllViews()

 // Inflate the native ad view and add it to the view hierarchy.
 val nativeAdBinding = NativeAdBinding.inflate(layoutInflater)
 binding.nativeViewContainer.addView(nativeAdBinding.root)

Java

 // Remove all old ad views when loading a new native ad.
 binding.nativeViewContainer.removeAllViews();

 // Inflate the native ad view and add it to the view hierarchy.
 NativeAdBinding nativeAdBinding = NativeAdBinding.inflate(getLayoutInflater());
 binding.nativeViewContainer.addView(nativeAdBinding.getRoot());

يضخّم هذا الرمز تنسيق XML يحتوي على طرق عرض لعرض إعلان مضمّن ، ثمّ يحدّد مكان مرجع إلى NativeAdView. تجدر الإشارة إلى أنّه يمكنك أيضًا إعادة استخدام NativeAdView حالي إذا كان متوفّرًا في المقتطف أو النشاط، أو إنشاء مثيل ديناميكيًا بدون استخدام ملف تنسيق.

تعبئة مشاهدات مواد العرض وتسجيلها

يحدِّد نموذج الرمز هذا موقع العرض المستخدَم لعرض العنوان، ويضبط نصه باستخدام مادة عرض السلسلة التي يوفّرها عنصر الإعلان، ويُسجِّله باستخدام عنصر NativeAdView:
Kotlin
```
 nativeAdView.headlineView = nativeAdBinding.adHeadline
 nativeAdBinding.adHeadline.text = nativeAd.headline
 nativeAdBinding.adHeadline.visibility = getAssetViewVisibility(nativeAd.headline)
```
Java
```
 nativeAdView.setHeadlineView(nativeAdBinding.adHeadline);
 nativeAdBinding.adHeadline.setText(nativeAd.getHeadline());
 nativeAdBinding.adHeadline.setVisibility(getAssetViewVisibility(nativeAd.getHeadline()));
```
يجب تكرار عملية تحديد موضع العرض وضبط قيمته وتسجيله باستخدام فئة عرض الإعلان لكل مادة عرض يوفّرها عنصر الإعلان المدمج الذي سيعرضه التطبيق.
التعامل مع النقرات

لا تنفِّذ أيّ معالجات نقرات مخصّصة على أيّ مشاهدات فوق عرض الإعلانات المدمجة أو داخله. تعالج حزمة تطوير البرامج (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.");
       }
   });
 }
```
تسجيل MediaView

عليك استخدام مادة العرض MediaView بدلاً من مادة العرض ImageView إذا كنت تريد تضمين مادة عرض صورة رئيسية في تنسيق إعلانك المدمج.
Kotlin
```
// Get the media asset view.
val mediaView = nativeAdBinding.adMedia
```
Java
```
// Get the media asset view.
MediaView mediaView = nativeAdBinding.adMedia;
```
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 بدلاً من ذلك.
في حال استخدام disableImageDownloading(true)، تكون قيمة mainImage هي null ويجب ضبط السمة mainImage على الصورة التي تم تنزيلها يدويًا. يُرجى العلم أنّه لن يتم استخدام هذه الصورة إلا في حال عدم توفّر مادة عرض فيديو.

تسجيل عنصر الإعلان المدمج مع المحتوى

تسجِّل هذه الخطوة الأخيرة عنصر الإعلان المدمج مع المحتوى في العرض المسؤول عن عرضه، بالإضافة إلى عرض مادة عرض محتوى الوسائط.

Kotlin

 // Inform the Google Mobile Ads SDK that you have finished populating
 // the native ad views with this native ad and media content asset.
 nativeAdView.registerNativeAd(nativeAd, mediaView)

Java

 // Inform the Google Mobile Ads SDK that you have finished populating
 // the native ad views with this native ad and media content asset.
 nativeAdView.registerNativeAd(nativeAd, mediaView);

إتلاف الإعلان

عند الانتهاء من عرض إعلانك المدمج مع المحتوى، يجب إزالته حتى تتم معالجة الإعلان بشكل صحيح.

Kotlin

nativeAd.destroy()

Java

nativeAd.destroy();

اختبار رمز الإعلانات المدمجة مع المحتوى

الإعلانات المَبيعة مباشرةً

إذا أردت اختبار أداء الإعلانات المدمجة مع المحتوى المُباعة مباشرةً، يمكنك استخدام رقم تعريف الوحدة الإعلانية هذا في "مدير إعلانات Google":

/21775744923/example/native

تم إعداده لعرض نماذج من إعلانات تثبيت التطبيقات وإعلانات المحتوى، بالإضافة إلى شكل إعلان مُدمَج مع المحتوى مخصّص باستخدام مواد العرض التالية:

العنوان (نص)
MainImage (صورة)
الترجمة (نص)

رقم تعريف النموذج لشكل الإعلان المدمج مع المحتوى المخصّص هو 10063170.

الإعلانات المدمجة مع المحتوى في "ملء الفراغات"

تقتصر ميزة "إضافة البيانات السابقة" في Ad Exchange على مجموعة محدّدة من الناشرين. لاختبار سلوك الإعلانات المدمجة مع المحتوى في الفيديوهات التي تمّ عرضها سابقًا، استخدِم هذه الوحدة الإعلانية في "مدير إعلانات Google":

/21775744923/example/native-backfill

ويعرض التطبيق نماذج من إعلانات تثبيت التطبيقات وإعلانات المحتوى التي تتضمّن تراكب "خيارات الإعلان".

تذكَّر تعديل الرمز للإشارة إلى معرّفات الوحدة الإعلانية والنموذج الفعلية قبل نشر الحملة.

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

يمكنك استكشاف المواضيع التالية:

خصوصية المستخدم

مثال

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

إعلانات مدمجة مع المحتوى تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

عرض NativeAd

تحديد فئة NativeAdView

تنسيق XML

Jetpack Compose

التعامل مع إعلان aad الأصلي الذي تم تحميله

Kotlin

Java

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

تحديد مصدر الإعلانات للإعلانات المدمجة مع المحتوى الآلية

مثال على الرمز البرمجي

Kotlin

Java

Kotlin

Java

Kotlin

Java

Kotlin

Java

Kotlin

Java

ImageScaleType

Kotlin

Java

MediaContent

Kotlin

Java

إتلاف الإعلان

Kotlin

Java

اختبار رمز الإعلانات المدمجة مع المحتوى

الإعلانات المَبيعة مباشرةً

الإعلانات المدمجة مع المحتوى في "ملء الفراغات"

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

مثال

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

تحديد فئة `NativeAdView`