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