عند تحميل إعلان مُدمَج مع المحتوى، تستدعي حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة أداة معالجة الأحداث الخاصة بشكل الإعلان ذي الصلة. ويكون تطبيقك مسؤولاً بعد ذلك عن عرض الإعلان، مع أنّه ليس بالضرورة أن يتم ذلك على الفور. لتسهيل عرض أشكال الإعلانات المحدّدة من النظام، توفّر حزمة 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
أدرِج وحدة JetpackComposeDemo/compose-util التي تتضمّن أدوات مساعدة لإنشاء NativeAdView
ومواد العرض الخاصة به.
باستخدام الوحدة compose-util
، أنشئ 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.
}
}
التعامل مع الإعلان المدمج مع المحتوى الذي تم تحميله
عند تحميل إعلان مدمج مع المحتوى، تعامَل مع حدث رد الاتصال، ووسِّع عرض الإعلان المدمج مع المحتوى، وأضِفه إلى بنية العرض:
Java
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
. تحاول حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة تسجيل تحذير عند عرض مواد عرض الإعلانات المدمجة مع المحتوى خارج تخطيط عرض الإعلان المدمج مع المحتوى.
توفّر فئات عرض الإعلانات أيضًا طرقًا تُستخدَم لتسجيل طريقة العرض المستخدَمة لكل مادة عرض فردية، وطريقة لتسجيل العنصر NativeAd
نفسه.
يتيح تسجيل طرق العرض بهذه الطريقة لحزمة تطوير البرامج (SDK) معالجة مهام تلقائيًا، مثل:
- تسجيل النقرات
- تسجيل مرّات الظهور عندما تكون وحدة البكسل الأولى مرئية على الشاشة
- عرض تراكب AdChoices لملء المساحة الإعلانية بتنسيقات أصلية —يتوفّر حاليًا لمجموعة محدودة من الناشرين
عرض الإعلان المدمج مع المحتوى
يوضّح المثال التالي كيفية عرض إعلان مدمج مع المحتوى:
Java
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) {
val context = LocalContext.current
Box(modifier = Modifier.padding(8.dp).wrapContentHeight(Alignment.Top)) {
// Call the NativeAdView composable to display the native ad.
NativeAdView {
// Inside the NativeAdView composable, display the native ad assets.
Column(Modifier.align(Alignment.TopStart).wrapContentHeight(Alignment.Top)) {
// Display the ad attribution.
NativeAdAttribution(text = context.getString(R.string.attribution))
Row {
// 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)
}
}
}
}
// If available, display the body asset.
nativeAd.body?.let { NativeAdBodyView { Text(text = it) } }
// Display the media asset.
NativeAdMediaView(Modifier.fillMaxWidth().height(500.dp).fillMaxHeight())
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.
// Note: The Jetpack Compose button implements a click handler which overrides the native
// ad click handler, causing issues. Use the NativeAdButton which does not implement a
// click handler. To handle native ad clicks, use the NativeAd AdListener onAdClicked
// callback.
nativeAd.callToAction?.let { callToAction ->
NativeAdCallToActionView(Modifier.padding(5.dp)) { NativeAdButton(text = callToAction) }
}
}
}
}
}
}
تراكب "خيارات الإعلان"
تضيف حزمة تطوير البرامج (SDK) شارة "خيارات الإعلان" كطريقة عرض إعلان عند عرض إعلان احتياطي. إذا كان تطبيقك يستخدم ميزة "تعبئة الإعلانات المدمجة مع المحتوى"، يجب ترك مساحة في الزاوية المفضّلة من طريقة عرض الإعلان المدمج مع المحتوى لشعار AdChoices الذي يتم إدراجه تلقائيًا. ومن الضروري أيضًا أن يتمكّن المستخدم من رؤية هذه الشارة، لذا يجب اختيار ألوان الخلفية والصور بشكل مناسب. لمزيد من المعلومات حول مظهر التراكب ووظيفته، يُرجى الرجوع إلى إرشادات تنفيذ الإعلانات المدمجة مع المحتوى الآلية.
تصنيف الإعلانات الآلية المدمجة مع المحتوى كإعلانات
عند عرض إعلانات مدمجة مع المحتوى آليًا، يجب عرض شارة "التصنيف كإعلان" للإشارة إلى أنّ العرض هو إعلان. مزيد من المعلومات في إرشادات السياسة
التعامل مع النقرات
لا تنفِّذ أي معالجات نقرات مخصّصة على أي طرق عرض فوق طريقة عرض الإعلان الأصلي أو بداخلها. تتعامل حزمة تطوير البرامج (SDK) مع النقرات على مواد عرض الإعلان طالما أنّك تملأ مواد عرض الإعلان وتسجّلها بشكل صحيح.
للاستماع إلى النقرات، عليك تنفيذ وظيفة معاودة الاتصال الخاصة بالنقرات في "حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة":
Java
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
:
Java
mediaView.setImageScaleType(ImageView.ScaleType.CENTER_CROP);
Kotlin
mediaView.imageScaleType = ImageView.ScaleType.CENTER_CROP
MediaContent
تحتوي الفئة MediaContent
على البيانات المرتبطة بمحتوى الوسائط الخاص بالإعلان الأصلي، والذي يتم عرضه باستخدام الفئة MediaView
. عند ضبط السمة
MediaView
mediaContent
باستخدام مثيل MediaContent
:
إذا كانت مادة عرض الفيديو متاحة، يتم تخزينها مؤقتًا ويبدأ تشغيلها داخل
MediaView
. يمكنك معرفة ما إذا كانت مادة عرض الفيديو متوفرة من خلال التحقّق منhasVideoContent()
.إذا لم يكن الإعلان يتضمّن مادة عرض فيديو، يتم تنزيل مادة العرض
mainImage
ووضعها داخلMediaView
بدلاً من ذلك.
∂## Destroy an ad
بعد عرض إعلان مدمج مع المحتوى، عليك إتلاف الإعلان. يوضّح المثال التالي كيفية إيقاف عرض إعلان أصلي:
Java
nativeAd.destroy();
Kotlin
nativeAd.destroy()
اختبار رمز الإعلان المدمج مع المحتوى
الإعلانات المَبيعة مباشرةً
إذا أردت تجربة الإعلانات المدمجة مع المحتوى التي يتم بيعها مباشرةً، يمكنك استخدام رقم تعريف الوحدة الإعلانية التالي في "مدير إعلانات Google":
/21775744923/example/native
تمّت تهيئته لعرض عيّنات من إعلانات تثبيت التطبيقات وإعلانات المحتوى، بالإضافة إلى شكل إعلان مدمج مع المحتوى مخصّص يتضمّن مواد العرض التالية:
- العنوان الرئيسي (نص)
- MainImage (image)
- التعليق التوضيحي (نص)
معرّف النموذج الخاص بشكل الإعلان المدمج مع المحتوى المخصّص هو 10063170
.
إعلانات ملء الفراغات المدمجة مع المحتوى
تقتصر ميزة "الإعلانات الاحتياطية" في Ad Exchange على مجموعة محدّدة من الناشرين. لاختبار سلوك الإعلانات المدمجة مع المحتوى الاحتياطية، استخدِم الوحدة الإعلانية التالية في "مدير إعلانات Google":
/21775744923/example/native-backfill
يعرض التطبيق عيّنات من "إعلانات تثبيت التطبيقات" و"إعلانات المحتوى" التي تتضمّن التراكب الخاص بـ AdChoices.
يُرجى تذكُّر تعديل الرمز للإشارة إلى المعرّفات الفعلية للوحدة الإعلانية والنموذج قبل طرح الإعلان.
أمثلة على GitHub
مثال على عملية إعداد "الإعلانات المدمجة مع المحتوى" بالكامل:
الخطوات التالية
يمكنك الاطّلاع على المواضيع التالية: