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

اختيار النظام الأساسي: Android

عند تحميل إعلان مدمج مع المحتوى، Google Mobile Ads SDK تستدعي المستمع لشكل الإعلان المقابل. بعد ذلك، يكون تطبيقك مسؤولاً عن عرض الإعلان، ولكن ليس بالضرورة أن يتم ذلك على الفور. لتسهيل عرض أشكال الإعلانات التي يحدّدها النظام، توفّر حزمة SDK بعض المراجع المفيدة، كما هو موضّح أدناه.

تحديد فئة `NativeAdView`

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

تنسيق XML

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

<com.google.android.gms.ads.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.gms.ads.nativead.NativeAdView>

Jetpack Compose

أدرِج مجلد 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.
        }
    }

التعامل مع "الإعلان المدمج مع المحتوى" الذي تم تحميله

عند تحميل "إعلان مدمج مع المحتوى"، تعامَل مع حدث معاودة الاتصال، واعرض طريقة عرض "الإعلان المدمج مع المحتوى"، وأضِفها إلى تسلسل العرض الهرمي:

جافا

AdLoader.Builder builder = new AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
    .forNativeAd(new NativeAd.OnNativeAdLoadedListener() {
        @Override
        public void onNativeAdLoaded(NativeAd nativeAd) {
            // Assumes you have a placeholder FrameLayout in your View layout
            // (with ID fl_adplaceholder) where the ad is to be placed.
            FrameLayout frameLayout =
                findViewById(R.id.fl_adplaceholder);
            // Assumes that your ad layout is in a file call native_ad_layout.xml
            // in the res/layout folder
            NativeAdView adView = (NativeAdView) getLayoutInflater()
                .inflate(R.layout.native_ad_layout, null);
            // This method sets the assets into the ad view.
            displayNativeAd(nativeAd, adView);
            frameLayout.removeAllViews();
            frameLayout.addView(adView);
        }
});

Kotlin

val builder = AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
    .forNativeAd { nativeAd ->
        // Assumes you have a placeholder FrameLayout in your View layout
        // (with ID fl_adplaceholder) where the ad is to be placed.
        val frameLayout: FrameLayout = findViewById(R.id.fl_adplaceholder)
        // Assumes that your ad layout is in a file call native_ad_layout.xml
        // in the res/layout folder
        val adView = layoutInflater
                .inflate(R.layout.native_ad_layout, null) as NativeAdView
        // This method sets the assets into the ad view.
        displayNativeAd(nativeAd, adView)
        frameLayout.removeAllViews()
        frameLayout.addView(adView)
    }

Jetpack Compose

@Composable
/** Load and display a native ad. */
fun NativeScreen() {
  var nativeAd by remember { mutableStateOf<NativeAd?>(null) }
  val context = LocalContext.current
  var isDisposed by remember { mutableStateOf(false) }

  DisposableEffect(Unit) {
    // Load the native ad when we launch this screen
    loadNativeAd(
      context = context,
      onAdLoaded = { ad ->
        // Handle the native ad being loaded.
        if (!isDisposed) {
          nativeAd = ad
        } else {
          // Destroy the native ad if loaded after the screen is disposed.
          ad.destroy()
        }
      },
    )
    // Destroy the native ad to prevent memory leaks when we dispose of this screen.
    onDispose {
      isDisposed = true
      nativeAd?.destroy()
      nativeAd = null
    }
  }

  // Display the native ad view with a user defined template.
  nativeAd?.let { adValue -> DisplayNativeAdView(adValue) }
}

