عند تحميل إعلان مدمج مع المحتوى، 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("/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)
جافا
// 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. 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
جافا
تتبُّع النقرات والنص المعدَّل
- العرض المباشر: عند عرض سلسلة
creativeSummaryالدقيقة التي توفّرها حزمة SDK، سجِّلها في خاصيةcreativeSummaryViewداخل حاويةNativeAdViewلتفعيل معالجة النقرات في حزمة SDK. - المقدّمات المعدَّلة: إذا كان تطبيقك يعدِّل الملخّص للمادة الإبداعية أو يلخّصه أو يضيف إليه نصًا مخصّصًا للمحادثة، ضَع النص المعدَّل خارج حاوية
NativeAdView.
محو إعلان
بعد عرض إعلان مدمج مع المحتوى، أتلف الإعلان. يُتلف المثال التالي إعلانًا مدمجًا مع المحتوى:
Kotlin
nativeAd.destroy()
جافا
nativeAd.destroy();
اختبار رمز الإعلان المدمج مع المحتوى
الإعلانات المَبيعة مباشرةً
إذا أردت اختبار شكل الإعلانات المدمجة مع المحتوى المَبيعة مباشرةً، يمكنك استخدام رقم تعريف الوحدة الإعلانية هذا في "مدير إعلانات Google":
/21775744923/example/native
تم ضبطه لعرض نماذج من إعلانات تثبيت التطبيقات وإعلانات المحتوى، بالإضافة إلى شكل إعلان مدمج مع المحتوى مخصّص يتضمّن مواد العرض التالية:
- العنوان (نص)
- الصورة الرئيسية (صورة)
- الشرح (نص)
رقم تعريف النموذج لشكل الإعلان المدمج مع المحتوى المخصّص هو 10063170.
الإعلانات التي تملأ المساحة الإعلانية المتبقية للإعلانات المدمجة مع المحتوى
يقتصر ملء المساحة الإعلانية المتبقية في Ad Exchange على مجموعة مختارة من الناشرين. لاختبار سلوك الإعلانات التي تملأ المساحة الإعلانية المتبقية للإعلانات المدمجة مع المحتوى، استخدِم الوحدة الإعلانية هذه في "مدير إعلانات Google":
/21775744923/example/native-backfill
تعرض هذه الوحدة نماذج من إعلانات تثبيت التطبيقات وإعلانات المحتوى التي تتضمّن شارة "خيارات الإعلان".
تذكَّر تعديل الرمز للإشارة إلى أرقام تعريف الوحدة الإعلانية والنموذج الفعلية قبل عرض الإعلانات.
الخطوات التالية
استكشِف المواضيع التالية:
مثال
نزِّل التطبيق النموذجي الذي يوضّح كيفية استخدام GMA Next-Gen SDK وشغِّله .