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

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

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

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

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

  • أكمِل دليل البدء.
  • اختياري: للحصول على مثال على عملية تنفيذ "إعلانات البانر"، اختَر أحد التطبيقات النموذجية التالية:
    • مثال على إعلانات البانر التكيُّفية الثابتة باستخدام Java أو Kotlin أو Jetpack Compose
    • العرض التوضيحي للميزات المتقدّمة في Java أو Kotlin

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

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

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

/21775744923/example/adaptive-banner

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

لمزيد من المعلومات حول طريقة عمل الإعلانات الاختبارية في حزمة Google Mobile Ads SDK، راجِع مقالة تفعيل الإعلانات الاختبارية.

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

تنسيق 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

  1. أدرِج الوحدة JetpackComposeDemo/compose-util. تتضمّن هذه الوحدة أدوات مساعدة لإنشاء العنصر AdView ومواد العرض.

  2. إنشاء صف BannerAd من وحدة compose-util:


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

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

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

Java

// Request an anchored adaptive banner with a width of 360.
adView.setAdSize(AdSize.getCurrentOrientationAnchoredAdaptiveBannerAdSize(this, 360));

Kotlin

// Request an anchored adaptive banner with a width of 360.
adView.setAdSize(AdSize.getCurrentOrientationAnchoredAdaptiveBannerAdSize(this, 360))

Jetpack Compose


// Set the adaptive banner ad size with a given width.
val adSize = AdSize.getCurrentOrientationAnchoredAdaptiveBannerAdSize(LocalContext.current, 360)
adView.setAdSize(adSize)

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

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

Java


// 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 an anchored adaptive banner with a width of 360.
adView.setAdSize(AdSize.getCurrentOrientationAnchoredAdaptiveBannerAdSize(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 = ADMANANGER_ADAPTIVE_BANNER_AD_UNIT_ID

// Set the adaptive banner ad size with a given width.
val adSize = AdSize.getCurrentOrientationAnchoredAdaptiveBannerAdSize(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) }
}

تحميل إعلان

بعد إعداد AdManagerAdView، تتمثّل الخطوة التالية في تحميل إعلان. يتم ذلك باستخدام طريقة loadAd() في الفئة AdManagerAdView. تتلقّى هذه الدالة AdManagerAdRequest مَعلمة تتضمّن معلومات وقت التشغيل، مثل معلومات الاستهداف، حول طلب إعلان واحد.

في ما يلي مثال يوضّح كيفية تحميل إعلان:

Java

AdManagerAdRequest adRequest = new AdManagerAdRequest.Builder().build();
adView.loadAd(adRequest);

Kotlin

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

في حال نجاح العملية، يصبح تطبيقك جاهزًا لعرض الإعلانات الصورية.

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

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

إلغاء حجز مورد إعلان

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

لتحرير مورد الإعلان، عليك إزالة الإعلان من بنية العرض وإلغاء جميع مراجع الإعلان:

Java

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
}

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

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

Java

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 التي تستخدم الإعلانات.

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

إذا كان تطبيقك لا يعمل بشكل صحيح عند تفعيل ميزة "تسريع الأجهزة" على مستوى العالم، يمكنك التحكّم فيها للأنشطة الفردية أيضًا. لتفعيل ميزة &quot;تسريع الأجهزة&quot; أو إيقافها، يمكنك استخدام السمة 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>

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

احتساب عدد مرات الظهور يدويًا

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

يمكنك إرسال إشارات ping لمرّات الظهور يدويًا إلى "مدير إعلانات Google" إذا كانت لديك شروط خاصة لتسجيل مرّة الظهور:

Java

if (adManagerAdView != null) {
  adManagerAdView.setManualImpressionsEnabled(true);
}

Kotlin

adManagerAdView?.setManualImpressionsEnabled(true)

عند التأكّد من أنّه تم عرض الإعلان بنجاح على الشاشة، يمكنك تسجيل مرّة ظهور يدويًا باتّباع الخطوات التالية:

Java

if (adManagerAdView != null) {
  adManagerAdView.recordManualImpression();
}

Kotlin

adManagerAdView?.recordManualImpression()

أحداث التطبيقات

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

يمكنك الاستماع إلى أحداث التطبيق الخاصة بـ "مدير إعلانات Google" باستخدام AppEventListener. يمكن أن تحدث هذه الأحداث في أي وقت خلال دورة حياة الإعلان، حتى قبل استدعاء onAdLoaded().

اضبط AppEventListener على AdManagerAdView:

Java

if (adManagerAdView != null) {
  adManagerAdView.setAppEventListener(this);
}

Kotlin

adManagerAdView?.appEventListener = this

في ما يلي مثال يوضّح كيفية تغيير لون خلفية تطبيقك استنادًا إلى حدث تطبيق يحمل اسم لون:

Java

@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.

Java Kotlin JetpackCompose

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

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

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

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

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

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