الإعلانات البينية هي إعلانات بملء الشاشة تغطي واجهة التطبيق. يمكنك عرض هذه الإعلانات في نقاط انتقال مناسبة في تطبيقك، مثلاً بين الأنشطة أو أثناء فترات الإيقاف المؤقت في مستويات اللعبة.
عندما يعرض تطبيقك إعلانًا بينيًا، يمكن للمستخدِمين النقر على الإعلان والمتابعة، أو إغلاقه والعودة إلى التطبيق. يمكنك الاطّلاع على دراسة الحالة هذه.
يوضّح هذا الدليل كيفية دمج الإعلانات البينية في تطبيق Android.
قبل البدء
قبل المتابعة، يُرجى اتّباع الخطوات التالية:
- إعداد GMA Next-Gen SDK
- استخدام رقم تعريف الوحدة الإعلانية البينية الاختبارية
ca-app-pub-3940256099942544/1033173712- عند إنشاء تطبيقك واختباره، احرص على استخدام الإعلانات الاختبارية بدلاً من الإعلانات الفعلية المعروضة. إذا لم تستخدم رقم تعريف الوحدة الإعلانية الاختبارية، يمكن أن تعلّق Google حسابك.
- قبل نشر تطبيقك، استبدِل هذا الرقم برقم تعريف وحدتك الإعلانية.
- للحصول على تفاصيل حول الإعلانات الاختبارية GMA Next-Gen SDK، يُرجى الاطّلاع على مقالة تفعيل الإعلانات الاختبارية.
فهم ميزة التحميل المسبق للإعلانات (إصدار تجريبي)
تعمل ميزة التحميل المسبق للإعلانات (إصدار تجريبي) في GMA Next-Gen SDK على أتمتة عملية تحميل الإعلانات وتخزينها مؤقتًا.
تقدّم ميزة التحميل المسبق للإعلانات المزايا التالية:
- إدارة المراجع: يتم الاحتفاظ بالمراجع إلى أن يتم عرض الإعلانات.
- إعادة التحميل التلقائي: يتم تحميل إعلان جديد عند استرداد إعلان من ذاكرة التخزين المؤقت.
- إعادة المحاولات المُدارة: يتم تحميل إعلان جديد عندما يتعذّر تحميل إعلان.
- التعامل مع انتهاء الصلاحية: يتم تعديل الإعلانات قبل انتهاء صلاحيتها.
- تحسين ذاكرة التخزين المؤقت: يتم تحسين ترتيب ذاكرة التخزين المؤقت لعرض الإعلان ذي الأولوية القصوى.
بدء التحميل المسبق للإعلانات
لبدء التحميل المسبق للإعلانات، استدعِ الطريقة startPreload() مرة واحدة عند بدء تشغيل التطبيق. بعد استدعاء الطريقة startPreload()، تحمّل
GMA Next-Gen SDK الإعلانات مسبقًا تلقائيًا وتعيد محاولة الطلبات التي تعذّر تنفيذها للإعدادات التي تم تحميلها مسبقًا.
يوضّح المثال التالي كيفية بدء التحميل المسبق للإعلانات:
Kotlin
جافا
استبدِل AD_UNIT_ID برقم تعريف وحدتك الإعلانية.
يوضّح المثال السابق كيفية استخدام رقم تعريف الوحدة الإعلانية كرقم تعريف التحميل المسبق. رقم تعريف التحميل المسبق هو معرّف سلسلة تنشئه لتحديد إعدادات التحميل المسبق للإعلانات. إذا كان تطبيقك يتطلّب إعدادات استهداف متعدّدة لرقم تعريف الوحدة الإعلانية نفسه، مرِّر معرّف سلسلة مخصّصًا.
الحصول على الإعلان الذي تم تحميله مسبقًا وعرضه
عندما تريد عرض إعلان، استدعِ الطريقة pollAd().
GMA Next-Gen SDK تستردّ إعلانًا متاحًا وتحمّل مسبقًا تلقائيًا الإعلان التالي
في الخلفية. إذا لم يتوفّر أي إعلان، لا تعرض GMA Next-Gen SDK أي إعلانات.
show لعرض الإعلان.
يوضّح المثال التالي كيفية استرداد إعلان تم تحميله مسبقًا وعرضه:
Kotlin
جافا
إلى أن تصبح مستعدًا لعرض إعلان، تجنَّب استدعاء الطريقة pollAd(). لقراءة معلومات استجابة الإعلان بدون عرضه،
يُرجى الاطّلاع على مقالة قراءة معلومات الاستجابة.
الاستماع إلى أحداث الإعلانات
قبل عرض الإعلان، استمع إلى أحداث الإعلانات. يسجِّل المثال التالي عمليات معاودة الاتصال لأحداث الإعلانات:
Kotlin
// Listen for ad events. val ad = interstitialAd if (ad == null) { Log.e(TAG, "Interstitial ad is not ready yet.") return } ad.adEventCallback = object : InterstitialAdEventCallback { override fun onAdShowedFullScreenContent() { // Interstitial ad did show. } override fun onAdDismissedFullScreenContent() { // Interstitial ad did dismiss. interstitialAd = null } override fun onAdFailedToShowFullScreenContent( fullScreenContentError: FullScreenContentError ) { // Interstitial ad failed to show. Log.e(TAG, "Interstitial ad failed to show: ${fullScreenContentError.message}") } override fun onAdImpression() { // Interstitial ad did record an impression. } override fun onAdClicked() { // Interstitial ad did record a click. } }
جافا
// Listen for ad events. if (interstitialAd == null) { Log.e(TAG, "Interstitial ad is not ready yet."); return; } interstitialAd.setAdEventCallback( new InterstitialAdEventCallback() { @Override public void onAdShowedFullScreenContent() { // Interstitial ad did show. } @Override public void onAdDismissedFullScreenContent() { // Interstitial ad did dismiss. interstitialAd = null; } @Override public void onAdFailedToShowFullScreenContent( @NonNull FullScreenContentError fullScreenContentError) { // Interstitial ad failed to show. Log.e(TAG, "Interstitial ad failed to show: " + fullScreenContentError.getMessage()); } @Override public void onAdImpression() { // Interstitial ad did record an impression. } @Override public void onAdClicked() { // Interstitial ad did record a click. } });
اختياري: الاستماع إلى أحداث التحميل المسبق
عند بدء التحميل المسبق للإعلانات، سجِّل أحداث التحميل المسبق لتلقّي إشعار عند تحميل الإعلانات مسبقًا بنجاح أو تعذّر تحميلها مسبقًا أو استنفاد ذاكرة التخزين المؤقت للإعلانات.
يوضّح المثال التالي كيفية تسجيل أحداث التحميل المسبق للإعلانات:
Kotlin
val preloadCallback = // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback. object : PreloadCallback { override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) { Log.d( TAG, ("Interstitial preload ad $preloadId failed to load with error: ${adError.message}"), ) } override fun onAdsExhausted(preloadId: String) { Log.i(TAG, "Interstitial preload ad $preloadId is not available") // [Important] Don't call ad preloader start() or pollAd() from onAdsExhausted. } override fun onAdPreloaded(preloadId: String, responseInfo: ResponseInfo) { Log.i(TAG, "Interstitial preload ad $preloadId is available") } } val adRequest = AdRequest.Builder(adUnitId).build() val preloadConfig = PreloadConfiguration(adRequest) InterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback)
جافا
PreloadCallback preloadCallback = // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback. new PreloadCallback() { @Override public void onAdFailedToPreload(@NonNull String preloadId, @NonNull LoadAdError adError) { Log.d( TAG, String.format( "Interstitial preload ad %s failed to load with error: %s", preloadId, adError.getMessage())); // [Optional] Get the error response info for additional details. // ResponseInfo responseInfo = adError.getResponseInfo(); } @Override public void onAdsExhausted(@NonNull String preloadId) { Log.i(TAG, "Interstitial preload ad " + preloadId + " is not available"); // [Important] Don't call ad preloader start() or pollAd() from onAdsExhausted. } @Override public void onAdPreloaded(@NonNull String preloadId, @NonNull ResponseInfo responseInfo) { Log.i(TAG, "Interstitial preload ad " + preloadId + " is available"); } }; AdRequest adRequest = new AdRequest.Builder(adUnitId).build(); PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest); InterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback);
عندما يتعذّر تحميل إعلان، GMA Next-Gen SDK تحمّل الإعلانات مسبقًا تلقائيًا وتعيد محاولة الطلبات التي تعذّر تنفيذها للإعدادات التي تم تحميلها مسبقًا.
اختياري: التحقّق من توفّر الإعلانات
إذا كنت بحاجة إلى معرفة ما إذا كان الإعلان متوفّرًا، تحقَّق من توفّر الإعلانات. يتحقّق المثال التالي مما إذا كان الإعلان الذي تم تحميله مسبقًا متوفّرًا:
Kotlin
private fun isAdAvailable(adUnitId: String): Boolean { return InterstitialAdPreloader.isAdAvailable(adUnitId) }
جافا
private boolean isAdAvailable(String adUnitId) { return InterstitialAdPreloader.isAdAvailable(adUnitId); }
اختياري: ضبط حجم المخزن المؤقت
يتحكّم حجم ذاكرة التخزين المؤقت في عدد الإعلانات التي تم تحميلها مسبقًا والمخزّنة في الذاكرة. تُحسِّن Google تلقائيًا حجم ذاكرة التخزين المؤقت لتحقيق التوازن بين استهلاك الذاكرة ووقت الاستجابة لعرض الإعلانات. يمكنك ضبط حجم ذاكرة التخزين المؤقت المخصّص لزيادة عدد الإعلانات المحفوظة في الذاكرة. ننصحك باستخدام حجم ذاكرة التخزين المؤقت الذي يتضمّن إعلانَين تم تحميلهما مسبقًا.
يوضّح المثال التالي كيفية ضبط حجم المخزن المؤقت:
Kotlin
private fun setBufferSize(adUnitId: String) { val adRequest = AdRequest.Builder(adUnitId).build() // Define a PreloadConfiguration and set the buffer size to 2 preloaded ads. val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 2) InterstitialAdPreloader.start(adUnitId, preloadConfig) }
جافا
private void setBufferSize(String adUnitId) { AdRequest adRequest = new AdRequest.Builder(adUnitId).build(); // Define a PreloadConfiguration and set the buffer size to 2 preloaded ads. PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 2); InterstitialAdPreloader.start(adUnitId, preloadConfig); }
حدود ذاكرة التخزين المؤقت للتحميل المسبق
GMA Next-Gen SDK تفرض حدًا على مستوى التطبيق لعدد الإعلانات الإجمالي التي تم تحميلها مسبقًا على مستوى جميع الوحدات الإعلانية وأرقام تعريف التحميل المسبق:
- الحدّ التلقائي: تحتفظ Google بحد أقصى ستة إعلانات تم تحميلها مسبقًا في الذاكرة. ويتم مشاركة هذا الحدّ على مستوى جميع الأشكال وأرقام تعريف التحميل المسبق.
- ننصحك بالاحتفاظ بحجم ذاكرة التخزين المؤقت يتضمّن إعلانَين لكل رقم تعريف تحميل مسبق.
اختياري: إيقاف التحميل المسبق للإعلانات
إذا لم تعُد بحاجة إلى عرض الإعلانات لرقم تعريف تحميل مسبق معيّن في الجلسة، يمكنك إيقاف التحميل المسبق للإعلانات. لإيقاف تحميل الإعلانات لرقم تعريف تحميل مسبق معيّن، استدعِ الطريقة destroy() باستخدام رقم تعريف التحميل المسبق. يؤدي استدعاء الطريقة destroy() إلى إزالة جميع الإعلانات التي تم تحميلها مسبقًا والمرتبطة برقم تعريف التحميل المسبق من ذاكرة التخزين المؤقت.
يوضّح المثال التالي كيفية إيقاف التحميل المسبق للإعلانات:
Kotlin
private fun stopPreloading(adUnitId: String) { // Stops the preloading and destroy preloaded ads. InterstitialAdPreloader.destroy(adUnitId) }
جافا
private void stopPreloading(String adUnitId) { // Stops the preloading and destroy preloaded ads. InterstitialAdPreloader.destroy(adUnitId); }
اختياري: قراءة معلومات الاستجابة
يمكنك قراءة معلومات استجابة الإعلان التالي الذي تم تحميله مسبقًا بدون إزالة الإعلان من ذاكرة التخزين المؤقت.
يوضّح المثال التالي كيفية قراءة معلومات استجابة الإعلان التالي الذي تم تحميله مسبقًا:
Kotlin
val responseInfo = InterstitialAdPreloader.peekAdResponseInfo(preloadId) if (responseInfo == null) { Log.e(TAG, "Failed to peek ad response info.") return } Log.d(TAG, "Peeked ad response ID: ${responseInfo.responseId}")
جافا
ResponseInfo responseInfo = InterstitialAdPreloader.peekAdResponseInfo(preloadId); if (responseInfo == null) { Log.e(TAG, "Failed to peek ad response info."); return; } Log.d(TAG, "Peeked ad response ID: " + responseInfo.getResponseId());