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

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

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

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

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

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

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

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

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

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

InterstitialAdPreloader.start(
  preloadId: _adUnitId,
  preloadConfiguration: PreloadConfiguration(adUnitId: _adUnitId),
  callback: const PreloadCallback(),
);

استبدِل _adUnitId بمعرّف وحدتك الإعلانية.

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

عند استخدام ميزة "التحميل المسبَق للإعلان"، يحتفظ Google Mobile Ads Flutter Plugin بالإعلانات المخزَّنة مؤقتًا. عندما تريد عرض إعلان، استدعِ الطريقة pollAd. يستردّ Google Mobile Ads Flutter Plugin إعلانًا متاحًا ويحمّل الإعلان التالي تلقائيًا في الخلفية.

تجنَّب استدعاء طريقة pollAd إلى أن تصبح مستعدًا لعرض إعلان. يسمح الاحتفاظ بالإعلانات في ذاكرة التخزين المؤقت لـ "Google Mobile Ads Flutter Plugin" بإعادة تحميل الإعلانات منتهية الصلاحية تلقائيًا وتحسين ذاكرة التخزين المؤقت.

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

void _pollAndShowAd() async {
  final InterstitialAd? ad = await InterstitialAdPreloader.pollAd(_adUnitId);
  if (ad != null) {
    _interstitialAd = ad;
    ad.fullScreenContentCallback = FullScreenContentCallback(
      onAdImpression: (ad) {
        // Called when an impression occurs on the ad.
        debugPrint('Ad recorded an impression.');
      },
    );
    ad.onPaidEvent = (ad, valueMicros, precision, currencyCode) {
      // Called when an ad is estimated to have earned money.
      debugPrint('Ad paid: $valueMicros $currencyCode.');
    };
    // Show the ad.
    await ad.show();
  }
}

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

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

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

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

void _checkAdAvailability() async {
  final bool isAvailable = await InterstitialAdPreloader.isAdAvailable(
    _adUnitId,
  );
  debugPrint('Is ad available: $isAvailable');
}

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

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

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

  • عدم الاتصال بـ ‎start
  • تجنَّب طلب pollAd ما لم يتم عرض الإعلان على الفور.

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

InterstitialAdPreloader.start(
  preloadId: _adUnitId,
  preloadConfiguration: PreloadConfiguration(adUnitId: _adUnitId),
  callback: PreloadCallback(
    onAdPreloaded: (preloadId, responseInfo) {
      debugPrint('Ad preloaded for ID: $preloadId');
    },
    onAdFailedToPreload: (preloadId, error) {
      debugPrint('Ad failed to preload for ID: $preloadId. Error: $error');
    },
    onAdsExhausted: (preloadId) {
      debugPrint('All preloaded ads exhausted for ID: $preloadId');
    },
  ),
);

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

إذا لم تكن بحاجة إلى عرض إعلانات لرقم تعريف تحميل مسبق مرة أخرى في الجلسة، يمكنك إيقاف التحميل المسبق للإعلانات. لإيقاف التحميل المُسبَق للإعلانات لرقم تعريف تحميل مُسبَق معيّن، يمكنك استدعاء destroy باستخدام رقم تعريف تحميل مُسبَق. لإيقاف التحميل المُسبق لجميع أدوات التحميل المُسبق، يمكنك استدعاء destroyAll.

void _stopPreloading() async {
  await InterstitialAdPreloader.destroy(_adUnitId);
}

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

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

InterstitialAdPreloader.start(
  preloadId: _adUnitId,
  preloadConfiguration: PreloadConfiguration(
    adUnitId: _adUnitId,
    bufferSize: 3,
  ),
  callback: const PreloadCallback(),
);

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

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

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