يتناول هذا الدليل كيفية تحميل "إعلان بانر تكيُّفي ثابت" في تطبيق Android.
المتطلبات الأساسية
- إعداد Google Mobile Ads SDK (Legacy)
- اختياري: للاطّلاع على مثال على تنفيذ "إعلانات البانر"، اختَر أحد نماذج التطبيقات التالية:
- مثال على إعلانات البانر التكيّفية الثابتة باستخدام Java أو Kotlin أو Jetpack Compose
- العرض التوضيحي للميزات المتقدّمة في Java أو Kotlin
اختبِر دائمًا باستخدام الإعلانات الاختبارية
عند إنشاء تطبيقاتك واختبارها، احرص على استخدام إعلانات اختبارية بدلاً من الإعلانات المباشرة الخاصة بالمنتج. وقد يؤدي عدم إجراء ذلك إلى تعليق حسابك.
أسهل طريقة لتحميل الإعلانات الاختبارية هي استخدام رقم تعريف وحدة إعلانية اختبارية مخصّصة لـ "إعلانات البانر" على Android:
/21775744923/example/adaptive-banner
تم إعداد هذا المعرّف خصيصًا لعرض إعلانات اختبارية لكل طلب، ويمكنك استخدامه في تطبيقاتك أثناء الترميز والاختبار وتصحيح الأخطاء. ما عليك سوى التأكّد من استبداله برقم تعريف الوحدة الإعلانية الخاص بك قبل نشر تطبيقك.
لمزيد من المعلومات حول طريقة عمل Google Mobile Ads SDK (Legacy) الإعلانات الاختبارية، يُرجى الاطّلاع على تفعيل الإعلانات الاختبارية.
تحديد طريقة عرض الإعلان
تنسيق XML
أضِف طريقة عرض إلى ملف XML الخاص بالتصميم لتعمل كحاوية لإعلان البانر التكيّفي الثابت:
<!-- Ad view container that fills the width of the screen and adjusts its
height to the content of the ad. -->
<FrameLayout
android:id="@+id/ad_view_container"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:layout_centerInParent="true"
android:layout_alignParentBottom="true" />
Jetpack Compose
أدرِج مجلد أدوات JetpackCompose. يتضمّن هذا المجلد أدوات مساعدة لإنشاء العنصر
AdViewومواد العرض.أنشئ
AdView:
// Place the ad view at the bottom of the screen.
Column(modifier = modifier.fillMaxSize(), verticalArrangement = Arrangement.Bottom) {
Box(modifier = modifier.fillMaxWidth()) { AdManagerBannerAd(adView, modifier) }
}
تحديد حجم الإعلان
توفّر "إعلانات البانر التكيُّفية" الكبيرة شكل إعلان أكبر مصمّمًا للتنسيقات التي لا تتضمّن إمكانية التمرير. مقارنةً بـ "إعلانات البانر التكيّفية الثابتة" العادية، تتيح هذه الإعلانات حدًا أقصى للارتفاع أكبر، يصل إلى% 20 من ارتفاع الشاشة، ويتراوح بين 50 و150 بكسل مستقل الكثافة. تم تحسين هذه المساحة المتزايدة لتناسب محتوى الفيديو.
اضبط AdSize على نوع إعلان بانر تكيّفي ثابت بعرض محدّد:
جافا
// Request an anchored adaptive banner with a width of 360.
adView.setAdSize(AdSize.getCurrentOrientationAnchoredAdaptiveBannerAdSize(this, 360));
Kotlin
// Request a large anchored adaptive banner with a width of 360.
adView.setAdSize(AdSize.getLargeAnchoredAdaptiveBannerAdSize(this, 360))
Jetpack Compose
// Set a large anchored adaptive banner ad size with a given width.
val adSize = AdSize.getLargeAnchoredAdaptiveBannerAdSize(LocalContext.current, 360)
adView.setAdSize(adSize)
إضافة "AdManagerAdView" إلى التنسيق
أنشئ AdManagerAdView باستخدام حجم الإعلان لإضافته إلى تنسيق تطبيقك:
جافا
// Create a new ad view.
adView = new AdManagerAdView(this);
adView.setAdUnitId(AD_UNIT);
// Request an anchored adaptive banner with a width of 360.
adView.setAdSize(AdSize.getCurrentOrientationAnchoredAdaptiveBannerAdSize(this, 360));
// Replace ad container with new ad view.
adContainerView.removeAllViews();
adContainerView.addView(adView);
Kotlin
// Create a new ad view.
val adView = AdManagerAdView(this)
adView.adUnitId = AD_UNIT_ID
// Request a large anchored adaptive banner with a width of 360.
adView.setAdSize(AdSize.getLargeAnchoredAdaptiveBannerAdSize(this, 360))
this.adView = adView
// Replace ad container with new ad view.
binding.adViewContainer.removeAllViews()
binding.adViewContainer.addView(adView)
Jetpack Compose
val adView = remember { AdManagerAdView(context) }
// Setup and load the adview.
// Set the unique ID for this specific ad unit.
adView.adUnitId = ADMANAGER_ADAPTIVE_BANNER_AD_UNIT_ID
// Set a large anchored adaptive banner ad size with a given width.
val adSize = AdSize.getLargeAnchoredAdaptiveBannerAdSize(LocalContext.current, 360)
adView.setAdSize(adSize)
// Place the ad view at the bottom of the screen.
Column(modifier = modifier.fillMaxSize(), verticalArrangement = Arrangement.Bottom) {
Box(modifier = modifier.fillMaxWidth()) { AdManagerBannerAd(adView, modifier) }
}
تحميل إعلان
يحمّل المثال التالي إعلان بانر تكيُّفي ثابت بعرض 360 وحدة بكسل في عنصر AdManagerAdView:
جافا
AdManagerAdRequest adRequest = new AdManagerAdRequest.Builder().build();
adView.loadAd(adRequest);
Kotlin
val adRequest = AdManagerAdRequest.Builder().build()
adView.loadAd(adRequest)
إعادة تحميل إعلان
إذا ضبطت وحدتك الإعلانية لإعادة التحميل، لن تحتاج إلى طلب إعلان آخر عند تعذُّر تحميل الإعلان. تلتزم Google Mobile Ads SDK (Legacy) بأي معدّل إعادة تحميل حدّدته في واجهة مستخدم "مدير إعلانات Google". إذا لم تفعّل إعادة التحميل، أرسِل طلبًا جديدًا. لمزيد من التفاصيل حول إعادة تحميل الوحدات الإعلانية، مثل ضبط معدّل إعادة التحميل، اطّلِع على معدّل إعادة تحميل الإعلانات في تطبيقات الأجهزة الجوّالة.
إصدار مورد إعلان
عند الانتهاء من استخدام "إعلان بانر"، يمكنك إزالة موارده.
لتحرير موارد الإعلان، عليك إزالة الإعلان من هيكلية طرق العرض وإسقاط جميع مَراجعه:
جافا
public void destroyBanner() {
// Remove banner from view hierarchy.
if (adView != null) {
View parentView = (View) adView.getParent();
if (parentView instanceof ViewGroup) {
((ViewGroup) parentView).removeView(adView);
}
// Destroy the banner ad resources.
adView.destroy();
}
// Drop reference to the banner ad.
adView = null;
}
Kotlin
fun destroyBanner() {
// Remove banner from view hierarchy.
val parentView = adView?.parent
if (parentView is ViewGroup) {
parentView.removeView(adView)
}
// Destroy the banner ad resources.
adView?.destroy()
// Drop reference to the banner ad.
adView = null
}
Jetpack Compose
DisposableEffect(Unit) {
// Destroy the AdView to prevent memory leaks when the screen is disposed.
onDispose { adView.destroy() }
}
أحداث الإعلانات
يمكنك الاستماع إلى عدد من الأحداث في مراحل نشاط الإعلان، بما في ذلك التحميل ومرّة ظهور الإعلان والنقر عليه، بالإضافة إلى أحداث فتح الإعلان وإغلاقه. يُنصح بضبط دالة معاودة الاتصال قبل تحميل البانر.
جافا
if (adView != null) {
adView.setAdListener(
new AdListener() {
@Override
public void onAdClicked() {
// Code to be executed when the user clicks on an ad.
}
@Override
public void onAdClosed() {
// Code to be executed when the user is about to return
// to the app after tapping on an ad.
}
@Override
public void onAdFailedToLoad(@NonNull LoadAdError adError) {
// Code to be executed when an ad request fails.
}
@Override
public void onAdImpression() {
// Code to be executed when an impression is recorded
// for an ad.
}
@Override
public void onAdLoaded() {
// Code to be executed when an ad finishes loading.
}
@Override
public void onAdOpened() {
// Code to be executed when an ad opens an overlay that
// covers the screen.
}
});
}
Kotlin
adView?.adListener =
object : AdListener() {
override fun onAdClicked() {
// Code to be executed when the user clicks on an ad.
}
override fun onAdClosed() {
// Code to be executed when the user is about to return
// to the app after tapping on an ad.
}
override fun onAdFailedToLoad(adError: LoadAdError) {
// Code to be executed when an ad request fails.
}
override fun onAdImpression() {
// Code to be executed when an impression is recorded
// for an ad.
}
override fun onAdLoaded() {
// Code to be executed when an ad finishes loading.
}
override fun onAdOpened() {
// Code to be executed when an ad opens an overlay that
// covers the screen.
}
}
يتوافق كلّ من الطرق القابلة للتجاهل في AdListener
مع حدث في دورة حياة الإعلان.
| الإجراءات القابلة للتجاهل | |
|---|---|
onAdClicked() |
يتم استدعاء الطريقة onAdClicked()
عند تسجيل نقرة على إعلان.
|
onAdClosed() |
يتم استدعاء الطريقة onAdClosed()
عندما يعود المستخدم إلى التطبيق بعد عرض عنوان URL المقصود للإعلان. ويمكن لتطبيقك استخدامها لاستئناف الأنشطة المعلّقة أو تنفيذ أي عمل آخر ضروري لتجهيز التطبيق للتفاعل.
|
onAdFailedToLoad() |
الطريقة الوحيدة التي تتضمّن مَعلمة هي onAdFailedToLoad(). تصف مَعلمة الخطأ من النوع
LoadAdError الخطأ الذي حدث. لمزيد من المعلومات، يُرجى الرجوع إلى مستندات تصحيح أخطاء تحميل الإعلانات.
|
onAdImpression() |
يتم استدعاء الطريقة onAdImpression() عند تسجيل مرّة ظهور لإعلان.
|
onAdLoaded() |
يتم تنفيذ الطريقة onAdLoaded()
عند انتهاء تحميل الإعلان. إذا أردت تأخير إضافة AdManagerAdView إلى نشاطك أو جزء من تطبيقك إلى أن تتأكّد من تحميل إعلان، يمكنك إجراء ذلك هنا مثلاً.
|
onAdOpened() |
يتم استدعاء الطريقة onAdOpened()
عندما يفتح إعلان طبقة تغطي الشاشة.
|
تسريع الأجهزة لإعلانات الفيديو
لكي تظهر إعلانات الفيديو بنجاح في مشاهدات إعلانات البانر، يجب تفعيل تسريع الأجهزة.
يتم تفعيل ميزة "تسريع الأجهزة" تلقائيًا، ولكن قد تختار بعض التطبيقات إيقافها. إذا كان ذلك ينطبق على تطبيقك، ننصحك بتفعيل ميزة تسريع الأجهزة لفئات
Activity التي تستخدم الإعلانات.
تفعيل ميزة "تسريع الأجهزة"
إذا كان تطبيقك لا يعمل بشكل صحيح عند تفعيل ميزة تسريع الأجهزة على مستوى الجهاز، يمكنك التحكّم فيها في الأنشطة الفردية أيضًا. لتفعيل ميزة "تسريع الأجهزة" أو إيقافها، يمكنك استخدام السمة android:hardwareAccelerated للعنصرَين <application> و<activity> في AndroidManifest.xml. يُفعّل المثال التالي تسريع الأجهزة للتطبيق بأكمله، ولكنّه يوقفه لنشاط واحد:
<application android:hardwareAccelerated="true">
<!-- For activities that use ads, hardwareAcceleration should be true. -->
<activity android:hardwareAccelerated="true" />
<!-- For activities that don't use ads, hardwareAcceleration can be false. -->
<activity android:hardwareAccelerated="false" />
</application>
لمزيد من المعلومات حول خيارات التحكّم في تسريع الأجهزة، يُرجى الاطّلاع على دليل تسريع الأجهزة. يُرجى العِلم أنّه لا يمكن تفعيل مشاهدات الإعلانات الفردية لميزة "تسريع الأجهزة" إذا كان النشاط غير مفعَّل، لذا يجب أن يكون النشاط نفسه مفعَّلاً لميزة "تسريع الأجهزة".
احتساب عدد مرّات الظهور يدويًا
يتوافق الاحتساب اليدوي لعدد مرات الظهور مع الحملات المبيعة مباشرةً والحملات الذاتية التي تتضمّن تصاميم إعلانات يتم عرضها مباشرةً في "مدير الإعلانات". ويجب عدم استخدامه في الإعلانات الاحتياطية أو إعلانات الشبكات التابعة لجهات خارجية. لمزيد من التفاصيل، يُرجى الاطّلاع على احتساب مرّات الظهور والنقرات.
يمكنك إرسال إشارات ping لمرّات الظهور يدويًا إلى "مدير إعلانات Google" إذا كانت لديك شروط خاصة لتسجيل مرّة الظهور:
جافا
if (adManagerAdView != null) {
adManagerAdView.setManualImpressionsEnabled(true);
}
Kotlin
adManagerAdView?.setManualImpressionsEnabled(true)
عندما تتأكّد من أنّه تم عرض إعلان بنجاح على الشاشة، يمكنك تسجيل مرّة ظهور يدويًا باتّباع الخطوات التالية:
جافا
if (adManagerAdView != null) {
adManagerAdView.recordManualImpression();
}
Kotlin
adManagerAdView?.recordManualImpression()
الأحداث في التطبيقات
تتيح لك أحداث التطبيق إنشاء إعلانات يمكنها إرسال رسائل إلى رمز التطبيق. ويمكن للتطبيق بعد ذلك اتخاذ إجراءات بناءً على هذه الرسائل.
يمكنك الاستماع إلى أحداث التطبيق الخاصة بـ "مدير إعلانات Google" باستخدام
AppEventListener.
يمكن أن تحدث هذه الأحداث في أي وقت خلال مراحل نشاط الإعلان، حتى قبل استدعاء onAdLoaded().
اضبط AppEventListener على AdManagerAdView:
جافا
if (adManagerAdView != null) {
adManagerAdView.setAppEventListener(this);
}
Kotlin
adManagerAdView?.appEventListener = this
في ما يلي مثال يوضّح كيفية تغيير لون خلفية تطبيقك استنادًا إلى حدث في التطبيق يحمل اسم لون:
جافا
@Override
public void onAppEvent(@NonNull String name, @NonNull String info) {
if (name.equals("color")) {
switch (info) {
case "green":
// Set background color to green.
break;
case "blue":
// Set background color to blue.
break;
default:
// Set background color to black.
break;
}
}
}
Kotlin
override fun onAppEvent(name: String, info: String) {
if (name == "color") {
when (info) {
"green" -> {
// Set background color to green.
}
"blue" -> {
// Set background color to blue.
}
else -> {
// Set background color to black.
}
}
}
}
في ما يلي تصميم الإعلان المقابل الذي يرسل رسائل أحداث تطبيق الألوان إلى أداة الاستماع:
<html>
<head>
<script src="//www.gstatic.com/afma/api/v1/google_mobile_app_ads.js"></script>
<script>
document.addEventListener("DOMContentLoaded", function() {
// Send a color=green event when ad loads.
admob.events.dispatchAppEvent("color", "green");
document.getElementById("ad").addEventListener("click", function() {
// Send a color=blue event when ad is clicked.
admob.events.dispatchAppEvent("color", "blue");
});
});
</script>
<style>
#ad {
width: 320px;
height: 50px;
top: 0px;
left: 0px;
font-size: 24pt;
font-weight: bold;
position: absolute;
background: black;
color: white;
text-align: center;
}
</style>
</head>
<body>
<div id="ad">Carpe diem!</div>
</body>
</html>
راجِع مثال "أحداث تطبيق مدير إعلانات Google" للاطّلاع على عملية تنفيذ أحداث التطبيق في تطبيق API Demo.
الخطوات التالية
إعلانات البانر القابلة للتصغير
"إعلانات البانر القابلة للتصغير" هي إعلانات بانر تظهر في البداية كتراكب أكبر، مع زر لتصغير الإعلان إلى حجم أصغر. ننصحك باستخدامها لتحسين أدائك بشكل أكبر. لمزيد من التفاصيل، يُرجى الاطّلاع على إعلانات البانر القابلة للتصغير.
إعلانات البانر التكيّفية المضمّنة
"إعلانات البانر التكيُّفية" المضمّنة هي أكبر وأطول مقارنةً بـ "إعلانات البانر التكيُّفية الثابتة". ويختلف ارتفاعها، ويمكن أن يكون بطول شاشة الجهاز. ننصح باستخدام "إعلانات البانر التكيُّفية المضمّنة" بدلاً من "إعلانات البانر التكيُّفية الثابتة" في التطبيقات التي تضع إعلانات البانر في محتوى قابل للتمرير. لمزيد من التفاصيل، يُرجى الاطّلاع على إعلانات البانر التكيُّفية المضمّنة.