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

اختيار النظام الأساسي: Android (إصدار تجريبي)

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

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

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

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

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

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

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

ca-app-pub-3940256099942544/9214589741

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

لمزيد من المعلومات عن طريقة عمل GMA Next-Gen SDK الإعلانات الاختبارية، اطّلِع على مقالة تفعيل الإعلانات الاختبارية.

إنشاء عنصر `AdView`

لعرض البانرات، اتّبِع الخطوات التالية:

Kotlin

استخدام إصدارات حزمة تطوير البرامج (SDK) من ‎0.22.0-beta01 إلى ‎0.22.0-beta04

هناك خطأ معروف في الإصدار 0.22.0 يمنع إنشاء مثيل AdView في Kotlin. اكتب طريقة مساعدة بلغة Java تنشئ العنصر AdView:

// AdViewJavaHelper.java
import android.content.Context;
import com.google.android.libraries.ads.mobile.sdk.banner.AdView;

public class AdViewJavaHelper {
  public static AdView createAdView(Context context) {
    return new AdView(context);
  }
}

بعد ذلك، استدعِ هذه الدالة المساعدة من رمز Kotlin لإنشاء مثيل AdView:

private fun createAdView(adViewContainer: FrameLayout, activity: Activity) {
  val adView = AdViewJavaHelper.createAdView(activity)
  adViewContainer.addView(adView)
}

استخدام الإصدار 0.23.0-beta01 أو إصدار أحدث من حزمة SDK (سيتم إطلاقه قريبًا)

أنشئ عنصر AdView.
أضِف العنصر AdView إلى تصميم تطبيقك.

ينشئ المثال التالي العنصر AdView ويضيفه إلى تصميم تطبيق:

private fun createAdView(adViewContainer: FrameLayout, activity: Activity) {
  val adView = AdView(activity)
  adViewContainer.addView(adView)
}

جافا

أنشئ عنصر AdView.
أضِف العنصر AdView إلى تصميم تطبيقك.

ينشئ المثال التالي العنصر AdView ويضيفه إلى تصميم تطبيق:

private void createAdView(FrameLayout adViewContainer, Activity activity) {
  AdView adView = new AdView(activity);
  adViewContainer.addView(adView);
}

تنسيق XML

أضِف عنصر AdView إلى ملف XML الخاص بالتصميم:

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

  <com.google.android.libraries.ads.mobile.sdk.banner.AdView
      android:id="@+id/adView"
      android:layout_width="wrap_content"
      android:layout_height="wrap_content"
      app:layout_constraintBottom_toBottomOf="parent"
      app:layout_constraintEnd_toEndOf="parent"
      app:layout_constraintStart_toStartOf="parent" />
</androidx.constraintlayout.widget.ConstraintLayout>

Jetpack Compose

أدرِج عنصر AndroidView في واجهة مستخدم Compose.
حدِّد متغيّر mutableStateOf<BannerAd?> لتخزين إعلان البانر:

// Initialize required variables.
val context = LocalContext.current
var bannerAdState by remember { mutableStateOf<BannerAd?>(null) }

// The AdView is placed at the bottom of the screen.
Column(modifier = modifier.fillMaxSize(), verticalArrangement = Arrangement.Bottom) {
  bannerAdState?.let { bannerAd ->
    Box(modifier = Modifier.fillMaxWidth()) {
      // Display the ad within an AndroidView.
      AndroidView(
        modifier = modifier.wrapContentSize(),
        factory = { bannerAd.getView(requireActivity()) },
      )
    }
  }
}

تحميل إعلان

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

Kotlin

private fun loadBannerAd(adView: AdView, activity: Activity) {
  // Get a BannerAdRequest for a 360 wide anchored adaptive banner ad.
  val adSize = AdSize.getCurrentOrientationAnchoredAdaptiveBannerAdSize(activity, 360)
  val adRequest = BannerAdRequest.Builder(AD_UNIT_ID, adSize).build()

  adView.loadAd(
    adRequest,
    object : AdLoadCallback<BannerAd> {
      override fun onAdLoaded(ad: BannerAd) {
        ad.adEventCallback =
          object : BannerAdEventCallback {
            override fun onAdImpression() {
              Log.d(TAG, "Banner ad recorded an impression.")
            }

            override fun onAdClicked() {
              Log.d(TAG, "Banner ad clicked.")
            }
          }
      }

      override fun onAdFailedToLoad(adError: LoadAdError) {
        Log.e(TAG, "Banner ad failed to load: $adError")
      }
    },
  )
}

جافا

private void loadBannerAd(AdView adView, Activity activity) {
  // Get a BannerAdRequest for a 360 wide anchored adaptive banner ad.
  AdSize adSize = AdSize.getCurrentOrientationAnchoredAdaptiveBannerAdSize(activity, 360);
  BannerAdRequest adRequest = new BannerAdRequest.Builder(AD_UNIT_ID, adSize).build();

  adView.loadAd(
      adRequest,
      new AdLoadCallback<BannerAd>() {
        @Override
        public void onAdLoaded(@NonNull BannerAd bannerAd) {
          bannerAd.setAdEventCallback(
              new BannerAdEventCallback() {
                @Override
                public void onAdImpression() {
                  Log.d(TAG, "Banner ad recorded an impression.");
                }

                @Override
                public void onAdClicked() {
                  Log.d(TAG, "Banner ad clicked.");
                }
              });
        }

        @Override
        public void onAdFailedToLoad(@NonNull LoadAdError adError) {
          Log.e(TAG, "Banner ad failed to load: " + adError);
        }
      });
}

