التحميل المُسبَق للإعلانات (إصدار تجريبي)

اختيار النظام الأساسي: Android جديد Android iOS Unity

ميزة "التحميل المُسبَق للإعلانات" هي ميزة لتحميل الإعلانات تديرها Google في Google Mobile Ads SDK، وتتولّى إدارة تحميل الإعلانات وتخزينها مؤقتًا بالنيابة عنك. يتطلّب التحميل المُسبَق للإعلانات إجراء تغيير في طريقة إدارة تحميل الإعلانات. لتحسين الأداء باستخدام ميزة التحميل المُسبَق للإعلانات، عليك إيقاف التخزين المؤقت المخصّص وتفويض هذه المسؤولية إلى Google Mobile Ads SDK.

توفّر ميزة "التحميل المُسبَق للإعلانات" المزايا التالية مقارنةً بالتحميل اليدوي للإعلانات:

  • إدارة المراجع: تحتفظ هذه الميزة بالإعلانات التي تم تحميلها، ما يغنيك عن الاحتفاظ بالمراجع إلى أن تصبح مستعدًا لعرضها.
  • إعادة التحميل التلقائي: يتم تلقائيًا تحميل إعلان جديد عند سحب إعلان من ذاكرة التخزين المؤقت.
  • عمليات إعادة المحاولة المُدارة: تتم تلقائيًا إعادة محاولة الطلبات التي تعذّر تنفيذها باستخدام التراجع الدليلي.
  • التعامل مع انتهاء الصلاحية: يتم تلقائيًا إعادة تحميل الإعلانات قبل انتهاء صلاحيتها (عادةً بعد ساعة واحدة).
  • تحسين ذاكرة التخزين المؤقت: إذا كنت تستخدم حجم ذاكرة تخزين مؤقت أكبر من واحد، تعمل Google Mobile Ads SDK على تحسين ترتيب ذاكرة التخزين المؤقت لعرض أفضل إعلان.

يتناول هذا الدليل كيفية ضبط إعدادات الإعلانات المحمَّلة مسبقًا والتحقّق من توفّرها وعرضها.

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

قبل المتابعة في هذا البرنامج التعليمي، عليك إكمال ما يلي:

  • ثبِّت الإصدار 13.3.0 أو إصدارًا أحدث.Google Mobile Ads SDK تتوفّر موارد المطوّرين للإصدارات الأقدم على 11.12.0 - 12.2.0، ولكن ننصحك باستخدام الإصدار 13.3.0 أو إصدار أحدث واتّباع هذا الدليل من الآن فصاعدًا.
  • إعداد Google Mobile Ads SDK

استيراد عناوين الإصدار التجريبي

لاستخدام ميزة "التحميل المُسبَق للإعلانات"، استورِد العناوين التجريبية:

Swift

import GoogleMobileAds_Private

Objective-C

#import <GoogleMobileAds/GoogleMobileAds_Beta.h>

بدء التحميل المُسبَق للإعلانات

لبدء التحميل المُسبَق للإعلانات، استدعِ الدالة preload(). يجب استدعاء هذه الطريقة مرة واحدة فقط لكل معرّف تحميل مُسبَق. ننصحك باستدعاء الطريقة عند بدء جلسة التطبيق. بعد طلب preload()، Google Mobile Ads SDK يتم تلقائيًا التحميل المُسبَق للإعلانات وإعادة محاولة الطلبات غير الناجحة لمعرّفات التحميل المُسبَق هذه.

يبدأ المثال التالي في التحميل المُسبَق للإعلانات:

Swift

private func startPreloading(adUnitID: String) {
  // Start the preloading initialization process.
  let request = Request()
  let interstitialConfig = PreloadConfigurationV2(adUnitID: adUnitID, request: request)
  InterstitialAdPreloader.shared.preload(
    for: adUnitID, configuration: interstitialConfig, delegate: self)
}

Objective-C

- (void)startPreloadingWithAdUnitID:(NSString *)adUnitID {
  // Start the preloading initialization process.
  GADRequest *request = [GADRequest request];
  GADPreloadConfigurationV2 *interstitialConfig = [[GADPreloadConfigurationV2 alloc] initWithAdUnitID:adUnitID request:request];

  [GADInterstitialAdPreloader.sharedInstance preloadForPreloadID:adUnitID
                                                       configuration:interstitialConfig
                                                            delegate:self];
}

الحصول على الإعلان المحمَّل مسبقًا وعرضه

عند استخدام ميزة "التحميل المُسبَق للإعلانات"، تحتفظ Google Mobile Ads SDK بالإعلانات المخزّنة مؤقتًا. عندما تريد عرض إعلان، استدعِ الدالة adWithPreloadID(). يستردّ Google Mobile Ads SDK الإعلان المتاح ويحمّل تلقائيًا الإعلان التالي مسبقًا في الخلفية.

