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

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

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

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

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

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

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

قبل المتابعة في هذا الدليل التعليمي، عليك إعداد Google Mobile Ads SDK.

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

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

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

Swift

// 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

// 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 إعلانًا متاحًا ويحمّل الإعلان التالي تلقائيًا في الخلفية.

تجنَّب استدعاء طريقة 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 loads 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:(nonnull 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];
}

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

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

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

Swift

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

Objective-C

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

التحقّق من توفّر الإعلان الذي يتم تحميله مسبقًا

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

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

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

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:(nonnull 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.
  // Don't call InterstitialAdPreloader.shared.preload or
  // InterstitialAdPreloader.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.
  // 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 تلقائيًا حجم المخزن المؤقت لتحقيق التوازن بين استهلاك الذاكرة ووقت استجابة عرض الإعلانات. إذا كان تطبيقك يعرض الإعلانات قبل تحميل الإعلان التالي، يمكنك ضبط حجم ذاكرة التخزين المؤقت المخصّص لزيادة عدد الإعلانات المحفوظة في الذاكرة.

Swift

let preloadConfig = PreloadConfigurationV2(adUnitID: adUnitID)
// Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
preloadConfig.bufferSize = 2

Objective-C

GADPreloadConfigurationV2 *preloadConfig =
    [[GADPreloadConfigurationV2 alloc] initWithAdUnitID:adUnitID];
// Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
preloadConfig.bufferSize = 2;

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

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

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