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

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

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

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

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

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

إعداد GMA Next-Gen SDK

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

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

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

ca-app-pub-3940256099942544/9214589741

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

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

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

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

Kotlin

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

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

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

جافا

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

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

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

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

أنشئ عنصر AdView داخل كتلة remember.
أدرِج عنصر AndroidView في واجهة مستخدم الإنشاء لعرض عنصر AdView:

val context = LocalContext.current
val adView = remember { AdView(context) }

// The AdView is placed at the bottom of the screen.
Column(modifier = modifier.fillMaxSize(), verticalArrangement = Arrangement.Bottom) {
  Box(modifier = modifier.fillMaxWidth()) {
    // Display the ad within an AndroidView.
    AndroidView(modifier = modifier.wrapContentSize(), factory = { adView })
  }
}ComposeBannerFragment.kt

تحميل إعلان

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

Kotlin

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

  adView.loadAd(
    adRequest,
    object : AdLoadCallback<BannerAd> {
      override fun onAdLoaded(ad: BannerAd) {
        Log.d(TAG, "Banner ad loaded.")
      }

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

جافا

private void loadBannerAd(AdView adView, Activity activity) {
  // Get a BannerAdRequest for a 360 wide large anchored adaptive banner ad.
  AdSize adSize = AdSize.getLargeAnchoredAdaptiveBannerAdSize(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) {
          Log.d(TAG, "Banner ad loaded.");
        }

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

Jetpack Compose

// Request a large anchored adaptive banner with a width of 360.
val adSize = AdSize.getLargeAnchoredAdaptiveBannerAdSize(context, 360)

// Load the ad when the screen is active.
val isPreviewMode = LocalInspectionMode.current
LaunchedEffect(adSize) {
  if (!isPreviewMode) {
    val adRequest = BannerAdRequest.Builder(AD_UNIT_ID, adSize).build()
    adView.loadAd(
      adRequest,
      object : AdLoadCallback<BannerAd> {
        override fun onAdLoaded(ad: BannerAd) {
          Log.d(Constant.TAG, "Banner ad loaded.")
        }

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

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

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

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

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

لإلغاء حجز مورد الإعلان، عليك إزالة الإعلان من هيكلية طرق عرض العناصر وإلغاء جميع مراجع الإعلان:

Kotlin

private 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

جافا

private void destroyBanner() {
  // Remove banner from view hierarchy.
  if (adView != null) {
    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;
}BannerSnippets.java

Jetpack Compose

// Destroy the ad when the screen is disposed.
DisposableEffect(Unit) { onDispose { adView.destroy() } }ComposeBannerFragment.kt

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

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

Kotlin

override fun onAdLoaded(ad: BannerAd) {
  ad.adEventCallback =
    object : BannerAdEventCallback {
      override fun onAdImpression() {
        // Banner ad recorded an impression.
        Log.d(TAG, "Banner ad recorded an impression.")
      }

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

      override fun onAdShowedFullScreenContent() {
        // Banner ad showed.
        Log.d(TAG, "Banner ad showed full screen content.")
      }

      override fun onAdDismissedFullScreenContent() {
        // Banner ad dismissed.
        Log.d(TAG, "Banner ad dismissed full screen content.")
      }

      override fun onAdFailedToShowFullScreenContent(
        fullScreenContentError: FullScreenContentError
      ) {
        // Banner ad failed to show.
        Log.w(TAG, "Banner ad failed to show full screen content: $fullScreenContentError")
      }
    }
}
BannerSnippets.kt

جافا

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

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

        @Override
        public void onAdShowedFullScreenContent() {
          // Banner ad showed.
          Log.d(TAG, "Banner ad showed full screen content.");
        }

        @Override
        public void onAdDismissedFullScreenContent() {
          // Banner ad dismissed.
          Log.d(TAG, "Banner ad dismissed full screen content.");
        }

        @Override
        public void onAdFailedToShowFullScreenContent(
            @NonNull FullScreenContentError fullScreenContentError) {
          // Banner ad failed to show.
          Log.w(
              TAG,
              "Banner ad failed to show full screen content: " + fullScreenContentError);
        }
      });
}
BannerSnippets.java

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

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

Kotlin

adView.loadAd(
  adRequest,
  object : AdLoadCallback<BannerAd> {
    override fun onAdLoaded(ad: BannerAd) {
      ad.bannerAdRefreshCallback =
        object : BannerAdRefreshCallback {
          override fun onAdRefreshed() {
            // Banner ad refreshed.
            Log.d(TAG, "Banner ad refreshed.")
          }

          override fun onAdFailedToRefresh(adError: LoadAdError) {
            // Banner ad failed to refresh.
            Log.w(TAG, "Banner ad failed to refresh: $adError")
          }
        }
    }

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

جافا

adView.loadAd(
    adRequest,
    new AdLoadCallback<BannerAd>() {
      @Override
      public void onAdLoaded(@NonNull BannerAd bannerAd) {
        bannerAd.setBannerAdRefreshCallback(
            new BannerAdRefreshCallback() {
              @Override
              public void onAdRefreshed() {
                // Banner ad refreshed.
                Log.d(TAG, "Banner ad refreshed.");
              }

              @Override
              public void onAdFailedToRefresh(@NonNull LoadAdError adError) {
                // Banner ad failed to refresh.
                Log.w(TAG, "Banner ad failed to refresh: " + adError);
              }
            });
      }

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

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

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

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

جافا

تنسيق XML

Jetpack Compose

تحميل إعلان

Kotlin

جافا

Jetpack Compose

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

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

Kotlin

جافا

Jetpack Compose

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

Kotlin

جافا

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

Kotlin

جافا

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

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

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

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