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

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

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

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

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

• أكمل دليل البدء.

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

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

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

/6499/example/adaptive-banner

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

لمزيدٍ من المعلومات عن آلية عمل الإعلانات الاختبارية في "حزمة تطوير البرامج (SDK) لإعلانات الأجهزة الجوّالة"، اطّلِع على الإعلانات الاختبارية.

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

الخطوة الأولى نحو عرض البانر هي وضع AdManagerAdView في تنسيق Activity أو Fragment الذي تريد عرضه فيه.:

Java

private AdSize getAdSize() {
  // Determine the screen width (less decorations) to use for the ad width.
  Display display = getWindowManager().getDefaultDisplay();
  DisplayMetrics outMetrics = new DisplayMetrics();
  display.getMetrics(outMetrics);

  float density = outMetrics.density;

  float adWidthPixels = adContainerView.getWidth();

  // If the ad hasn't been laid out, default to the full screen width.
  if (adWidthPixels == 0) {
    adWidthPixels = outMetrics.widthPixels;
  }

  int adWidth = (int) (adWidthPixels / density);
  return AdSize.getCurrentOrientationAnchoredAdaptiveBannerAdSize(this, adWidth);
}

private void loadBanner() {
  
  // Create a new ad view.
  AdManagerAdView adView = new AdManagerAdView(this);
  adView.setAdSizes(getAdSize());
  adView.setAdUnitId("/6499/example/adaptive-banner");

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

  // Start loading the ad in the background.
  AdManagerAdRequest adRequest = new AdManagerAdRequest.Builder().build();
  adView.loadAd(adRequest);
}

Kotlin

// Determine the screen width (less decorations) to use for the ad width.
// If the ad hasn't been laid out, default to the full screen width.
private val adSize: AdSize
  get() {
    val display = windowManager.defaultDisplay
    val outMetrics = DisplayMetrics()
    display.getMetrics(outMetrics)

    val density = outMetrics.density

    var adWidthPixels = binding.adViewContainer.width.toFloat()
    if (adWidthPixels == 0f) {
      adWidthPixels = outMetrics.widthPixels.toFloat()
    }

    val adWidth = (adWidthPixels / density).toInt()
    return AdSize.getCurrentOrientationAnchoredAdaptiveBannerAdSize(this, adWidth)
  }

private fun loadBanner() {
  
  // Create a new ad view.
  val adView = AdManagerAdView(this)
  adView.adSizes = adSize
  adView.adUnitId = "/6499/example/adaptive-banner"

  // Create an ad request.
  val adRequest = AdManagerAdRequest.Builder().build()

  // Start loading the ad in the background.
  adView.loadAd(adRequest)
}

تحميل إعلان

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

نقطة رئيسية: أجرِ جميع الطلبات إلى حزمة تطوير البرامج (SDK) لإعلانات الأجهزة الجوّالة في سلسلة المحادثات الرئيسية.

في ما يلي مثال يوضّح كيفية تحميل إعلان في طريقة onCreate() على Activity:

Java

private void loadBanner() {
  // Create a new ad view.
  adView = new AdManagerAdView(this);
  adView.setAdUnitId(AD_UNIT);
  adView.setAdSize(getAdSize());
  
  // Replace ad container with new ad view.
  adContainerView.removeAllViews();
  adContainerView.addView(adView);

  // Start loading the ad in the background.
  AdManagerAdRequest adRequest = new AdManagerAdRequest.Builder().build();
  adView.loadAd(adRequest);
}

Kotlin

private fun loadBanner() {
  // This is an ad unit ID for a test ad. Replace with your own banner ad unit ID.
  adView.adUnitId = "/6499/example/banner"
  adView.setAdSize(adSize)
  
  // Create an ad request.
  val adRequest = AdManagerAdRequest.Builder().build()

  // Start loading the ad in the background.
  adView.loadAd(adRequest)
}

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

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

أكملت هذه الخطوة. تطبيقك جاهز الآن لعرض إعلانات البانر.

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

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

Java

AdManagerAdView.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(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

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

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

Java

AdManagerAdRequest adRequest = new AdManagerAdRequest.Builder()
    .setManualImpressionsEnabled(true)
    .build();

Kotlin

val adRequest = AdManagerAdRequest.Builder()
    .setManualImpressionsEnabled(true)
    .build()

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

Java

AdManagerAdView.recordManualImpression();

Kotlin

AdManagerAdView.recordManualImpression()

نقطة رئيسية: يتم عادةً تنشيط مرات الظهور عند استدعاء الإجراء onAdLoaded(). ننصحك باستخدام هذه الميزة فقط إذا أردت تسجيل مرّات الظهور في وقت مختلف.

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

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

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

Java

public interface AppEventListener {
  void onAppEvent(String name, String info);
}

Kotlin

interface AppEventListener {
    fun onAppEvent(name: String, info: String)
}

يتم استدعاء void onAppEvent(String name, String info) عند وقوع حدث في التطبيق في أحد الإعلانات. يمكن تنفيذ هذه الواجهة من خلال نشاطك أو أي عنصر آخر:

Java

import com.google.android.gms.ads.admanager.*;

public class BannerExample extends Activity implements AppEventListener {
}

Kotlin

import com.google.android.gms.ads.admanager.*

class BannerExample : Activity(), AppEventListener {
}

ثم تم تمريرها إلى AdManagerAdView:

Java

AdManagerAdView.setAppEventListener(this);

Kotlin

AdManagerAdView.appEventListener = this

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

Java

@Override
public void onAppEvent(String name, String info) {
  if ("color".equals(name)) {
    if ("green".equals(info)) {
      // Set background color to green.
    } else if ("blue".equals(info)) {
      // Set background color to blue.
    } else {
      // Set background color to black.
    }
  }
}

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>

اطّلع على مثال على أحداث التطبيقات في "مدير الإعلانات" لتنفيذ أحداث التطبيق في تطبيق واجهة برمجة التطبيقات التجريبي.

Java Kotlin

مصادر إضافية

أمثلة على GitHub

• مثال على إعلانات البانر التكيُّفية الثابتة: Java | Kotlin

• العرض التوضيحي للميزات المتقدّمة: Java | Kotlin

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

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

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

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

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

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

• خصوصية المستخدم
• تحسين إعداد حزمة تطوير البرامج (SDK) وتحميل الإعلانات (إصدار تجريبي)