الانتقال إلى ميزة "التحميل المسبَق للإعلان"

تتيح ميزة "التحميل المُسبَق للإعلانات" تحميل الإعلانات وتخزينها مؤقتًا وإعادة تحميلها تلقائيًا في GMA Next-Gen SDK. إذا كنت تستخدم ميزة "التحميل الفردي"، عليك نقل البيانات إلى ميزة "التحميل المُسبَق للإعلانات" للاستفادة من الإدارة التلقائية لدورة الحياة، وعمليات إعادة المحاولة المُدارة، واختيار الإعلانات المحسّن. للاطّلاع على تفاصيل مفاهيمية حول التحميل المسبَق للإعلانات، يُرجى مراجعة مقالة التحميل المسبَق للإعلانات. تتيح ميزة "التحميل المُسبَق للإعلان" استخدام أشكال "الإعلانات على شاشة فتح التطبيق" و"الإعلانات البينية" و"الإعلانات مقابل مكافأة" و"الإعلانات البينية مقابل مكافأة".

توضّح لك هذه الصفحة كيفية نقل عملية تنفيذ حالية لإعلان يتم تحميله مرة واحدة إلى التحميل المسبَق للإعلان. يستخدم هذا الدليل "الإعلانات البينية" كمثال، ولكن يمكنك تطبيق العملية نفسها على أشكال الإعلانات المتوافقة.

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

قبل المتابعة، أكمِل ما يلي:

طلب الإعلانات باستخدام ميزة "التحميل المسبَق للإعلان"

في التحميل الفردي، تطلب إعلانًا واحدًا لكل طلب عرض إعلان. باستخدام ميزة التحميل المُسبق للإعلانات، يمكنك بدء أداة التحميل المُسبق مرة واحدة باستخدام رقم تعريف التحميل المُسبق وإعدادات التحميل المُسبق.

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

Kotlin

حمولة واحدة:

// Request a single ad.
val adRequest = AdRequest.Builder(adUnitId).build()
InterstitialAd.load(adRequest, adLoadCallback)

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

// Start the preloader once with a preload configuration.
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
InterstitialAdPreloader.start(adUnitId, preloadConfig)

جافا

التحميل الفردي:

// Request a single ad.
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
InterstitialAd.load(adRequest, adLoadCallback);

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

// Start the preloader once with a preload configuration.
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
InterstitialAdPreloader.start(adUnitId, preloadConfig);

التبديل إلى عمليات معاودة الاتصال للتحميل المُسبق

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

تقارن الأمثلة التالية كيفية تسجيل عمليات الاستدعاء للتحميل المسبق في التحميل الفردي والتحميل المسبق للإعلانات:

Kotlin

حمولة واحدة:

// Listen for single ad request load results.
val adLoadCallback =
  object : AdLoadCallback<InterstitialAd> {
    override fun onAdLoaded(ad: InterstitialAd) {
      // Ad loaded for a single request.
    }

    override fun onAdFailedToLoad(adError: LoadAdError) {
      Log.d(TAG, "Ad failed to load: ${adError.message}")
    }
  }

InterstitialAd.load(adRequest, adLoadCallback)

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

// Observe cache updates across multiple ads.
val preloadCallback =
  object : PreloadCallback {
    override fun onAdPreloaded(
      preloadId: String,
      responseInfo: ResponseInfo,
    ) {
      // Ad preloaded into the cache and is ready to show.
    }

    override fun onAdFailedToPreload(
      preloadId: String,
      adError: LoadAdError,
    ) {
      Log.d(TAG, "Ad failed to preload: ${adError.message}")
    }

    override fun onAdsExhausted(preloadId: String) {
      // All preloaded ads in the cache have been shown.
      Log.d(TAG, "Ads exhausted for: $preloadId")
    }
  }

InterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback)

جافا

التحميل الفردي:

// Listen for single ad request load results.
AdLoadCallback<InterstitialAd> adLoadCallback =
    new AdLoadCallback<InterstitialAd>() {
      @Override
      public void onAdLoaded(@NonNull InterstitialAd ad) {
        // Ad loaded for a single request.
      }

      @Override
      public void onAdFailedToLoad(@NonNull LoadAdError adError) {
        Log.d(TAG, "Ad failed to load: " + adError.getMessage());
      }
    };

