يتناول هذا الدليل كيفية تحميل "إعلان بانر تكيُّفي ثابت" في تطبيق 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)
اضبط حجم الإعلان على قيمة أصغر من حجم شاشة الجهاز أو مساوية له.
لتحديد الحد الأقصى لحجم الشاشة، استخدِم الطريقة
Resources.getDisplayMetrics. تستخدم أبعاد العنصر AdSize وحدات بكسل مستقلة الكثافة (dp). عند المقارنة، قم بتحويل حجم
الشاشة من بكسل إلى dp.
لمعرفة التفاصيل حول قيود الحجم، يُرجى الاطّلاع على مقالة تحديد المشاكل وحلّها في ما يتعلّق بمرّات الظهور غير المعروضة في "إدارة إعلانات Google".
إضافة "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>
يمكنك الاطّلاع على دليل تسريع الأجهزة لمزيد من المعلومات حول خيارات التحكّم في تسريع الأجهزة. يُرجى العِلم أنّه لا يمكن تفعيل مشاهدات الإعلانات الفردية لميزة "تسريع الأجهزة" إذا كان النشاط غير مفعَّل، لذا يجب أن يكون النشاط نفسه مفعَّلاً لميزة "تسريع الأجهزة".
احتساب عدد مرّات الظهور يدويًا
يتوافق الاحتساب اليدوي لعدد مرات الظهور مع الحملات المبيعة مباشرةً والحملات الذاتية التي تتضمّن تصاميم إعلانات يتم عرضها مباشرةً في "مدير الإعلانات". ويجب عدم استخدامه في الإعلانات الاحتياطية أو إعلانات الشبكات التابعة لجهات خارجية. لمزيد من التفاصيل، يُرجى الاطّلاع على احتساب مرّات الظهور والنقرات.
يمكنك إرسال إشعارات مرّات الظهور يدويًا إلى "مدير إعلانات 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.
الخطوات التالية
إعلانات البانر القابلة للتصغير
إعلانات البانر القابلة للتصغير هي إعلانات بانر تظهر في البداية كتراكب أكبر، مع زر لتصغير الإعلان إلى حجم أصغر. ننصحك باستخدامها لتحسين أدائك بشكل أكبر. لمزيد من التفاصيل، يُرجى الاطّلاع على إعلانات البانر القابلة للتصغير.
إعلانات البانر التكيّفية المضمّنة
"إعلانات البانر التكيُّفية" المضمّنة هي أكبر وأطول مقارنةً بـ "إعلانات البانر التكيُّفية الثابتة". ويختلف ارتفاعها، ويمكن أن يكون بطول شاشة الجهاز. ننصح باستخدام "إعلانات البانر التكيُّفية المضمّنة" بدلاً من "إعلانات البانر التكيُّفية الثابتة" في التطبيقات التي تضع إعلانات البانر في محتوى قابل للتمرير. يمكنك الاطّلاع على البانرات التكيّفية المضمّنة لمزيد من التفاصيل.