Di chuyển sang tính năng tải trước quảng cáo

Tính năng tải trước quảng cáo sẽ tự động hoá việc tải, lưu vào bộ nhớ đệm và tải lại quảng cáo trong GMA Next-Gen SDK. Nếu bạn sử dụng tính năng tải một lần, hãy di chuyển sang tính năng tải trước quảng cáo để quản lý vòng đời tự động, quản lý việc thử lại và tối ưu hoá việc lựa chọn quảng cáo. Để biết thông tin chi tiết về khái niệm tải trước quảng cáo, hãy xem bài viết Tải trước quảng cáo. Tính năng tải trước quảng cáo hỗ trợ các định dạng quảng cáo khi mở ứng dụng, quảng cáo xen kẽ, quảng cáo có tặng thưởng và quảng cáo xen kẽ có tặng thưởng.

Trang này hướng dẫn bạn cách di chuyển một quy trình triển khai quảng cáo tải một lần hiện có sang tính năng tải trước quảng cáo. Hướng dẫn này sử dụng quảng cáo xen kẽ làm ví dụ, nhưng bạn có thể áp dụng quy trình tương tự cho các định dạng quảng cáo được hỗ trợ.

Điều kiện tiên quyết

Trước khi tiếp tục, hãy hoàn tất các bước sau:

Yêu cầu quảng cáo bằng tính năng tải trước quảng cáo

Trong tính năng tải một lần, bạn yêu cầu một quảng cáo cho mỗi yêu cầu quảng cáo. Với tính năng tải trước quảng cáo, bạn chỉ cần khởi động trình tải trước một lần bằng mã tải trước và cấu hình tải trước.

Các ví dụ sau đây so sánh yêu cầu quảng cáo với tính năng tải một lần và tính năng tải trước quảng cáo:

Kotlin

Tải một lần:

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

Tải trước quảng cáo:

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

Java

Tải một lần:

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

Tải trước quảng cáo:

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

Chuyển sang lệnh gọi lại tải trước

Trong tính năng tải một lần, bạn đính kèm lệnh gọi lại tải vào từng yêu cầu quảng cáo riêng lẻ. Với tính năng tải trước quảng cáo, bạn đăng ký một trình nghe lệnh gọi lại để quan sát các bản cập nhật bộ nhớ đệm của trình tải trước. Các lệnh gọi lại này sẽ thông báo cho ứng dụng của bạn khi quảng cáo tải trước xong, không tải được hoặc hết bộ nhớ đệm.

Các ví dụ sau đây so sánh cách đăng ký lệnh gọi lại tải trước cho tính năng tải một lần và tính năng tải trước quảng cáo:

Kotlin

Tải một lần:

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

Tải trước quảng cáo:

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

Java

Tải một lần:

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

Tải trước quảng cáo:

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

Trình tải trước sẽ gọi các phương thức gọi lại khi GMA Next-Gen SDK tải hoặc lưu vào bộ nhớ đệm một quảng cáo, hoặc khi ứng dụng của bạn hiển thị một quảng cáo.

Hiển thị quảng cáo từ bộ nhớ đệm

Trong tính năng tải một lần, bạn lưu quảng cáo đã tải vào một biến và hiển thị quảng cáo khi có. Với tính năng tải trước quảng cáo, khi có quảng cáo để hiển thị, bạn sẽ truy xuất quảng cáo trực tiếp từ bộ nhớ đệm. Trong cả hai phương pháp, hãy đính kèm trình nghe sự kiện vào quảng cáo trước khi hiển thị quảng cáo đó.

Các ví dụ sau đây so sánh việc hiển thị quảng cáo bằng tính năng tải trước quảng cáo với tính năng tải một lần:

Kotlin

Tải một lần:

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

Tải trước quảng cáo:

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

Java

Tải một lần:

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

Tải trước quảng cáo:

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

Xoá tính năng lưu vào bộ nhớ đệm và tải lại theo cách thủ công

Trình tải trước sẽ tự động tải một quảng cáo thay thế khi bạn nhận được quảng cáo. Không giống như tính năng tải một lần, bạn không cần lưu trữ các tham chiếu quảng cáo theo cách thủ công hoặc viết logic tải lại.

Xoá các mẫu sau đây khỏi mã của bạn:

  • Lưu vào bộ nhớ đệm biến thành viên: Xoá các biến thành viên lưu trữ đối tượng quảng cáo.
  • Tải lại theo cách thủ công: Xoá các lệnh gọi tải sau khi người dùng của bạn đóng quảng cáo hoặc không hiển thị được.
  • Bộ hẹn giờ thử lại tuỳ chỉnh: Xoá trình xử lý thử lại, vòng lặp lùi và bộ hẹn giờ. GMA Next-Gen SDK sẽ tự động thử lại các yêu cầu tải trước không thành công.

So sánh các ví dụ hoàn chỉnh

Các ví dụ sau đây so sánh một quy trình triển khai quảng cáo xen kẽ đầy đủ trước và sau khi di chuyển sang tính năng tải trước quảng cáo:

Kotlin

Tải một lần:

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

Tải trước quảng cáo:

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

Java

Tải một lần:

// 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);
}

Tải trước quảng cáo:

// 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);
}

Các bước tiếp theo

Khám phá các tài nguyên sau để định cấu hình các tính năng tải trước, tích hợp định dạng quảng cáo và kiểm thử quy trình triển khai của bạn: