حزمة "SDK لإعلانات Google على الأجهزة الجوّالة" في وضع الصيانة للحصول على آخر التحديثات والميزات، عليك migrate وإعداد "الجيل التالي من SDK لإعلانات Google على الأجهزة الجوّالة".

تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

إعداد إعلانات البانر

اختيار النظام الأساسي: Android iOS Unity Flutter Android (قديم)

إعلانات البانر هي إعلانات مستطيلة تشغل جزءًا من تصميم التطبيق. "إعلانات البانر التكيُّفية الثابتة" هي إعلانات ذات نسبة عرض إلى ارتفاع ثابتة تظل معروضة على الشاشة أثناء تفاعل المستخدمين مع التطبيق، إما في الجزء العلوي أو السفلي من الشاشة.

يتناول هذا الدليل كيفية تحميل "إعلان بانر تكيُّفي ثابت" في تطبيق Android.

المتطلبات الأساسية

إعداد Google Mobile Ads SDK (Legacy)
اختياري: للاطّلاع على مثال على تنفيذ "إعلانات البانر"، اختَر أحد نماذج التطبيقات التالية:
- مثال على "إعلانات البانر التكيُّفية الثابتة" في Java أو Kotlin أو Jetpack Compose.
- العرض التوضيحي للميزات المتقدّمة في Java أو Kotlin

اختبِر دائمًا باستخدام الإعلانات الاختبارية

عند إنشاء تطبيقاتك واختبارها، تأكَّد من استخدام الإعلانات الاختبارية بدلاً من الإعلانات المباشرة والإنتاجية. وقد يؤدي عدم إجراء ذلك إلى تعليق حسابك.

أسهل طريقة لتحميل الإعلانات الاختبارية هي استخدام معرّف الوحدة الإعلانية الاختبارية المخصّص لإعلانات البانر على Android:

ca-app-pub-3940256099942544/9214589741

تم إعدادها خصيصًا لعرض إعلانات اختبارية لكل طلب، ويمكنك استخدامها في تطبيقاتك أثناء الترميز والاختبار وتصحيح الأخطاء. احرص على استبداله بمعرّف الوحدة الإعلانية الخاص بك قبل نشر تطبيقك.

لمزيد من المعلومات حول طريقة عمل الإعلانات الاختبارية في 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 Utilities. يتضمّن هذا المجلد أدوات مساعدة لإنشاء عنصر AdView ومواد العرض.
إنشاء AdView:


// Place the ad view at the bottom of the screen.
Column(modifier = modifier.fillMaxSize(), verticalArrangement = Arrangement.Bottom) {
  Box(modifier = modifier.fillMaxWidth()) { BannerAd(adView, modifier) }
}BannerScreen.kt

ضبط حجم الإعلان

توفّر "إعلانات البانر التكيُّفية" الكبيرة شكل إعلان أكبر مصمّمًا للتنسيقات التي لا تتضمّن إمكانية التمرير. مقارنةً بـ "إعلانات البانر التكيُّفية الثابتة" العادية، تتيح هذه الإعلانات حدًا أقصى للارتفاع يصل إلى% 20 من ارتفاع الشاشة، ويتراوح بين 50 و150 بكسل مستقل الكثافة. تم تحسين هذه المساحة الإضافية لمحتوى الفيديو.

اضبط AdSize على نوع "إعلان بانر تكيُّفي ثابت" بعرض محدّد:

جافا


// Request a large anchored adaptive banner with a width of 360.
adView.setAdSize(AdSize.getLargeAnchoredAdaptiveBannerAdSize(this, 360));MyActivity.java

Kotlin


// Request a large anchored adaptive banner with a width of 360.
adView.setAdSize(AdSize.getLargeAnchoredAdaptiveBannerAdSize(this, 360))MainActivity.kt

Jetpack Compose


// Set a large anchored adaptive banner ad size with a given width.
val adSize = AdSize.getLargeAnchoredAdaptiveBannerAdSize(LocalContext.current, 360)
adView.setAdSize(adSize)BannerScreen.kt

