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

اختيار النظام الأساسي: Android iOS Android (الإصدار القديم)

عند تحميل إعلان مدمج مع المحتوى، Google Mobile Ads SDK (Legacy) تستدعي أداة الاستماع لشكل الإعلان المقابل. بعد ذلك، يكون تطبيقك مسؤولاً عن عرض الإعلان، ولكن ليس بالضرورة أن يعرضه على الفور. لتسهيل عرض أشكال الإعلانات التي يحدّدها النظام، توفّر حزمة 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

  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.
        }
    }

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

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

جافا

AdLoader.Builder builder = new AdLoader.Builder(this, "/21775744923/example/native")
    .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, "/21775744923/example/native")
    .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())
}

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

توفّر فئات عرض الإعلانات أيضًا طرقًا تُستخدَم لتسجيل العرض المستخدَم لكل مادة عرض فردية، وطريقة لتسجيل عنصر 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) }
          }
        }
      }
    }
  }
}

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

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

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

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

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

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

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

جافا

AdLoader adLoader = new AdLoader.Builder(context, "/21775744923/example/native")
    // ...
    .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, "/21775744923/example/native")
    // ...
    .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()

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

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

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

/21775744923/example/native

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

  • العنوان (نص)
  • الصورة الرئيسية (صورة)
  • الشرح (نص)

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

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

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

/21775744923/example/native-backfill

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

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

أمثلة على GitHub

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

Java Kotlin JetpackCompose

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

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