تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

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

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

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

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

/21775744923/example/adaptive-banner

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

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

أضِف AdManagerAdView إلى التنسيق.

يمكنك إنشاء بانر من خلال تحديد حجم الإعلان. أكمِل الخطوات التالية:

أنشئ حجم إعلان تكيُّفيًا ثابتًا بالعرض الكامل:

Java

// Get the ad size with screen width.
public AdSize getAdSize() {
  DisplayMetrics displayMetrics = getResources().getDisplayMetrics();
  int adWidthPixels = displayMetrics.widthPixels;

  if (VERSION.SDK_INT >= VERSION_CODES.R) {
    WindowMetrics windowMetrics = this.getWindowManager().getCurrentWindowMetrics();
    adWidthPixels = windowMetrics.getBounds().width();
  }

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

Kotlin

// Get the ad size with screen width.
private val adSize: AdSize
  get() {
    val displayMetrics = resources.displayMetrics
    val adWidthPixels =
      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
        val windowMetrics: WindowMetrics = this.windowManager.currentWindowMetrics
        windowMetrics.bounds.width()
      } else {
        displayMetrics.widthPixels
      }
    val density = displayMetrics.density
    val adWidth = (adWidthPixels / density).toInt()
    return AdSize.getCurrentOrientationAnchoredAdaptiveBannerAdSize(this, adWidth)
  }
MyActivity.kt

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

Java

// 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);MyActivity.java

Kotlin

// Create a new ad view.
val adView = AdManagerAdView(this)
adView.adUnitId = AD_UNIT_ID
adView.setAdSize(adSize)
this.adView = adView

// Replace ad container with new ad view.
binding.adViewContainer.removeAllViews()
binding.adViewContainer.addView(adView)MyActivity.kt

تحميل إعلان

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

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

Java

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

Kotlin

// Start loading the ad in the background.
val adRequest = AdManagerAdRequest.Builder().build()
adView.loadAd(adRequest)MyActivity.kt

إذا نجحت عملية الإعداد، يعني ذلك أنّ تطبيقك جاهز لعرض إعلانات البانر.

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

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

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

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

Java

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

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

Java

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

Kotlin

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

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

Java

{ ad_view }.recordManualImpression();

Kotlin

AdManagerAdView.recordManualImpression()

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

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

يمكنك الاستماع إلى أحداث التطبيقات المتعلّقة بخدمة "مدير إعلانات Google" باستخدام 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

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

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>

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

Java Kotlin

مراجع إضافية

أمثلة على GitHub

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

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

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