يغطّي هذا الدليل كيفية تحميل إعلان بانر تكيُّفي ثابت في تطبيق Android.
المتطلبات الأساسية
الاختبار دائمًا باستخدام الإعلانات الاختبارية
عند إنشاء تطبيقاتك واختبارها، احرص على استخدام الإعلانات الاختبارية بدلاً من الإعلانات الفعلية. وقد يؤدي عدم إجراء ذلك إلى تعليق حسابك.
أسهل طريقة لتحميل الإعلانات الاختبارية هي استخدام رقم تعريف الوحدة الإعلانية الاختبارية المخصّص لإعلانات البانر على Android:
/21775744923/example/adaptive-banner
تم إعداد هذا الرقم خصيصًا لعرض إعلانات اختبارية لكل طلب، ويمكنك استخدامه في تطبيقاتك الخاصة أثناء الترميز والاختبار وتحديد الأخطاء وحلّها. ما عليك سوى استبداله برقم تعريف الوحدة الإعلانية الخاص بك قبل نشر تطبيقك.
لمزيد من المعلومات حول طريقة عمل الإعلانات الاختبارية GMA Next-Gen SDK، يُرجى الاطّلاع على تفعيل الإعلانات الاختبارية.
إنشاء عنصر AdView
لعرض إعلانات البانر، اتّبِع الخطوات التالية:
Kotlin
- أنشئ عنصر
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
- أنشئ عنصر
AdViewداخل كتلةremember. - أدرِج عنصر
AndroidViewفي واجهة مستخدم Compose لعرض عنصر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 })
}
}
تحميل إعلان
يحمّل المثال التالي إعلان بانر تكيُّفي ثابت بعرض 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")
}
},
)
}
جافا
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);
}
});
}
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")
}
},
)
}
}
اضبط حجم إعلان أصغر من حجم شاشة الجهاز أو مساوٍ له.
لتحديد الحد الأقصى لحجم الشاشة، استخدِم الـ
Resources.getDisplayMetrics
طريقة. تستخدم أبعاد عنصر AdSize وحدات بكسل مستقلة الكثافة (dp). عند المقارنة، عليك تحويل حجم الشاشة من وحدات البكسل إلى وحدات dp.
لمعرفة تفاصيل حول قيود الحجم، يُرجى الاطّلاع على مقالة
تحديد المشاكل وحلّها في مرّات الظهور غير المعروضة في "مدير إعلانات Google".
إعادة تحميل إعلان
إذا ضبطت وحدتك الإعلانية على إعادة التحميل، ليس عليك طلب إعلان آخر عندما يتعذّر تحميل الإعلان. GMA Next-Gen SDK تراعي أي معدّل إعادة تحميل تحدّده في واجهة مستخدم "مدير إعلانات Google". إذا لم تفعِّل إعادة التحميل، أرسِل طلبًا جديدًا. لمزيد من التفاصيل حول إعادة تحميل الوحدات الإعلانية، مثل ضبط معدّل إعادة التحميل، يُرجى الاطّلاع على معدّل إعادة تحميل الإعلانات في التطبيقات على الأجهزة الجوّالة.
إصدار مصدر إعلان
عند الانتهاء من استخدام إعلان بانر، يمكنك إصدار مصادر إعلان البانر.
لإلغاء حجز مورد الإعلان، عليك إزالة الإعلان من هيكلية طرق العرض وإزالة جميع مراجع الإعلان:
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
}
جافا
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;
}
Jetpack Compose
// Destroy the ad when the screen is disposed.
DisposableEffect(Unit) { onDispose { adView.destroy() } }
أحداث الإعلانات
يمكنك الاستماع إلى عدد من الأحداث في دورة حياة الإعلان، بما في ذلك مرّة ظهور الإعلان والنقر عليه، بالإضافة إلى فتح الإعلان وإغلاقه. يُنصح بضبط معاودة الاتصال قبل عرض إعلان البانر.
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")
}
}
}
جافا
@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);
}
});
}
تتعامل واجهة BannerAdEventCallback
مع أحداث المحتوى بملء الشاشة على النحو التالي:
التراكبات داخل التطبيق: GMA Next-Gen SDK تستدعي
onAdShowedFullScreenContentوonAdDismissedFullScreenContentفقط عندما يعرض إعلان بانر تراكبًا في تطبيقك أو يرفضه، مثل إعلان وسائط تفاعلية متقدّمة (MRAID) موسّع أو تراكب خيارات الإعلان.التنقّل الخارجي: GMA Next-Gen SDK لا تستدعي هاتَين الطريقتَين عندما يؤدي النقر على إعلان إلى التنقّل خارج تطبيقك، مثل الانتقال إلى متصفّح خارجي أو سوق تطبيقات. لرصد متى يغادر المستخدم تطبيقك أو يعود إليه بعد النقر على إعلان، استمع إلى أحداث يتم في مراحل النشاط للتطبيق بالإضافة إلى
onAdClickedطريقة.
معاودة الاتصال لإعادة تحميل الإعلان
يتعامل 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")
}
},
)
جافا
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);
}
});
تسريع الأجهزة لإعلانات الفيديو
لكي تظهر إعلانات الفيديو بنجاح في طرق عرض إعلانات البانر، يجب تفعيل ميزة "تسريع الفيديو على الجهاز".
يتم تفعيل تسريع الأجهزة تلقائيًا، ولكن قد تختار بعض التطبيقات إيقافها. إذا كان هذا ينطبق على تطبيقك، ننصحك بتفعيل ميزة "تسريع الأجهزة" لفئات 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 وشغِّله.