يتناول هذا الدليل كيفية تحميل "إعلان بانر تكيُّفي ثابت" في تطبيق 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)
}
Java
- أنشئ عنصر
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")
}
},
)
}
Java
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 يلتزم بأي معدّل إعادة تحميل حدّدته في واجهة مستخدم "مدير الإعلانات". إذا لم تكن قد فعّلت إعادة التحميل، أرسِل طلبًا جديدًا. لمزيد من التفاصيل حول إعادة تحميل الوحدات الإعلانية، مثل ضبط معدّل إعادة التحميل، يُرجى الاطّلاع على معدّل إعادة تحميل الإعلانات في التطبيقات على الأجهزة الجوّالة.
إلغاء حجز مورد إعلان
عند الانتهاء من استخدام إعلان بانر، يمكنك تحرير موارد إعلان البانر.
لتحرير مورد الإعلان، عليك إزالة الإعلان من بنية العرض وإلغاء جميع مراجع الإعلان:
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
Java
// 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("/21775744923/example/adaptive-banner", 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.
}
}
}
// ...
}
)
Java
BannerAd.load(
new BannerAdRequest.Builder("/21775744923/example/adaptive-banner", 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("/21775744923/example/adaptive-banner", 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.
}
}
// ...
}
}
)
Java
BannerAd.load(
new BannerAdRequest.Builder("/21775744923/example/adaptive-banner", 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 وشغِّله.