يعرض المثال التالي كيفية استرداد إعلان تم تحميله مسبقًا وعرضه:

Swift

private func showInterstitialAd(adUnitID: String) {
  // Verify that the preloaded ad is available before polling.
  guard isInterstitialAvailable(adUnitID: adUnitID) else {
    print("Preloaded interstitial ad is not available.")
    return
  }

  // Polling returns the next available ad and load another ad in the background.
  let ad = InterstitialAdPreloader.shared.ad(with: adUnitID)

  // Interact with the ad object as needed.
  print("Interstitial ad response info: \(String(describing: ad?.responseInfo))")
  ad?.paidEventHandler = { (value: AdValue) in
    print("Interstitial ad paid event: \(value.value), \(value.currencyCode)")
  }

  ad?.fullScreenContentDelegate = self
  ad?.present(from: self)
}

Objective-C

- (void)showInterstitialAdWithAdUnitID:(NSString *)adUnitID {
  // Verify that the preloaded ad is available before polling.
  if (![self isInterstitialAvailableWithAdUnitID:adUnitID]) {
    NSLog(@"Preloaded interstitial ad is not available.");
    return;
  }

  // Getting the preloaded ad loads another ad in the background.
  GADInterstitialAd *ad = [GADInterstitialAdPreloader.sharedInstance adWithPreloadID:adUnitID];

  // Interact with the ad object as needed.
  NSLog(@"Interstitial ad response info: %@", ad.responseInfo);
  ad.paidEventHandler = ^(GADAdValue *_Nonnull value) {
    NSLog(@"Interstitial ad paid event: %@ %@ ", value.value, value.currencyCode);
  };
  ad.fullScreenContentDelegate = self;
  [ad presentFromRootViewController:self];
}

الحصول على البيانات الوصفية للإعلانات المحمَّلة مسبقًا

للحصول على بيانات وصفية مُحمَّلة مسبقًا للإعلان، يمكنك البحث عن عنصر معلومات استجابة الإعلان. تتيح لك هذه العملية فحص بيانات وصفية للإعلان بدون إزالتها من ذاكرة التخزين المؤقت.

يبحث المثال التالي عن البيانات الوصفية لإعلان تم تحميله مسبقًا من عنصر info الخاص بالاستجابة:

Swift

private func getInterstitialAdResponseInfo(preloadID: String) {
  // Get the response info for the preloaded ad.
  if let responseInfo = InterstitialAdPreloader.shared.adResponseInfo(withPreloadID: preloadID) {
    print("Ad response ID: \(responseInfo.responseID)")
  }
}

Objective-C

- (void)getInterstitialAdResponseInfoWithPreloadID:(NSString *)preloadID {
  // Get the response info for the preloaded ad.
  GADResponseInfo *responseInfo =
      [GADInterstitialAdPreloader.sharedInstance
          adResponseInfoWithPreloadID:preloadID];
  if (responseInfo) {
    NSLog(@"Ad response ID: %@", responseInfo.responseID);
  }
}

التحقّق من توفّر إعلان التحميل المُسبَق

للتحقّق من توفّر الإعلانات، اختَر أحد الخيارَين التاليَين:

الحصول على معلومات حول توفّر الإعلانات المحمَّلة مسبقًا

يتحقّق المثال التالي من توفّر الإعلانات:

Swift

private func isInterstitialAvailable(adUnitID: String) -> Bool {
  // Verify that an ad is available before polling.
  return InterstitialAdPreloader.shared.isAdAvailable(with: adUnitID)
}

Objective-C

- (BOOL)isInterstitialAvailableWithAdUnitID:(NSString *)adUnitID {
  // Verify that an ad is available before polling.
  return [GADInterstitialAdPreloader.sharedInstance isAdAvailableWithPreloadID:adUnitID];
}

الاستماع إلى مدى توفّر الإعلانات المحمَّلة مسبقًا

سجِّل أحداث التحميل المُسبَق لتلقّي إشعارات عند تحميل الإعلانات مُسبقًا بنجاح، أو تعذُّر تحميلها مُسبقًا، أو استنفاد ذاكرة التخزين المؤقت للإعلانات.

أحداث التحميل المُسبَق مخصّصة لأغراض إحصائية. ضمن عمليات معاودة الاتصال الخاصة بحدث التحميل المُسبَق:

  • عدم الاتصال بالرقم ‎preload()
  • تجنَّب استدعاء adWithPreloadID() ما لم يكن سيتم عرض الإعلان على الفور.

