يمكنك مشاركة ملاحظاتك حول "الجيل التالي من SDK لإعلانات Google على الأجهزة الجوّالة" في قناة #gma-next-gen-sdk على Discord في خادم Google Advertising and Measurement Community.

تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

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

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

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

أدرِج مجلد 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("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)

جافا

// 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. GMA Next-Gen SDK تحاول تسجيل تحذير عند عرض مواد عرض مدمجة مع المحتوى خارج تنسيق عرض إعلان مدمج مع المحتوى.

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

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

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

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

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

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

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

للاستماع إلى النقرات، نفِّذ 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. عند ضبط خاصية mediaContent في MediaView باستخدام مثيل 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 الدقيقة التي توفّرها حزمة تطوير البرامج (SDK)، سجِّلها في خاصية creativeSummaryView داخل حاوية NativeAdView لتفعيل معالجة النقرات في حزمة تطوير البرامج (SDK).
المقدّمات المعدَّلة: إذا كان تطبيقك يعدِّل الملخّص للمادة الإبداعية أو يلخّصه أو يضيف إليه نصًا حواريًا مخصّصًا، ضَع النص المعدَّل خارج حاوية NativeAdView.

محو إعلان

بعد عرض إعلان مدمج مع المحتوى، أتلف الإعلان. يُتلف المثال التالي إعلانًا مدمجًا مع المحتوى:

Kotlin

nativeAd.destroy()

جافا

nativeAd.destroy();

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

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

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

مثال

نزِّل التطبيق النموذجي الذي يوضّح كيفية استخدام GMA Next-Gen SDK وشغِّله .

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

تحديد فئة NativeAdView

تنسيق XML

Jetpack Compose

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

Kotlin

جافا

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

Kotlin

جافا

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

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

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

Kotlin

جافا

ImageScaleType

Kotlin

جافا

MediaContent

إضافة ملخّص للمادة الإبداعية

إضافة طريقة عرض النص إلى تنسيقك

ملء طريقة العرض وتسجيلها

Kotlin

جافا

تتبُّع النقرات والنص المعدَّل

محو إعلان

Kotlin

جافا

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

مثال

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

تحديد فئة `NativeAdView`