Jetpack Compose

// Request an anchored adaptive banner with a width of 360.
val adSize = AdSize.getCurrentOrientationAnchoredAdaptiveBannerAdSize(requireContext(), 360)

// Load the ad when the screen is active.
val coroutineScope = rememberCoroutineScope()
val isPreviewMode = LocalInspectionMode.current
LaunchedEffect(context) {
  bannerAdState?.destroy()
  if (!isPreviewMode) {
    coroutineScope.launch {
      when (val result = BannerAd.load(BannerAdRequest.Builder(AD_UNIT_ID, adSize).build())) {
        is AdLoadResult.Success -> {
          bannerAdState = result.ad
        }
        is AdLoadResult.Failure -> {
          showToast("Banner failed to load.")
          Log.w(Constant.TAG, "Banner ad failed to load: $result.error")
        }
      }
    }
  }
}

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

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

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

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

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

Kotlin

// 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

جافا

// Remove banner from view hierarchy.
if (adView.getParent() instanceof ViewGroup) {
  ((ViewGroup) adView.getParent()).removeView(adView);
}
// Destroy the banner ad resources.
adView.destroy();
// Drop reference to the banner ad.
adView = null;

Jetpack Compose


// Destroy the ad when the screen is disposed.
DisposableEffect(Unit) { onDispose { bannerAdState?.destroy() } }

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

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

Kotlin

BannerAd.load(
  BannerAdRequest.Builder("ca-app-pub-3940256099942544/9214589741", adSize).build(),
  object : AdLoadCallback<BannerAd> {
    override fun onAdLoaded(ad: BannerAd) {
      ad.adEventCallback =
        object : BannerAdEventCallback {
          override fun onAdImpression() {
            // Banner ad recorded an impression.
          }

          override fun onAdClicked() {
            // Banner ad recorded a click.
          }

          override fun onAdShowedFullScreenContent() {
            // Banner ad showed.
          }

          override fun onAdDismissedFullScreenContent() {
            // Banner ad dismissed.
          }

          override fun onAdFailedToShowFullScreenContent(
            fullScreenContentError: FullScreenContentError
          ) {
            // Banner ad failed to show.
          }
        }
    }
    // ...
  }
)

جافا

BannerAd.load(
    new BannerAdRequest.Builder("ca-app-pub-3940256099942544/9214589741", adSize).build(),
    new AdLoadCallback<BannerAd>() {
      @Override
      public void onAdLoaded(@NonNull BannerAd ad) {
        ad.setAdEventCallback(new BannerAdEventCallback() {
          @Override
          public void onAdImpression() {
            // Banner ad recorded an impression.
          }

          @Override
          public void onAdClicked() {
            // Banner ad recorded a click.
          }

          @Override
          public void onAdShowedFullScreenContent() {
            // Banner ad showed.
          }

          @Override
          public void onAdDismissedFullScreenContent() {
            // Banner ad dismissed.
          }

          @Override
          public void onAdFailedToShowFullScreenContent(
              @NonNull FullScreenContentError fullScreenContentError) {
            // Banner ad failed to show.
          }
        });

        // ...
      }
    });

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

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

Kotlin

BannerAd.load(
  BannerAdRequest.Builder("ca-app-pub-3940256099942544/9214589741", adSize).build(),
  object : AdLoadCallback<BannerAd> {
    override fun onAdLoaded(ad: BannerAd) {
      ad.bannerAdRefreshCallback =
        object : BannerAdRefreshCallback {
          // Set the ad refresh callbacks.
          override fun onAdRefreshed() {
            // Called when the ad refreshes.
          }

          override fun onAdFailedToRefresh(loadAdError: LoadAdError) {
            // Called when the ad fails to refresh.
          }
        }

      // ...
    }
  }
)

جافا

BannerAd.load(
    new BannerAdRequest.Builder("ca-app-pub-3940256099942544/9214589741", adSize).build(),
    new AdLoadCallback<BannerAd>() {
      @Override
      public void onAdLoaded(@NonNull BannerAd ad) {
        ad.setBannerAdRefreshCallback(
            // Set the ad refresh callbacks.
            new BannerAdRefreshCallback() {
              @Override
              public void onAdRefreshed() {
                // Called when the ad refreshes.
              }

              @Override
              public void onAdFailedToRefresh(@NonNull LoadAdError adError) {
                // Called when the ad fails to refresh.
              }
            });
        // ...
      }
    });

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

لكي تظهر إعلانات الفيديو بنجاح في مشاهدات إعلانات البانر، يجب تفعيل تسريع الأجهزة.

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

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

نزِّل التطبيق النموذجي الذي يوضّح كيفية استخدام GMA Next-Gen SDK وشغِّله.

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

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

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

إنشاء عنصر AdView

Kotlin

استخدام إصدارات حزمة تطوير البرامج (SDK) من ‎0.22.0-beta01 إلى ‎0.22.0-beta04

استخدام الإصدار 0.23.0-beta01 أو إصدار أحدث من حزمة SDK (سيتم إطلاقه قريبًا)

جافا

تنسيق XML

Jetpack Compose

تحميل إعلان

Kotlin

جافا

Jetpack Compose

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

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

Kotlin

جافا

Jetpack Compose

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

Kotlin

جافا

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

Kotlin

جافا

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

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

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

إنشاء عنصر `AdView`