يسجّل المثال التالي أحداث الإعلانات:

Swift

func adAvailable(forPreloadID preloadID: String, responseInfo: ResponseInfo) {
  // This callback indicates that an ad is available for the specified configuration.
  // No action is required here, but updating the UI can be useful in some cases.
  print("Ad preloaded successfully for ad preload ID: \(preloadID)")
}

func adsExhausted(forPreloadID preloadID: String) {
  // This callback indicates that all the ads for the specified configuration have been
  // consumed and no ads are available to show. No action is required here, but updating
  // the UI can be useful in some cases.
  // [Important] Don't call AdPreloader.shared.preload or AdPreloader.shared.ad
  // from adsExhausted.
  print("Ad exhausted for ad preload ID: \(preloadID)")
}

func adFailedToPreload(forPreloadID preloadID: String, error: Error) {
  print(
    "Ad failed to load with ad preload ID: \(preloadID), Error: \(error.localizedDescription)"
  )
}

Objective-C

- (void)adAvailableForPreloadID:(nonnull NSString *)preloadID responseInfo:(nonnull GADResponseInfo *)responseInfo {
  // This callback indicates that an ad is available for the specified configuration.
  // No action is required here, but updating the UI can be useful in some cases.
  NSLog(@"Ad preloaded successfully for ad unit ID: %@", preloadID);
}

- (void)adsExhaustedForPreloadID:(nonnull NSString  *)preloadID {
  // This callback indicates that all the ads for the specified configuration have been
  // consumed and no ads are available to show. No action is required here, but updating
  // the UI can be useful in some cases.
  // [Important] Don't call [GAD<Format>AdPreloader preloadForPreloadID:] or
  // [GAD<Format>AdPreloader adWithPreloadID:] from adsExhaustedForPreloadID.
  NSLog(@"Ad exhausted for ad preload ID: %@", preloadID);
}

- (void)adFailedToPreloadForPreloadID:(nonnull NSString  *)preloadID error:(nonnull NSError *)error {
  NSLog(@"Ad failed to load with ad preload ID: %@, Error: %@", preloadID, error.localizedDescription);
}

إيقاف التحميل المُسبَق للإعلانات

إذا لم تعُد بحاجة إلى عرض إعلانات لمعرّف التحميل المُسبَق مرة أخرى في الجلسة، يمكنك إيقاف التحميل المُسبَق للإعلانات. لإيقاف التحميل المسبق للإعلانات باستخدام معرّف تحميل مسبق معيّن، استخدِم الدالة stopPreloadingAndRemoveAdsForPreloadID() مع معرّف تحميل مسبق. لإيقاف التحميل المُسبَق لجميع أدوات التحميل المُسبَق، استخدِم stopPreloadingAndRemoveAllAds().

ضبط حجم ذاكرة التخزين المؤقت

يتحكّم حجم ذاكرة التخزين المؤقت في عدد الإعلانات المحمَّلة مسبقًا والمخزَّنة في الذاكرة. تُحسِّن Google تلقائيًا حجم ذاكرة التخزين المؤقت لتحقيق التوازن بين استهلاك الذاكرة ووقت استجابة عرض الإعلانات. إذا كان تطبيقك يعرض الإعلانات قبل تحميل الإعلان التالي، يمكنك ضبط حجم ذاكرة التخزين المؤقت المخصّص لزيادة عدد الإعلانات التي يتم الاحتفاظ بها في الذاكرة. ننصحك بحجم ذاكرة التخزين المؤقت يبلغ اثنين أو ثلاثة.

حدود التحميل المُسبَق من ذاكرة التخزين المؤقت

تفرض Google Mobile Ads SDK حدًا على مستوى التطبيق على إجمالي عدد الإعلانات المحمَّلة مسبقًا على مستوى جميع الوحدات الإعلانية ومعرّفات التحميل المُسبَق:

  • الحدّ التلقائي: يمكن أن يتضمّن Google Mobile Ads SDK ستة إعلانات محملة مسبقًا كحدّ أقصى في الذاكرة. تتم مشاركة هذا الحد بين جميع التنسيقات ومعرّفات التحميل المُسبَق.
  • ننصحك بإبقاء حجم ذاكرة التخزين المؤقت بمقدار اثنَين أو ثلاثة لكل معرّف تحميل مُسبَق.

Swift

let preloadConfig = PreloadConfigurationV2(adUnitID: "/21775744923/example/rewarded")
preloadConfig.bufferSize = 3

Objective-C

GADPreloadConfigurationV2 *preloadConfig =
    [[GADPreloadConfigurationV2 alloc] initWithAdUnitID:@"/21775744923/example/rewarded"];
preloadConfig.bufferSize = 3;