Menyiapkan iklan interstisial reward

Next-Gen SDK.

Pilih platform: Android iOS Unity Flutter Android (Warisan)

Iklan interstisial reward adalah format yang memungkinkan Anda menawarkan reward untuk iklan yang muncul secara otomatis selama transisi aplikasi normal. Berbeda dengan iklan reward, pengguna tidak harus memilih untuk melihat iklan interstisial reward.

Panduan ini menjelaskan cara mengintegrasikan iklan interstisial reward ke dalam aplikasi Android.

Sebelum memulai

Sebelum melanjutkan, lakukan hal berikut:

  • Siapkan GMA Next-Gen SDK.
  • Gunakan ID unit iklan interstisial reward percobaan /21775744923/example/rewarded-interstitial.
    • Saat membangun dan menguji aplikasi, pastikan Anda menggunakan iklan percobaan, bukan iklan produksi langsung. Kegagalan untuk melakukannya dapat menyebabkan penangguhan akun.
    • Sebelum memublikasikan aplikasi, ganti ID ini dengan ID unit iklan Anda.
    • Untuk mengetahui detail tentang iklan percobaan GMA Next-Gen SDK, lihat Mengaktifkan iklan percobaan.

Memahami pramuat iklan

Pramuat iklan di GMA Next-Gen SDK mengotomatiskan pemuatan dan penyimpanan iklan dalam cache.

Pramuat iklan memberikan manfaat berikut:

  • Pengelolaan referensi: mempertahankan referensi hingga iklan ditampilkan.
  • Pemuatan ulang otomatis: memuat iklan baru saat iklan diambil dari cache.
  • Percobaan ulang yang dikelola: memuat iklan baru saat iklan gagal dimuat.
  • Penanganan masa berlaku: memperbarui iklan sebelum masa berlakunya berakhir.
  • Pengoptimalan cache: mengoptimalkan urutan cache untuk menayangkan iklan dengan prioritas tertinggi.

Memulai pramuat iklan

Untuk mulai memuat iklan, panggil metode start sekali saat aplikasi dimulai. Setelah Anda memanggil metode start, GMA Next-Gen SDK akan otomatis memuat iklan dan mencoba ulang permintaan yang gagal untuk konfigurasi yang dimuat.

Contoh berikut menunjukkan cara memulai pramuat iklan:

Kotlin

// Call start() once after SDK initialization.
// Preload only one ad unit per format to optimize performance.
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig)

Java

// Call start() once after SDK initialization.
// Preload only one ad unit per format to optimize performance.
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig);

Ganti AD_UNIT_ID dengan ID unit iklan Anda.

Contoh sebelumnya menunjukkan cara menggunakan ID unit iklan sebagai ID pramuat. ID pramuat adalah ID string yang Anda buat untuk mengidentifikasi konfigurasi pramuat iklan. Jika aplikasi Anda memerlukan beberapa konfigurasi penargetan untuk ID unit iklan yang sama, teruskan ID string kustom.

Mendapatkan dan menampilkan iklan yang dimuat

Saat Anda ingin menampilkan iklan, panggil metode pollAd. GMA Next-Gen SDK mengambil iklan yang tersedia dan otomatis memuat iklan berikutnya di latar belakang. Jika tidak ada iklan yang tersedia, GMA Next-Gen SDK tidak akan menampilkan iklan.

Jika Anda memiliki objek iklan yang tersedia, panggil metode show untuk menampilkan iklan. Gunakan pemroses reward untuk menangani peristiwa reward. Contoh berikut menunjukkan cara mengambil dan menampilkan iklan yang dimuat:

Kotlin

private fun pollAndShowAd(activity: Activity, adUnitId: String) {
  // Polling returns the next available ad and loads another ad in the background.
  val ad = RewardedInterstitialAdPreloader.pollAd(adUnitId)
  if (ad == null) {
    Log.e(TAG, "Rewarded interstitial ad is not available.")
    return
  }

  // Interact with the ad object as needed.
  Log.d(TAG, "Rewarded interstitial ad response info: ${ad.getResponseInfo()}")
  ad.adEventCallback =
    object : RewardedInterstitialAdEventCallback {
      override fun onAdImpression() {
        Log.d(TAG, "Rewarded interstitial ad recorded an impression.")
      }
    }
  ad.show(activity) { rewardItem -> Log.d(TAG, "User earned reward: ${rewardItem.amount}") }
}

Java

private void pollAndShowAd(Activity activity, String adUnitId) {
  // Polling returns the next available ad and loads another ad in the background.
  final RewardedInterstitialAd ad = RewardedInterstitialAdPreloader.pollAd(adUnitId);

  // Interact with the ad object as needed.
  if (ad == null) {
    Log.e(TAG, "Rewarded interstitial ad is not available.");
    return;
  }

  Log.d(TAG, "Rewarded interstitial ad response info: " + ad.getResponseInfo());
  ad.setAdEventCallback(
      new RewardedInterstitialAdEventCallback() {
        @Override
        public void onAdImpression() {
          Log.d(TAG, "Rewarded interstitial ad recorded an impression.");
        }
      });

  // Show the ad.
  ad.show(
      activity,
      rewardItem -> {
        Log.d(TAG, "User earned reward: " + rewardItem.getAmount());
      });
}

Hindari memanggil metode pollAd hingga Anda siap menampilkan iklan. Untuk membaca info respons iklan tanpa menampilkannya, lihat Membaca info respons.

Memproses peristiwa iklan

Sebelum menampilkan iklan, proses peristiwa iklan. Contoh berikut menunjukkan cara mendaftarkan callback untuk peristiwa iklan:

Kotlin

private fun listenToAdEvents() {
  // Listen for ad events.
  val ad = rewardedInterstitialAd
  if (ad == null) {
    Log.e(TAG, "Rewarded interstitial ad is not ready yet.")
    return
  }

  ad.adEventCallback =
    object : RewardedInterstitialAdEventCallback {
      override fun onAdShowedFullScreenContent() {
        // Rewarded interstitial ad did show.
      }

      override fun onAdDismissedFullScreenContent() {
        // Rewarded interstitial ad did dismiss.
        rewardedInterstitialAd = null
      }

      override fun onAdFailedToShowFullScreenContent(
        fullScreenContentError: FullScreenContentError
      ) {
        // Rewarded interstitial ad failed to show.
        Log.e(TAG, "Rewarded interstitial ad failed to show: ${fullScreenContentError.message}")
      }

      override fun onAdImpression() {
        // Rewarded interstitial ad did record an impression.
      }

      override fun onAdClicked() {
        // Rewarded interstitial ad did record a click.
      }
    }
}

Java

private void listenToAdEvents() {
  // Listen for ad events.
  if (rewardedInterstitialAd == null) {
    Log.e(TAG, "Rewarded interstitial ad is not ready yet.");
    return;
  }

  rewardedInterstitialAd.setAdEventCallback(
      new RewardedInterstitialAdEventCallback() {
        @Override
        public void onAdShowedFullScreenContent() {
          // Rewarded interstitial ad did show.
        }

        @Override
        public void onAdDismissedFullScreenContent() {
          // Rewarded interstitial ad did dismiss.
          rewardedInterstitialAd = null;
        }

        @Override
        public void onAdFailedToShowFullScreenContent(
            @NonNull FullScreenContentError fullScreenContentError) {
          // Rewarded interstitial ad failed to show.
          Log.e(
              TAG,
              "Rewarded interstitial ad failed to show: " + fullScreenContentError.getMessage());
        }

        @Override
        public void onAdImpression() {
          // Rewarded interstitial ad did record an impression.
        }

        @Override
        public void onAdClicked() {
          // Rewarded interstitial ad did record a click.
        }
      });
}

Opsional: Memvalidasi callback verifikasi sisi server (SSV)

Jika aplikasi Anda memerlukan data tambahan dalam callback verifikasi sisi server, gunakan fitur data kustom iklan interstisial reward. Nilai string apa pun yang ditetapkan pada objek iklan interstisial reward akan diteruskan ke parameter kueri custom_data dari callback SSV. Jika tidak ada nilai data kustom yang ditetapkan, nilai parameter kueri custom_data tidak akan ada dalam callback SSV.

Contoh kode berikut menunjukkan cara menetapkan data kustom pada objek iklan interstisial reward sebelum menampilkan iklan:

Kotlin

RewardedInterstitialAd.load(
  context,
  AD_UNIT_ID,
  AdRequest.Builder().build(),
  object : RewardedInterstitialAdLoadCallback() {
    override fun onAdLoaded(ad: RewardedInterstitialAd) {
      rewardedInterstitialAd = ad
      val options =
        ServerSideVerificationOptions.Builder().setCustomData("SAMPLE_CUSTOM_DATA_STRING").build()
      rewardedInterstitialAd?.setServerSideVerificationOptions(options)
    }
  },
)

Java

RewardedInterstitialAd.load(
    context,
    AD_UNIT_ID,
    new AdRequest.Builder().build(),
    new RewardedInterstitialAdLoadCallback() {
      @Override
      public void onAdLoaded(RewardedInterstitialAd ad) {
        rewardedInterstitialAd = ad;
        ServerSideVerificationOptions options =
            new ServerSideVerificationOptions.Builder()
                .setCustomData("SAMPLE_CUSTOM_DATA_STRING")
                .build();
        rewardedInterstitialAd.setServerSideVerificationOptions(options);
      }
    });

Ganti SAMPLE_CUSTOM_DATA_STRING dengan data kustom Anda.

Opsional: Memproses peristiwa pramuat

Saat Anda mulai memuat iklan, daftarkan peristiwa pramuat untuk mendapatkan notifikasi saat iklan berhasil dimuat, gagal dimuat, atau cache iklan habis.

Contoh berikut menunjukkan cara mendaftarkan peristiwa pramuat iklan:

Kotlin