fun loadNativeAd(context: Context, onAdLoaded: (NativeAd) -> Unit) {
  val adLoader =
    AdLoader.Builder(context, NATIVE_AD_UNIT_ID)
      .forNativeAd { nativeAd -> onAdLoaded(nativeAd) }
      .withAdListener(
        object : AdListener() {
          override fun onAdFailedToLoad(error: LoadAdError) {
            Log.e(TAG, "Native ad failed to load: ${error.message}")
          }

          override fun onAdLoaded() {
            Log.d(TAG, "Native ad was loaded.")
          }

          override fun onAdImpression() {
            Log.d(TAG, "Native ad recorded an impression.")
          }

          override fun onAdClicked() {
            Log.d(TAG, "Native ad was clicked.")
          }
        }
      )
      .build()
  adLoader.loadAd(AdRequest.Builder().build())
}
NativeScreen.kt

يُرجى العِلم أنّه يجب عرض جميع مواد العرض لإعلان مدمج مع المحتوى معيّن داخل تنسيق NativeAdView. Google Mobile Ads SDK تحاول تسجيل تحذير عند عرض مواد العرض المدمجة مع المحتوى خارج تنسيق عرض الإعلان المدمج مع المحتوى.

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

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

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

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

جافا

private void displayNativeAd(ViewGroup parent, NativeAd ad) {

  // Inflate a layout and add it to the parent ViewGroup.
  LayoutInflater inflater = (LayoutInflater) parent.getContext()
          .getSystemService(Context.LAYOUT_INFLATER_SERVICE);
  NativeAdView adView = (NativeAdView) inflater
          .inflate(R.layout.ad_layout_file, parent);

  // Locate the view that will hold the headline, set its text, and call the
  // NativeAdView's setHeadlineView method to register it.
  TextView headlineView = adView.findViewById<TextView>(R.id.ad_headline);
  headlineView.setText(ad.getHeadline());
  adView.setHeadlineView(headlineView);

  // Repeat the process for the other assets in the NativeAd
  // using additional view objects (Buttons, ImageViews, etc).

  // If you use a MediaView, call theNativeAdView.setMediaView() method
  // before calling the NativeAdView.setNativeAd() method.
  MediaView mediaView = (MediaView) adView.findViewById(R.id.ad_media);
  adView.setMediaView(mediaView);

  // Register the native ad with its ad view.
  adView.setNativeAd(ad);

  // Ensure that the parent view doesn't already contain an ad view.
  parent.removeAllViews();

  // Place the AdView into the parent.
  parent.addView(adView);
}

Kotlin

fun displayNativeAd(parent: ViewGroup, ad: NativeAd) {

  // Inflate a layout and add it to the parent ViewGroup.
  val inflater = parent.getContext().getSystemService(Context.LAYOUT_INFLATER_SERVICE)
          as LayoutInflater
  val adView = inflater.inflate(R.layout.ad_layout_file, parent) as NativeAdView

  // Locate the view that will hold the headline, set its text, and use the
  // NativeAdView's headlineView property to register it.
  val headlineView = adView.findViewById<TextView>(R.id.ad_headline)
  headlineView.text = ad.headline
  adView.headlineView = headlineView

  // Repeat the process for the other assets in the NativeAd using
  // additional view objects (Buttons, ImageViews, etc).

  val mediaView = adView.findViewById<MediaView>(R.id.ad_media)
  adView.mediaView = mediaView

  // Call the NativeAdView's setNativeAd method to register the
  // NativeAdObject.
  adView.setNativeAd(ad)

  // Ensure that the parent view doesn't already contain an ad view.
  parent.removeAllViews()

  // Place the AdView into the parent.
  parent.addView(adView)
}

Jetpack Compose

@Composable
/** Display a native ad with a user defined template. */
fun DisplayNativeAdView(nativeAd: NativeAd) {
  Box(modifier = Modifier.padding(8.dp)) {
    // Call the NativeAdView composable to display the native ad.
    NativeAdView(nativeAd) {
      Column(modifier = Modifier.fillMaxWidth()) {
        Box {
          Row(modifier = Modifier.fillMaxWidth()) {
            // If available, display the icon asset.
            nativeAd.icon?.let { icon ->
              NativeAdIconView(Modifier.padding(5.dp)) {
                icon.drawable?.toBitmap()?.let { bitmap ->
                  Image(bitmap = bitmap.asImageBitmap(), "Icon")
                }
              }
            }
            Column {
              // If available, display the headline asset.
              nativeAd.headline?.let {
                NativeAdHeadlineView {
                  Text(text = it, style = MaterialTheme.typography.headlineLarge)
                }
              }
              // If available, display the star rating asset.
              nativeAd.starRating?.let {
                NativeAdStarRatingView {
                  Text(text = "Rated $it", style = MaterialTheme.typography.labelMedium)
                }
              }
            }
          }
          // Display the ad attribution.
          NativeAdAttribution(
            modifier = Modifier.align(Alignment.TopStart),
            text = stringResource(R.string.attribution),
          )
        }

        // Display the media asset.
        NativeAdMediaView(modifier = Modifier.fillMaxWidth())

        // If available, display the body asset.
        nativeAd.body?.let {
          NativeAdBodyView(modifier = Modifier.padding(5.dp)) { Text(text = it) }
        }

        Row(Modifier.align(Alignment.End).padding(5.dp)) {
          // If available, display the price asset.
          nativeAd.price?.let {
            NativeAdPriceView(Modifier.padding(5.dp).align(Alignment.CenterVertically)) {
              Text(text = it)
            }
          }
          // If available, display the store asset.
          nativeAd.store?.let {
            NativeAdStoreView(Modifier.padding(5.dp).align(Alignment.CenterVertically)) {
              Text(text = it)
            }
          }
          // If available, display the call to action asset.
          nativeAd.callToAction?.let { callToAction ->
            NativeAdCallToActionView(Modifier.padding(5.dp)) { NativeAdButton(text = callToAction) }
          }
        }
      }
    }
  }
}
NativeScreen.kt

شارة "خيارات الإعلان"

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

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

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

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

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

للاستماع إلى النقرات، نفِّذ Google Mobile Ads SDK معاودة الاتصال للنقرات:

جافا

AdLoader adLoader = new AdLoader.Builder(context, "ca-app-pub-3940256099942544/2247696110")
    // ...
    .withAdListener(new AdListener() {
        @Override
        public void onAdFailedToLoad(LoadAdError adError) {
            // Handle the failure by logging.
        }
        @Override
        public void onAdClicked() {
            // Log the click event or other custom behavior.
        }
    })
    .build();

Kotlin

val adLoader = AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
    // ...
    .withAdListener(object : AdListener() {
        override fun onAdFailedToLoad(adError: LoadAdError) {
            // Handle the failure.
        }
        override fun onAdClicked() {
            // Log the click event or other custom behavior.
        }
    })
    .build()

ImageScaleType

تحتوي فئة MediaView على سمة ImageScaleType عند عرض الصور. إذا أردت تغيير كيفية تغيير حجم صورة في MediaView، اضبط ImageView.ScaleType المقابل باستخدام طريقة setImageScaleType() في MediaView:

جافا

mediaView.setImageScaleType(ImageView.ScaleType.CENTER_CROP);

Kotlin

mediaView.imageScaleType = ImageView.ScaleType.CENTER_CROP

MediaContent

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

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

محو إعلان

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

جافا

nativeAd.destroy();

Kotlin

nativeAd.destroy()

أمثلة على GitHub

تنفيذ كامل لمثال "الإعلانات المدمجة مع المحتوى":

Java Kotlin JetpackCompose

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

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

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

تحسين عملية تهيئة حزمة SDK وتحميل الإعلانات (إصدار تجريبي)

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

تحديد فئة NativeAdView

تنسيق XML

Jetpack Compose

التعامل مع "الإعلان المدمج مع المحتوى" الذي تم تحميله

جافا

Kotlin

Jetpack Compose

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

جافا

Kotlin

Jetpack Compose

شارة "خيارات الإعلان"

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

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

جافا

Kotlin

ImageScaleType

جافا

Kotlin

MediaContent

محو إعلان

جافا

Kotlin

أمثلة على GitHub

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

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

تحديد فئة `NativeAdView`