اضبط حجم الإعلان على قيمة أصغر من حجم شاشة الجهاز أو مساوية له. لتحديد الحد الأقصى لحجم الشاشة، استخدِم الطريقة Resources.getDisplayMetrics. تستخدم أبعاد العنصر AdSize وحدات بكسل مستقلة الكثافة (dp). عند المقارنة، قم بتحويل حجم الشاشة من بكسل إلى dp. لمعرفة التفاصيل حول قيود الحجم، يُرجى الاطّلاع على متطلبات حجم طلب عرض الإعلان.

إضافة "`AdView`" إلى التنسيق

أنشئ AdView باستخدام حجم الإعلان لإضافته إلى تنسيق تطبيقك:

جافا


// Create a new ad view.
adView = new AdView(this);
adView.setAdUnitId(AD_UNIT_ID);
// Request a large anchored adaptive banner with a width of 360.
adView.setAdSize(AdSize.getLargeAnchoredAdaptiveBannerAdSize(this, 360));

// Replace ad container with new ad view.
adContainerView.removeAllViews();
adContainerView.addView(adView);MyActivity.java

Kotlin


// Create a new ad view.
val adView = AdView(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)MainActivity.kt

Jetpack Compose


val adView = remember { AdView(context) }

// Setup and load the adview.
// Set the unique ID for this specific ad unit.
adView.adUnitId = 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()) { BannerAd(adView, modifier) }
}BannerScreen.kt

تحميل إعلان

يحمّل المثال التالي "إعلان بانر تكيُّفي ثابت" بعرض 360 في عنصر AdView:

جافا

AdRequest adRequest = new AdRequest.Builder().build();
adView.loadAd(adRequest);MyActivity.java

Kotlin

val adRequest = AdRequest.Builder().build()
adView.loadAd(adRequest)MainActivity.kt

إعادة تحميل إعلان

إذا ضبطت وحدتك الإعلانية لإعادة التحميل، لن تحتاج إلى طلب إعلان آخر عند تعذُّر تحميل الإعلان. تلتزم Google Mobile Ads SDK (Legacy) بأي معدّل إعادة تحميل تحدّده في واجهة مستخدم AdMob. إذا لم تفعّل ميزة إعادة التحميل، أرسِل طلبًا جديدًا. لمزيد من التفاصيل حول إعادة تحميل الوحدات الإعلانية، مثل ضبط معدّل إعادة التحميل، يُرجى الاطّلاع على ضبط خيار إعادة التحميل التلقائية لـ "إعلانات البانر".

إصدار مورد إعلاني

عند الانتهاء من استخدام "إعلان بانر"، يمكنك إزالة موارد "إعلان البانر".

لتحرير موارد الإعلان، عليك إزالة الإعلان من هيكلية طرق العرض وإسقاط جميع مَراجعه:

جافا

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;
}
BannerSnippets.java

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
}
BannerSnippets.kt

Jetpack Compose

DisposableEffect(Unit) {
  // Destroy the AdView to prevent memory leaks when the screen is disposed.
  onDispose { adView.destroy() }
}BannerScreen.kt

أحداث الإعلانات

يمكنك الاستماع إلى عدد من الأحداث في مراحل نشاط الإعلان، بما في ذلك التحميل ومرّات ظهور الإعلان والنقرات، بالإضافة إلى أحداث فتح الإعلان وإغلاقه. ننصحك بضبط دالة الاستدعاء قبل تحميل إعلان البانر.

جافا

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.
        }
      });
}BannerSnippets.java

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.
    }
  }BannerSnippets.kt

تتوافق كل طريقة من الطرق القابلة للتجاوز في AdListener مع حدث في مراحل نشاط الإعلان.