val preloadCallback =
  // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
  object : PreloadCallback {
    override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) {
      Log.d(
        TAG,
        "Rewarded interstitial preload ad $preloadId failed to load with error: ${adError.message}",
      )
    }

    override fun onAdsExhausted(preloadId: String) {
      Log.i(TAG, "Rewarded interstitial preload ad $preloadId is not available")
      // [Important] Don't call ad preloader start() or pollAd() from onAdsExhausted.
    }

    override fun onAdPreloaded(preloadId: String, responseInfo: ResponseInfo) {
      Log.i(TAG, "Rewarded interstitial preload ad $preloadId is available")
    }
  }
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback)

Java

PreloadCallback preloadCallback =
    // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
    new PreloadCallback() {
      @Override
      public void onAdFailedToPreload(@NonNull String preloadId, @NonNull LoadAdError adError) {
        Log.d(
            TAG,
            String.format(
                "Rewarded interstitial preload ad %s failed to load with error: %s",
                preloadId, adError.getMessage()));
        // [Optional] Get the error response info for additional details.
        // ResponseInfo responseInfo = adError.getResponseInfo();
      }

      @Override
      public void onAdsExhausted(@NonNull String preloadId) {
        Log.i(TAG, "Rewarded interstitial preload ad " + preloadId + " is not available");
        // [Important] Don't call ad preloader start() or pollAd() from onAdsExhausted.
      }

      @Override
      public void onAdPreloaded(@NonNull String preloadId, @NonNull ResponseInfo responseInfo) {
        Log.i(TAG, "Rewarded interstitial preload ad " + preloadId + " is available");
      }
    };
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback);

Jika iklan gagal dimuat, GMA Next-Gen SDK akan otomatis memuat iklan dan mencoba ulang permintaan yang gagal untuk konfigurasi yang dimuat.

Opsional: Memeriksa ketersediaan iklan

Jika Anda perlu mengetahui apakah iklan tersedia, periksa ketersediaan iklan. Contoh berikut menunjukkan cara memeriksa apakah iklan yang dimuat tersedia:

Kotlin

private fun isAdAvailable(adUnitId: String): Boolean {
  return RewardedInterstitialAdPreloader.isAdAvailable(adUnitId)
}

Java

private boolean isAdAvailable(String adUnitId) {
  return RewardedInterstitialAdPreloader.isAdAvailable(adUnitId);
}

Opsional: Menetapkan ukuran buffer

Ukuran buffer mengontrol jumlah iklan yang dimuat dan disimpan dalam memori. Secara default, Google mengoptimalkan ukuran buffer untuk menyeimbangkan konsumsi memori dan latensi penayangan iklan. Anda dapat menetapkan ukuran buffer kustom untuk meningkatkan jumlah iklan yang disimpan dalam memori. Sebaiknya tetapkan ukuran buffer maksimum 4.

Contoh berikut menunjukkan cara menetapkan ukuran buffer 4 iklan yang dimuat:

Kotlin

val adRequest = AdRequest.Builder(adUnitId).build()
// Maintain small or default buffer size unless rapid transitions are expected.
val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 4)
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig)

Java

// Maintain small or default buffer size unless rapid transitions are expected.
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 4);
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig);

Batas cache pramuat

GMA Next-Gen SDK menerapkan batas di seluruh aplikasi pada jumlah total iklan yang dimuat di semua unit iklan dan ID pramuat:

  • Batas default: Google menyimpan maksimum 6 iklan yang dimuat dalam memori. Batas ini berlaku untuk semua format dan ID pramuat.
  • Sebaiknya pertahankan ukuran buffer 2 atau 3 per ID pramuat.

Opsional: Menghentikan pramuat iklan

Jika Anda tidak perlu menampilkan iklan untuk ID pramuat tertentu lagi dalam sesi, Anda dapat menghentikan pramuat iklan. Untuk berhenti memuat iklan untuk ID pramuat tertentu, panggil metode destroy dengan ID pramuat. Memanggil metode destroy akan menghapus semua iklan yang dimuat yang terkait dengan ID pramuat dari cache.

Contoh berikut menunjukkan cara menghentikan pramuat iklan:

Kotlin

private fun stopPreloading(adUnitId: String) {
  // Stops the preloading and destroy preloaded ads.
  RewardedInterstitialAdPreloader.destroy(adUnitId)
}

Java

private void stopPreloading(String adUnitId) {
  // Stops the preloading and destroy preloaded ads.
  RewardedInterstitialAdPreloader.destroy(adUnitId);
}

Opsional: Membaca info respons

Baca info respons iklan yang dimuat berikutnya tanpa menghapus iklan dari cache.

Contoh berikut menunjukkan cara membaca info respons iklan yang dimuat berikutnya:

Kotlin

val responseInfo = RewardedInterstitialAdPreloader.peekAdResponseInfo(preloadId)
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.")
  return
}

Log.d(TAG, "Peeked ad response ID: ${responseInfo.responseId}")

Java

ResponseInfo responseInfo = RewardedInterstitialAdPreloader.peekAdResponseInfo(preloadId);
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.");
  return;
}

Log.d(TAG, "Peeked ad response ID: " + responseInfo.getResponseId());