Menyiapkan iklan interstisial

Pilih platform: Android iOS Unity Flutter Android (Lama)

Iklan interstisial adalah iklan layar penuh yang menutupi antarmuka aplikasi. Anda menampilkan iklan ini pada titik transisi alami di aplikasi, seperti di antara aktivitas atau selama jeda dalam level game.

Saat aplikasi Anda menampilkan iklan interstisial, pengguna dapat mengetuk iklan dan melanjutkan, atau menutup iklan dan kembali ke aplikasi. Baca studi kasus ini.

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

Sebelum memulai

Sebelum melanjutkan, lakukan hal berikut:

  • Siapkan GMA Next-Gen SDK.
  • Gunakan ID unit iklan interstisial pengujian ca-app-pub-3940256099942544/1033173712.
    • Saat membuat dan menguji aplikasi, pastikan Anda menggunakan iklan percobaan, bukan iklan produksi langsung. Jika Anda tidak menggunakan ID unit iklan pengujian, Google dapat menangguhkan akun Anda.
    • Sebelum memublikasikan aplikasi, ganti ID ini dengan ID unit iklan Anda.
    • Untuk mengetahui detail tentang iklan pengujian GMA Next-Gen SDK, lihat Mengaktifkan iklan pengujian.

Memahami pramuat iklan (beta)

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 terkelola: memuat iklan baru saat iklan gagal dimuat.
  • Penanganan masa berlaku: memuat ulang iklan sebelum masa berlakunya habis.
  • Pengoptimalan cache: mengoptimalkan urutan cache untuk menayangkan iklan dengan prioritas tertinggi.

Memulai pramuat iklan

Untuk mulai mem-pramuat iklan, panggil metode start sekali saat Anda melakukan inisialisasi GMA Next-Gen SDK. Setelah Anda memanggil metode start, GMA Next-Gen SDK akan otomatis melakukan pramuat iklan dan mencoba lagi permintaan yang gagal untuk konfigurasi yang telah dipramuat.

Contoh berikut menunjukkan cara memulai pramuat iklan:

Kotlin

private fun startPreloading(adUnitId: String) {
  // 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)
  InterstitialAdPreloader.start(adUnitId, preloadConfig)
}

Java

private void startPreloading(String adUnitId) {
  // 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);
  InterstitialAdPreloader.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.

Pramuat iklan tidak mendukung perubahan parameter penargetan atau permintaan iklan. Jika Anda perlu mengubah parameter penargetan di antara permintaan, gunakan pemuatan tunggal.

Mendapatkan dan menampilkan iklan yang sudah dipramuat

Sebelum menampilkan iklan, panggil metode pollAd. Jangan simpan objek iklan yang sudah dipramuat. Saat Anda memanggil metode pollAd, GMA Next-Gen SDK akan mengambil iklan yang tersedia dan otomatis melakukan pramuat 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. Contoh berikut menunjukkan cara mengambil dan menampilkan iklan yang dipramuat:

Kotlin

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

  // Interact with the ad object as needed.
  Log.d(TAG, "Interstitial ad response info: ${ad.getResponseInfo()}")
  ad.adEventCallback =
    object : InterstitialAdEventCallback {
      override fun onAdImpression() {
        Log.d(TAG, "Interstitial ad recorded an impression.")
      }
    }
  ad.show(activity)
}

Java

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

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

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

  // Show the ad.
  ad.show(activity);
}

Saat aplikasi Anda mencapai penempatan iklan dan dapat memanggil metode show, panggil metode pollAd. Jangan panggil metode pollAd dalam callback pramuat atau setelah memeriksa metode isAdAvailable untuk menahan iklan. Jika Anda perlu memeriksa metadata iklan sebelum menampilkan iklan, baca info respons tanpa menghapus iklan dari cache.

Memproses peristiwa iklan

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

Kotlin

// Listen for ad events.
val ad = interstitialAd
if (ad == null) {
  Log.e(TAG, "Interstitial ad is not ready yet.")
  return
}