الطرق القابلة للتجاوز
`onAdClicked()`	يتم استدعاء الإجراء `onAdClicked()` عند تسجيل نقرة على إعلان.
`onAdClosed()`	يتم استدعاء الإجراء `onAdClosed()` عندما يعود المستخدم إلى التطبيق بعد الاطّلاع على عنوان URL المقصود للإعلان. ويمكن لتطبيقك استخدامها لاستئناف الأنشطة المعلّقة أو تنفيذ أي عمل آخر ضروري لجعله جاهزًا للتفاعل. يُرجى الرجوع إلى مثال AdListener في AdMob للاطّلاع على كيفية تنفيذ طرق مستمع الإعلانات في تطبيق Android API Demo.
`onAdFailedToLoad()`	الطريقة `onAdFailedToLoad()` هي الطريقة الوحيدة التي تتضمّن مَعلمة. تصف مَعلمة الخطأ من النوع `LoadAdError` الخطأ الذي حدث. لمزيد من المعلومات، يُرجى الرجوع إلى مستندات تصحيح أخطاء تحميل الإعلانات.
`onAdImpression()`	يتم استدعاء الإجراء `onAdImpression()` عند تسجيل مرّة ظهور لإعلان.
`onAdLoaded()`	يتم تنفيذ طريقة `onAdLoaded()` عند انتهاء تحميل الإعلان. إذا أردت تأخير إضافة `AdView` إلى نشاطك أو الجزء الخاص بك إلى أن تتأكّد من تحميل الإعلان، على سبيل المثال، يمكنك إجراء ذلك هنا.
`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>

يمكنك الاطّلاع على دليل تسريع الأجهزة لمزيد من المعلومات حول خيارات التحكّم في تسريع الأجهزة. يُرجى العِلم أنّه لا يمكن تفعيل ميزة "تسريع الأجهزة" لمشاهدات الإعلانات الفردية إذا كان النشاط غير مفعَّل، لذا يجب تفعيل ميزة "تسريع الأجهزة" للنشاط نفسه.

الخطوات التالية

إعلانات البانر القابلة للتصغير

"إعلانات البانر القابلة للتصغير" هي إعلانات بانر تظهر في البداية كتراكب أكبر، مع زر لتصغير الإعلان إلى حجم أصغر. ننصحك باستخدامها لتحسين أدائك بشكل أكبر. لمزيد من التفاصيل، يُرجى الاطّلاع على إعلانات البانر القابلة للتصغير.

إعلانات البانر التكيّفية المضمّنة

"إعلانات البانر التكيُّفية" المضمّنة هي أكبر وأطول مقارنةً بـ "إعلانات البانر التكيُّفية الثابتة". ويختلف ارتفاعها، ويمكن أن يكون بطول شاشة الجهاز. ننصح باستخدام "إعلانات البانر التكيُّفية المضمّنة" بدلاً من "إعلانات البانر التكيُّفية الثابتة" في التطبيقات التي تضع إعلانات البانر في محتوى يمكن تصفّحه بالانتقال للأعلى والأسفل. لمزيد من التفاصيل، يُرجى الاطّلاع على إعلانات البانر التكيُّفية المضمّنة.

إعداد إعلانات البانر تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

المتطلبات الأساسية

اختبِر دائمًا باستخدام الإعلانات الاختبارية

تحديد طريقة عرض الإعلان

تنسيق XML

Jetpack Compose

ضبط حجم الإعلان

جافا

Kotlin

Jetpack Compose

إضافة "AdView" إلى التنسيق

جافا

Kotlin

Jetpack Compose

تحميل إعلان

جافا

Kotlin

إعادة تحميل إعلان

إصدار مورد إعلاني

جافا

Kotlin

Jetpack Compose

أحداث الإعلانات

جافا

Kotlin

تسريع الأجهزة لإعلانات الفيديو

تفعيل ميزة "تسريع الأجهزة"

الخطوات التالية

إعلانات البانر القابلة للتصغير

إعلانات البانر التكيّفية المضمّنة

استكشاف مواضيع أخرى

إعداد إعلانات البانر

إضافة "`AdView`" إلى التنسيق