Menyiapkan iklan reward

Pilih platform: Android iOS Unity Flutter React Native Android (Lama)

Iklan reward memberi pengguna item dalam aplikasi karena telah berinteraksi dengan iklan video, iklan yang dapat dimainkan, dan survei. Untuk mengetahui detailnya, lihat Ringkasan unit iklan reward.

Untuk menghilangkan latensi presentasi dan memastikan iklan tersedia saat pengguna mendapatkan reward, Google Mobile Ads SDK for React Native menggunakan pramuat iklan untuk mengelola pemuatan latar belakang, caching, dan pengisian ulang buffer.

Panduan ini menunjukkan cara mengintegrasikan iklan reward di aplikasi React Native.

Prasyarat

Sebelum melanjutkan, lakukan hal berikut:

• Siapkan Google Mobile Ads SDK for React Native.
• Aktifkan iklan pengujian dan gunakan unit iklan pengujian berikut:

Android

ca-app-pub-3940256099942544/5224354917

iOS

ca-app-pub-3940256099942544/1712485313

Memahami pramuat iklan

Pramuat iklan di Google Mobile Ads SDK for React Native 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.

Untuk memuat iklan secara manual, lihat Memuat satu iklan reward.

Mulai melakukan pramuat

Untuk mulai melakukan pramuat iklan, panggil metode RewardedAdPreloader.start dan teruskan nilai preloadId, setelan konfigurasi, dan callback peristiwa untuk memantau perubahan status buffering:

export function startRewardedAdPreloader(
  adUnitId: string,
  preloadId: string,
  customPreloadCallback?: PreloadCallback,
): boolean {
  const started = RewardedAdPreloader.start(
    preloadId,
    {
      request: {adUnitId},
      bufferSize: 2,
    },
    {
      // Called when an ad is preloaded into the buffer.
      onAdPreloaded: (event) => {
        console.log(`Rewarded ad preloaded for ${event.preloadId}`);
        customPreloadCallback?.onAdPreloaded?.(event);
      },
      // Called when an ad fails to preload.
      onAdFailedToPreload: (error: LoadAdError) => {
        console.error('Failed to preload rewarded ad:', error.message);
        customPreloadCallback?.onAdFailedToPreload?.(error);
      },
      // Called when all preloaded ads in the buffer have been shown.
      onAdsExhausted: () => {
        console.log('Rewarded ad buffer exhausted.');
        customPreloadCallback?.onAdsExhausted?.();
      },
    },
  );
  return started;
}

ID pramuat adalah string yang secara unik mengidentifikasi konfigurasi pramuat iklan. Jika menggunakan ID unit iklan untuk satu konfigurasi pra-pemuatan di aplikasi, Anda dapat menggunakan ID unit iklan tersebut sebagai ID pra-pemuatan. Jika aplikasi Anda memerlukan beberapa pra-pemuat untuk ID unit iklan yang sama, teruskan string yang berbeda untuk setiap ID pramuat.

Saat aplikasi Anda melakukan polling iklan yang dipramuat dari buffer, Google Mobile Ads SDK for React Native akan meminta iklan pengganti di latar belakang untuk mengisi ulang buffer. Jika tidak ada iklan yang dipramuat dalam buffer, Google Mobile Ads SDK for React Native akan memanggil onAdsExhausted.

Batas cache pramuat

Google Mobile Ads SDK for React Native menerapkan batas di seluruh aplikasi untuk jumlah total iklan pramuat 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 pra-pemuatan.
• Ukuran buffer yang direkomendasikan: Dua untuk setiap ID pramuat.

Jika aplikasi Anda mencapai batas seluruh aplikasi, permintaan latar belakang untuk iklan yang dimuat di awal akan dijeda hingga iklan yang ada diambil dari cache atau dihancurkan. Pemuatan awal juga dijeda sementara saat iklan layar penuh ditampilkan secara aktif di layar.

Melakukan polling dan menampilkan iklan

Sebelum menampilkan iklan, pastikan iklan tersedia dengan memanggil metode RewardedAdPreloader.isAdAvailable. Untuk mengambil iklan, panggil metode RewardedAdPreloader.pollAd.

Untuk memproses peristiwa presentasi, seperti penutupan iklan atau kegagalan tampilan, tetapkan properti adEventCallback pada instance iklan sebelum memanggil metode show:

Contoh berikut memeriksa ketersediaan iklan, dan memproses peristiwa presentasi sebelum menampilkan iklan:

export function showPreloadedRewardedAd(
  preloadId: string,
  onRewardEarned: (reward: Reward) => void,
  customAdEventCallback?: FullScreenAdEventCallback,
) {
  if (!RewardedAdPreloader.isAdAvailable(preloadId)) {
    console.log('No preloaded rewarded ad available right now.');
    return;
  }

  const ad = RewardedAdPreloader.pollAd(preloadId);
  if (!ad) {
    return;
  }

  ad.adEventCallback = {
    // Called when the ad is presented on screen.
    onAdShowedFullScreenContent: () => {
      console.log('Preloaded rewarded ad showed full screen content.');
      customAdEventCallback?.onAdShowedFullScreenContent?.();
    },
    // Called when the ad is closed by the user.
    onAdDismissedFullScreenContent: () => {
      console.log('Preloaded rewarded ad dismissed full screen content.');
      customAdEventCallback?.onAdDismissedFullScreenContent?.();
      ad.destroy();
    },
    // Called when presentation fails.
    onAdFailedToShowFullScreenContent: (error) => {
      console.error('Failed to show preloaded rewarded ad:', error);
      customAdEventCallback?.onAdFailedToShowFullScreenContent?.(error);
      ad.destroy();
    },
    // Called when an impression is recorded.
    onAdImpression: () => {
      console.log('Preloaded rewarded ad recorded an impression.');
      customAdEventCallback?.onAdImpression?.();
    },
    // Called when the user taps the ad.
    onAdClicked: () => {
      console.log('Preloaded rewarded ad was clicked.');
      customAdEventCallback?.onAdClicked?.();
    },
    // Called when the ad is estimated to have earned money.
    onAdPaid: (adValue) => {
      console.log(
        `Preloaded rewarded ad paid: ${adValue.amountMicros}` +
          ` ${adValue.currencyCode}`,
      );
      customAdEventCallback?.onAdPaid?.(adValue);
    },
  };

  ad.show(onRewardEarned);
}

Untuk merilis memori dan resource, panggil metode ad.destroy di callback onAdDismissedFullScreenContent dan onAdFailedToShowFullScreenContent.

Membaca info respons

Untuk memeriksa info respons iklan yang telah dimuat sebelumnya berikutnya tanpa menghapus iklan dari cache, panggil metode RewardedAdPreloader.peekAdResponseInfo:

export function peekRewardedAdResponseInfo(
  preloadId: string,
): ResponseInfo | null {
  const responseInfo = RewardedAdPreloader.peekAdResponseInfo(preloadId);
  if (responseInfo) {
    console.log('Next preloaded rewarded ad response info:', responseInfo);
  }
  return responseInfo;
}

Jika iklan tersedia, metode peekAdResponseInfo akan menampilkan objek ResponseInfo yang berisi informasi tentang sumber iklan dan adaptor jaringan yang dimuat.

Opsional: Memvalidasi callback verifikasi sisi server

Jika aplikasi Anda memerlukan parameter verifikasi kustom, seperti ID pengguna atau metadata reward kustom, dalam callback verifikasi sisi server (SSV), tetapkan properti serverSideVerificationOptions pada instance iklan yang di-polling sebelum memanggil show.

Nilai yang Anda tetapkan akan diteruskan ke parameter kueri callback SSV:

• userId: Diteruskan ke parameter kueri user_id untuk mengidentifikasi pengguna.
• customData: Meneruskan ke parameter kueri custom_data untuk meneruskan metadata kustom.

Contoh berikut menetapkan ServerSideVerificationOptions (customData dan userId) pada objek iklan reward sebelum menampilkan iklan:

export function setServerSideVerificationRewarded(ad: RewardedAd) {
  ad.serverSideVerificationOptions = {
    userId: 'user_123',
    customData: 'sample_custom_data',
  };
}

Poin Penting: Nilai parameter kueri custom_data di-escape dengan persen, atau dienkode ke URL. Saat menangani callback SSV di server Anda, lakukan dekode URL pada string ini sebelum diproses.

Membersihkan resource

Jika Anda tidak perlu lagi menampilkan iklan untuk ID pramuat tertentu selama sisa sesi, panggil metode RewardedAdPreloader.destroy. Proses ini menghentikan pramuat untuk ID pramuat tersebut dan mengosongkan iklan pramuat yang tidak digunakan dari memori.

Contoh berikut menghentikan pramuat:

export function destroyRewardedAdPreloader(preloadId: string) {
  RewardedAdPreloader.destroy(preloadId);
}

Setelah pengguna menutup iklan atau iklan gagal ditampilkan, hancurkan setiap instance iklan yang di-polling. Untuk mengetahui detailnya, lihat Melakukan polling dan menampilkan iklan.

Lihat contoh lengkapnya

Komponen contoh berikut memulai pra-pemuatan saat pemasangan, melacak jumlah iklan yang tersedia, dan menyediakan kontrol untuk menampilkan iklan reward yang telah dipramuat:

export function RewardedScreen() {
  const [numAdsAvailable, setNumAdsAvailable] = useState<number>(0);
  const [status, setStatus] = useState<string>('Preloader idle.');
  const [reward, setReward] = useState<string | null>(null);

  const refreshAdCount = () => {
    const count = RewardedAdPreloader.getNumAdsAvailable(PRELOAD_ID);
    setNumAdsAvailable(count);
  };

  useEffect(() => {
    // Start preloading ads on component mount
    const started = startRewardedAdPreloader(REWARDED_AD_UNIT_ID, PRELOAD_ID, {
      onAdPreloaded: () => {
        refreshAdCount();
        setStatus('Rewarded ad preloaded into buffer.');
      },
      onAdFailedToPreload: (error) => {
        setStatus(`Failed to preload rewarded ad: ${error.message}`);
      },
      onAdsExhausted: () => {
        refreshAdCount();
        setStatus('Preload buffer exhausted for rewarded ads.');
      },
    });
    if (started) {
      setStatus('Preloader started.');
    }

    // Clean up preloader resources on component unmount
    return () => {
      destroyRewardedAdPreloader(PRELOAD_ID);
    };
  }, []);

  const handleShowAd = () => {
    setReward(null);
    setStatus('Showing preloaded ad...');
    showPreloadedRewardedAd(
      PRELOAD_ID,
      (userReward) => {
        setReward(`${userReward.amount} ${userReward.type}`);
      },
      {
        onAdDismissedFullScreenContent: () => {
          setStatus('Ad dismissed.');
        },
        onAdFailedToShowFullScreenContent: (error) => {
          setStatus(`Failed to show preloaded ad: ${error.message}`);
        },
      },
    );
    refreshAdCount();
  };

  return (
    <View style={styles.container}>
      <Text style={styles.title}>Preload Rewarded Ads</Text>
      <Text style={styles.status}>Status: {status}</Text>
      <Text style={styles.status}>Ads Available: {numAdsAvailable}</Text>
      {reward && <Text style={styles.rewardText}>Earned: {reward}</Text>}
      <View style={styles.buttonGroup}>
        <Button
          title="Show Preloaded Ad"
          onPress={handleShowAd}
          disabled={numAdsAvailable === 0}
        />
      </View>
    </View>
  );
}

Ganti kode berikut:

• REWARDED_AD_UNIT_ID dengan ID unit iklan Anda.
• PRELOAD_ID dengan ID preloader Anda.

Langkah berikutnya

Setelah mengintegrasikan iklan reward, pelajari topik berikut:

• Pendapatan iklan di tingkat tayangan iklan
• Privasi dan izin pengguna