ad.adEventCallback =
  object : InterstitialAdEventCallback {
    override fun onAdShowedFullScreenContent() {
      // Interstitial ad did show.
    }

    override fun onAdDismissedFullScreenContent() {
      // Interstitial ad did dismiss.
      interstitialAd = null
    }

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

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

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

Java

// Listen for ad events.
if (interstitialAd == null) {
  Log.e(TAG, "Interstitial ad is not ready yet.");
  return;
}

interstitialAd.setAdEventCallback(
    new InterstitialAdEventCallback() {
      @Override
      public void onAdShowedFullScreenContent() {
        // Interstitial ad did show.
      }

      @Override
      public void onAdDismissedFullScreenContent() {
        // Interstitial ad did dismiss.
        interstitialAd = null;
      }

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

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

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

Opsional: Memproses peristiwa pra-pemuatan

Saat Anda mulai melakukan pramuat iklan, daftar ke peristiwa pramuat untuk mendapatkan notifikasi saat iklan berhasil dipramuat, gagal dipramuat, atau cache iklan habis.

Contoh berikut menunjukkan cara mendaftar untuk peristiwa iklan pramuat:

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,
        ("Interstitial preload ad $preloadId failed to load with error: ${adError.message}"),
      )
    }

    override fun onAdsExhausted(preloadId: String) {
      Log.i(TAG, "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, "Interstitial preload ad $preloadId is available")
    }
  }
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
InterstitialAdPreloader.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(
                "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, "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, "Interstitial preload ad " + preloadId + " is available");
      }
    };

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

Jika iklan gagal dimuat, GMA Next-Gen SDK akan otomatis mem-pramuat iklan dan mencoba ulang permintaan yang gagal untuk konfigurasi pramuat. Jangan panggil permintaan pemuatan manual dalam callback kegagalan. Dalam metode callback peristiwa pramuat, jangan panggil metode pollAd, destroy, atau start. Memanggil metode ini dalam callback dapat memanggil loop pemuatan rekursif.

Opsional: Memeriksa ketersediaan iklan

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

Kotlin

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

Java

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

Opsional: Menetapkan ukuran buffer

Ukuran buffer mengontrol jumlah iklan yang dipramuat 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 menambah atau mengurangi jumlah iklan yang disimpan dalam memori. Sebaiknya gunakan ukuran buffer dua iklan yang dipramuat. Jika sebagian besar traffic Anda berasal dari perangkat dengan memori rendah, kurangi ukuran buffer.

Contoh berikut menunjukkan cara menetapkan ukuran buffer:

Kotlin

private fun setBufferSize(adUnitId: String) {
  val adRequest = AdRequest.Builder(adUnitId).build()
  // Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
  val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 2)
  InterstitialAdPreloader.start(adUnitId, preloadConfig)
}

Java

private void setBufferSize(String adUnitId) {
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  // Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 2);
  InterstitialAdPreloader.start(adUnitId, preloadConfig);
}

Batas cache pramuat

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

  • Batas default: Google menyimpan maksimum enam iklan yang dipramuat dalam memori. Batas ini digunakan bersama di semua format dan ID pramuat.
  • Sebaiknya pertahankan ukuran buffering dua untuk setiap ID pramuat.

Opsional: Menghentikan iklan pramuat

Tetap aktifkan pra-pemuatan saat aplikasi Anda menayangkan iklan. Selama waktu ini, jangan gunakan metode destroy. Jika Anda tidak perlu menampilkan iklan untuk ID pra-pemuatan tertentu lagi dalam sesi, Anda dapat berhenti melakukan pra-pemuatan iklan. Untuk berhenti memuat iklan untuk ID pramuat tertentu, panggil metode destroy dengan ID pramuat. Memanggil metode destroy akan menghapus semua iklan pramuat 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.
  InterstitialAdPreloader.destroy(adUnitId)
}

Java

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

Opsional: Baca info respons

Baca info respons iklan yang telah dimuat sebelumnya berikutnya tanpa menghapus iklan dari cache. Jika Anda perlu memeriksa metadata iklan sebelum menampilkan iklan, baca info respons, bukan memanggil metode pollAd.

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

Kotlin

val responseInfo = InterstitialAdPreloader.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 = InterstitialAdPreloader.peekAdResponseInfo(preloadId);
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.");
  return;
}

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