InterstitialAd.load(adRequest, adLoadCallback);

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

// Observe cache updates across multiple ads.
PreloadCallback preloadCallback =
    new PreloadCallback() {
      @Override
      public void onAdPreloaded(
          @NonNull String preloadId, @NonNull ResponseInfo responseInfo) {
        // Ad preloaded into the cache and is ready to show.
      }

      @Override
      public void onAdFailedToPreload(
          @NonNull String preloadId, @NonNull LoadAdError adError) {
        Log.d(TAG, "Ad failed to preload: " + adError.getMessage());
      }

      @Override
      public void onAdsExhausted(@NonNull String preloadId) {
        // All preloaded ads in the cache have been shown.
        Log.d(TAG, "Ads exhausted for: " + preloadId);
      }
    };

InterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback);

يستدعي برنامج التحميل المسبق طرق ردّ الاتصال عندما يتم تحميل إعلان أو تخزينه مؤقتًا في GMA Next-Gen SDK، أو عندما يعرض تطبيقك إعلانًا.

عرض الإعلانات من ذاكرة التخزين المؤقت

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

تقارن الأمثلة التالية بين عرض إعلان مع التحميل المُسبَق للإعلان وعرض إعلان واحد:

Kotlin

حمولة واحدة:

// Retrieve the ad from a saved variable.
val interstitialAd = this.interstitialAd ?: return
// Display the ad.
interstitialAd.show(activity)

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

// Retrieve the ad directly from the preloader cache.
val interstitialAd = InterstitialAdPreloader.pollAd(adUnitId) ?: return
// Display the ad.
interstitialAd.show(activity)

جافا

التحميل الفردي:

// Retrieve the ad from a saved variable.
InterstitialAd interstitialAd = this.interstitialAd;
if (interstitialAd == null) {
  return;
}
// Display the ad.
interstitialAd.show(activity);

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

// Retrieve the ad directly from the preloader cache.
InterstitialAd interstitialAd = InterstitialAdPreloader.pollAd(adUnitId);
if (interstitialAd == null) {
  return;
}
// Display the ad.
interstitialAd.show(activity);

إزالة التخزين المؤقت اليدوي وإعادة التحميل

يحمّل أداة التحميل المُسبَق تلقائيًا إعلانًا بديلاً عندما تتلقّى الإعلان. على عكس التحميل الفردي، لست بحاجة إلى تخزين مراجع الإعلانات يدويًا أو كتابة منطق إعادة التحميل.

أزِل الأنماط التالية من الرمز:

  • تخزين متغيرات الأعضاء مؤقتًا: احذف متغيرات الأعضاء التي تخزّن عناصر الإعلانات.
  • عمليات إعادة التحميل اليدوية: احذف طلبات التحميل بعد أن يغلق المستخدم الإعلان أو يتعذّر عرضه.
  • موقّتات إعادة المحاولة المخصّصة: احذف معالِجات إعادة المحاولة وحلقات التراجع والموقّتات. تعيد ميزة "GMA Next-Gen SDK" تلقائيًا محاولة تنفيذ طلبات التحميل المُسبق التي تعذّر إكمالها.

مقارنة الأمثلة الكاملة

تقارن الأمثلة التالية عملية التنفيذ الكاملة للإعلان البيني قبل وبعد نقل البيانات إلى ميزة التحميل المُسبَق للإعلانات:

Kotlin

حمولة واحدة:

// 1. Maintain a member variable to store the ad.
private var interstitialAd: InterstitialAd? = null

// 2. Load the ad and listen for load completion.
private fun loadAd() {
  val adRequest = AdRequest.Builder(adUnitId).build()
  InterstitialAd.load(
    adRequest,
    object : AdLoadCallback<InterstitialAd> {
      override fun onAdLoaded(ad: InterstitialAd) {
        interstitialAd = ad
      }

      override fun onAdFailedToLoad(adError: LoadAdError) {
        interstitialAd = null
      }
    },
  )
}

// 3. Show the saved ad.
private fun showAd(activity: Activity) {
  val interstitialAd = this.interstitialAd ?: return
  interstitialAd.adEventCallback =
    object : InterstitialAdEventCallback {
      override fun onAdDismissedFullScreenContent() {
        // Reload the ad after dismissal in single-load integrations.
        loadAd()
      }

      override fun onAdFailedToShowFullScreenContent(
        fullScreenContentError: FullScreenContentError,
      ) {
        Log.d(TAG, "Ad failed to show: ${fullScreenContentError.message}")
      }
    }
  interstitialAd.show(activity)
}

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

