Menyiapkan iklan reward

Pilih platform: Android iOS Unity Flutter Android (Legacy)

Iklan reward memungkinkan Anda memberi reward kepada pengguna dengan item dalam aplikasi karena telah berinteraksi dengan iklan video, iklan yang dapat dimainkan, dan survei.

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

Sebelum memulai

Sebelum melanjutkan, lakukan hal berikut:

  • Siapkan GMA Next-Gen SDK.
  • Gunakan ID unit iklan reward percobaan ca-app-pub-3940256099942544/5224354917.
    • Saat membangun dan menguji aplikasi, pastikan Anda menggunakan iklan percobaan, bukan iklan produksi langsung. Jika Anda tidak menggunakan ID unit iklan percobaan, Google dapat menangguhkan akun Anda.
    • 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 (beta)

Pramuat iklan di GMA Next-Gen SDK mengotomatiskan pemuatan dan caching iklan.

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 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 mem-pramuat iklan dan mencoba ulang permintaan yang gagal untuk konfigurasi yang dipramuat.

Contoh berikut menunjukkan cara memulai pramuat iklan:

Kotlin

val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
RewardedAdPreloader.start(adUnitId, preloadConfig)

Java

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedAdPreloader.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 antar-permintaan, gunakan pemuatan tunggal.

Mendapatkan dan menampilkan iklan yang dipramuat

Sebelum menampilkan iklan, panggil metode pollAd. Jangan menyimpan objek iklan yang dipramuat. Saat Anda memanggil metode pollAd, GMA Next-Gen SDK akan mengambil iklan yang tersedia dan otomatis mem-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. Gunakan pemroses reward untuk menangani peristiwa reward. 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 = RewardedAdPreloader.pollAd(adUnitId)
  if (ad == null) {
    Log.e(TAG, "Rewarded ad is not available.")
    return
  }

  // Interact with the ad object as needed.
  Log.d(TAG, "Rewarded ad response info: ${ad.getResponseInfo()}")
  ad.adEventCallback =
    object : RewardedAdEventCallback {
      override fun onAdImpression() {
        Log.d(TAG, "Rewarded 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 RewardedAd ad = RewardedAdPreloader.pollAd(adUnitId);

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

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

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

Saat aplikasi Anda mencapai penempatan iklan dan dapat memanggil metode show, panggil metode pollAd. Jangan panggil metode pollAd di 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

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

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

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

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

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

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

Java

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

  rewardedAd.setAdEventCallback(
      new RewardedAdEventCallback() {
        @Override
        public void onAdShowedFullScreenContent() {
          // Rewarded ad did show.
        }

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

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

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

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

Opsional: Memvalidasi callback verifikasi sisi server (SSV)

Untuk meneruskan konteks pengguna dan aplikasi dalam callback verifikasi sisi server (SSV), tetapkan opsi verifikasi pada objek iklan sebelum menampilkan iklan. Karena callback SSV tiba di server Anda dari Google tanpa status sesi, lampirkan string opsional berikut. Google meneruskan string ini tanpa perubahan sebagai parameter kueri yang ditandatangani dalam callback SSV.

  • Parameter kueri user_id: Mengidentifikasi pengguna yang akan diberi kredit, seperti ID akun internal.
  • Parameter kueri custom_data: Membawa data aplikasi, seperti penempatan reward, level game, atau nonce yang dibuat server.

Jika Anda tidak menetapkan nilai, Google akan menghapus parameter kueri tersebut dari callback SSV.

Contoh berikut menetapkan data kustom pada objek iklan sebelum menampilkan iklan:

Kotlin

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

Java

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

Ganti SAMPLE_CUSTOM_DATA_STRING dengan data kustom Anda.

Poin penting: Parameter kueri custom_data di enkode dalam persentase. Sebelum Anda mengurai nilai, lakukan URL-decode pada string di server Anda dan verifikasi tanda tangan callback sebelum mempercayai parameter kueri user_id atau custom_data.

Opsional: Memproses peristiwa pramuat

Saat Anda memulai pramuat iklan, daftarkan peristiwa pramuat untuk mendapatkan notifikasi saat iklan berhasil dipramuat, gagal dipramuat, atau cache iklan habis.

Contoh berikut menunjukkan cara mendaftar untuk peristiwa pramuat iklan:

Kotlin

val preloadCallback =
  object : PreloadCallback {
    override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) {
      Log.d(TAG, "Rewarded preload ad $preloadId failed to load with error: ${adError.message}")
    }

    override fun onAdsExhausted(preloadId: String) {
      Log.i(TAG, "Rewarded preload ad $preloadId is not available")
    }

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

Java

PreloadCallback preloadCallback =
    new PreloadCallback() {
      @Override
      public void onAdFailedToPreload(String preloadId, LoadAdError adError) {
        Log.d(
            TAG,
            String.format(
                "Rewarded preload ad %s failed to load with error: %s",
                preloadId, adError.getMessage()));
      }

      @Override
      public void onAdsExhausted(String preloadId) {
        Log.i(TAG, "Rewarded preload ad " + preloadId + " is not available");
      }

      @Override
      public void onAdPreloaded(String preloadId, ResponseInfo responseInfo) {
        Log.i(TAG, "Rewarded preload ad " + preloadId + " is available");
      }
    };

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

Saat iklan gagal dimuat, GMA Next-Gen SDK akan otomatis mem-pramuat iklan dan mencoba ulang permintaan yang gagal untuk konfigurasi yang dipramuat. Jangan panggil permintaan pemuatan manual di callback kegagalan. Dalam metode callback peristiwa pramuat, jangan panggil metode pollAd, destroy, atau start. Memanggil metode ini dalam callback dapat memicu 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 RewardedAdPreloader.isAdAvailable(adUnitId)
}

Java

private boolean isAdAvailable(String adUnitId) {
  return RewardedAdPreloader.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

val adRequest = AdRequest.Builder(adUnitId).build()
// Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 2)
RewardedAdPreloader.start(adUnitId, preloadConfig)

Java

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);
RewardedAdPreloader.start(adUnitId, preloadConfig);

Batas cache pramuat

GMA Next-Gen SDK menerapkan batas di seluruh aplikasi pada 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 berlaku untuk semua format dan ID pramuat.
  • Sebaiknya pertahankan ukuran buffer dua untuk setiap ID pramuat.

Opsional: Menghentikan pramuat iklan

Pertahankan pramuat aktif saat aplikasi Anda menayangkan iklan. Selama waktu ini, jangan gunakan metode destroy. 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 dipramuat 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.
  RewardedAdPreloader.destroy(adUnitId)
}

Java

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

Opsional: Membaca info respons

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

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