Menyiapkan iklan interstisial reward

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

Iklan interstisial reward adalah format iklan layar penuh yang memungkinkan Anda menawarkan item dalam aplikasi untuk iklan yang muncul di antara layar atau level game. Tidak seperti iklan reward, pengguna Anda tidak perlu memilih untuk melihat iklan. Untuk mengetahui detailnya, lihat studi kasus AdMob dan Ringkasan unit iklan interstisial reward (Beta).

Untuk menghilangkan latensi presentasi dan memastikan iklan tersedia saat transisi terjadi, Google Mobile Ads SDK for React Native menggunakan pramuat iklan untuk mengelola pemuatan, caching, dan pengisian ulang buffering di latar belakang.

Panduan ini menunjukkan cara mengintegrasikan iklan interstisial reward dengan pramuat iklan 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/5354046379

iOS

ca-app-pub-3940256099942544/6978759866

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 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 interstisial reward.

Mulai melakukan pramuat

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

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

preloadId adalah string yang secara unik mengidentifikasi konfigurasi pramuat iklan. Jika Anda menggunakan ID unit iklan untuk satu konfigurasi pra-pemuatan di aplikasi, gunakan 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 dimuat sebelumnya yang tersisa di buffer, Google Mobile Ads SDK for React Native akan memanggil callback onAdsExhausted.

Batas cache pramuat

Google Mobile Ads SDK for React Native menerapkan batas di seluruh aplikasi untuk jumlah total iklan yang dipramuat:

• Batas default: Google menyimpan maksimum enam iklan yang dipramuat dalam memori. Batas ini digunakan bersama di semua format dan ID pra-pemuatan.
• Buffer yang direkomendasikan: Dua iklan pramuat 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 RewardedInterstitialAdPreloader.isAdAvailable. Untuk mengambil iklan, panggil metode RewardedInterstitialAdPreloader.pollAd.

Untuk menampilkan iklan, panggil metode show dengan callback onUserEarnedReward untuk memberikan reward saat pengguna selesai menonton iklan. 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 layar penuh sebelum menampilkan iklan:

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

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

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

export function peekRewardedInterstitialAdResponseInfo(
  preloadId: string,
): ResponseInfo | null {
  const responseInfo =
    RewardedInterstitialAdPreloader.peekAdResponseInfo(preloadId);
  if (responseInfo) {
    console.log(
      'Next preloaded rewarded interstitial 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 SSV

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 metode 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 interstisial reward sebelum menampilkan iklan:

export function setServerSideVerificationRewardedInterstitial(
  ad: RewardedInterstitialAd,
) {
  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 RewardedInterstitialAdPreloader.destroy. Proses ini menghentikan pramuat untuk ID pramuat tersebut dan mengosongkan iklan pramuat yang tidak digunakan dari memori.

Contoh berikut menghentikan pramuat:

export function destroyRewardedInterstitialAdPreloader(preloadId: string) {
  RewardedInterstitialAdPreloader.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

Bagian ini membahas penerapan lengkap pramuat iklan.

Contoh komponen berikut memulai pra-pemuatan saat pemasangan, melacak jumlah iklan yang tersedia, dan menyediakan kontrol untuk menampilkan iklan interstisial reward yang telah dimuat sebelumnya:

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

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

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

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

  const handleShowAd = () => {
    setReward(null);
    setStatus('Showing preloaded ad...');
    showPreloadedRewardedInterstitialAd(
      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 Interstitial 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>
  );
}

Langkah berikutnya

Setelah Anda mengintegrasikan iklan interstisial reward, pelajari topik berikut:

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