// 1. Start preloading with a callback to listen for loaded ads.
private fun startPreloading(adUnitId: String) {
  val preloadCallback =
    object : PreloadCallback {
      override fun onAdPreloaded(
        preloadId: String,
        responseInfo: ResponseInfo,
      ) {
        // Ad preloaded successfully.
      }

      override fun onAdFailedToPreload(
        preloadId: String,
        adError: LoadAdError,
      ) {
        Log.d(TAG, "Ad failed to preload: ${adError.message}")
      }
    }

  val adRequest = AdRequest.Builder(adUnitId).build()
  val preloadConfig = PreloadConfiguration(adRequest)
  InterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback)
}

// 2. Show the ad immediately after polling.
private fun showAd(activity: Activity, adUnitId: String) {
  val interstitialAd = InterstitialAdPreloader.pollAd(adUnitId) ?: return
  interstitialAd.adEventCallback =
    object : InterstitialAdEventCallback {
      override fun onAdDismissedFullScreenContent() {
        // Preloading automatically fetches a replacement ad.
      }

      override fun onAdFailedToShowFullScreenContent(
        fullScreenContentError: FullScreenContentError,
      ) {
        Log.d(TAG, "Ad failed to show: ${fullScreenContentError.message}")
      }
    }
  interstitialAd.show(activity)
}

جافا

التحميل الفردي:

// 1. Maintain a member variable to store the ad.
private InterstitialAd interstitialAd;

// 2. Load the ad and listen for load completion.
private void loadAd() {
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  InterstitialAd.load(
      adRequest,
      new AdLoadCallback<InterstitialAd>() {
        @Override
        public void onAdLoaded(@NonNull InterstitialAd ad) {
          interstitialAd = ad;
        }

        @Override
        public void onAdFailedToLoad(@NonNull LoadAdError adError) {
          interstitialAd = null;
        }
      });
}

// 3. Show the saved ad.
private void showAd(Activity activity) {
  if (interstitialAd == null) {
    return;
  }
  interstitialAd.setAdEventCallback(
      new InterstitialAdEventCallback() {
        @Override
        public void onAdDismissedFullScreenContent() {
          // Reload the ad after dismissal in single-load integrations.
          loadAd();
        }

        @Override
        public void onAdFailedToShowFullScreenContent(
            @NonNull FullScreenContentError fullScreenContentError) {
          Log.d(
              TAG,
              "Ad failed to show: " + fullScreenContentError.getMessage());
        }
      });
  interstitialAd.show(activity);
}

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

// 1. Start preloading with a callback to listen for loaded ads.
private void startPreloading(String adUnitId) {
  PreloadCallback preloadCallback =
      new PreloadCallback() {
        @Override
        public void onAdPreloaded(
            @NonNull String preloadId, @NonNull ResponseInfo responseInfo) {
          // Ad preloaded successfully.
        }

        @Override
        public void onAdFailedToPreload(
            @NonNull String preloadId, @NonNull LoadAdError adError) {
          Log.d(TAG, "Ad failed to preload: " + adError.getMessage());
        }
      };

  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
  InterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback);
}

// 2. Show the ad immediately after polling.
private void showAd(Activity activity, String adUnitId) {
  InterstitialAd interstitialAd = InterstitialAdPreloader.pollAd(adUnitId);
  if (interstitialAd == null) {
    return;
  }
  interstitialAd.setAdEventCallback(
      new InterstitialAdEventCallback() {
        @Override
        public void onAdDismissedFullScreenContent() {
          // Preloading automatically fetches a replacement ad.
        }

        @Override
        public void onAdFailedToShowFullScreenContent(
            @NonNull FullScreenContentError fullScreenContentError) {
          Log.d(
              TAG,
              "Ad failed to show: " + fullScreenContentError.getMessage());
        }
      });
  interstitialAd.show(activity);
}

الخطوات التالية

اطّلِع على المراجع التالية لضبط ميزات التحميل المُسبق ودمج أشكال الإعلانات واختبار عملية التنفيذ: