Menyiapkan iklan di layar pembuka aplikasi

Iklan di layar pembuka aplikasi muncul saat pengguna membuka atau kembali ke aplikasi Anda. Pengguna dapat menutup iklan di layar pembuka aplikasi kapan saja. Untuk memonetisasi layar pemuatan aplikasi, gunakan iklan di layar pembuka aplikasi. Untuk mengetahui detailnya, lihat Panduan dan praktik terbaik iklan di layar pembuka aplikasi.

Panduan ini menjelaskan cara mengintegrasikan iklan di layar pembuka aplikasi ke dalam aplikasi React Native.

Prasyarat

Sebelum melanjutkan, lakukan hal berikut:

Android 

ca-app-pub-3940256099942544/9257395921

iOS 

ca-app-pub-3940256099942544/5575463023

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 panduan Memuat satu iklan di layar pembuka aplikasi.

Mulai melakukan pramuat

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

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

preloadId adalah string yang secara unik mengidentifikasi konfigurasi pramuat iklan. Jika adUnitId hanya digunakan 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 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.
  • Sebaiknya pertahankan ukuran buffering 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 di-polling dan ditampilkan atau dihancurkan.

Melakukan polling dan menampilkan iklan

Untuk memeriksa iklan yang dipramuat yang tersedia dan mengambil instance iklan, panggil metode AppOpenAdPreloader.pollAd.

Untuk memproses peristiwa presentasi layar penuh, daftarkan callback di properti adEventCallback dari instance AppOpenAd yang ditampilkan sebelum memanggil metode show:

export function showPreloadedAppOpenAd(
  preloadId: string,
  customAdEventCallback?: FullScreenAdEventCallback,
) {
  if (!AppOpenAdPreloader.isAdAvailable(preloadId)) {
    console.log('No preloaded app open ad available right now.');
    return;
  }

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

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

  ad.show();
}

Untuk mengosongkan memori dan resource, panggil metode ad.destroy dalam callback onAdDismissedFullScreenContent dan onAdFailedToShowFullScreenContent saat pengguna menutup iklan atau iklan gagal ditampilkan.

Membaca info respons

Untuk memeriksa detail iklan yang dimuat otomatis berikutnya tanpa menghapus iklan dari cache, panggil metode AppOpenAdPreloader.peekAdResponseInfo:

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

Mengelola iklan di layar pembuka aplikasi dengan pengelola tingkat aplikasi

Karena iklan di layar pembuka aplikasi ditampilkan secara global selama peluncuran aplikasi dan transisi latar depan, sebaiknya kelola status siklus proses preloader di pengelola tingkat aplikasi di luar hierarki komponen React.

Penggunaan pengelola tingkat aplikasi menawarkan beberapa keuntungan utama:

  • Menjaga status preloader tetap independen dari navigasi layar individual dan siklus proses komponen.
  • Memusatkan callback peristiwa iklan, pelacakan status, dan pembersihan dalam satu instance bersama di seluruh aplikasi Anda.
  • Mengontrol kapan peristiwa latar depan diproses, sehingga mencegah presentasi duplikat saat iklan ditutup.

Contoh berikut mengimplementasikan pengelola tingkat aplikasi menggunakan objek AppOpenAdPreloader:

export class AppOpenAdManager {
  private adUnitId: string;
  private preloadId: string;
  private appStateSubscription?: NativeEventSubscription;
  private startTimeoutId?: ReturnType<typeof setTimeout>;

  constructor(adUnitId: string, preloadId: string) {
    this.adUnitId = adUnitId;
    this.preloadId = preloadId;
  }

  start(): boolean {
    if (!AppOpenAdPreloader.getConfiguration(this.preloadId)) {
      AppOpenAdPreloader.start(
        this.preloadId,
        {
          request: {adUnitId: this.adUnitId},
          bufferSize: 2,
        },
        {
          onAdPreloaded: (event) => {
            console.log(`App open ad preloaded for ${event.preloadId}`);
          },
          onAdFailedToPreload: (error: LoadAdError) => {
            console.error('Failed to preload app open ad:', error.message);
          },
          onAdsExhausted: () => {
            console.log('App open ad buffer exhausted.');
          },
        },
      );
    }

    if (!this.appStateSubscription && !this.startTimeoutId) {
      // Delay attaching the listener to ensure native dismissal transitions complete
      this.startTimeoutId = setTimeout(() => {
        this.startTimeoutId = undefined;
        if (!this.appStateSubscription) {
          this.appStateSubscription = AppState.addEventListener(
            'change',
            (nextAppState: AppStateStatus) => {
              if (nextAppState === 'active') {
                this.showAdIfAvailable();
              }
            },
          );
        }
      }, APP_STATE_LISTENER_DELAY_MS);
    }

    return true;
  }

  pause(): void {
    if (this.startTimeoutId) {
      clearTimeout(this.startTimeoutId);
      this.startTimeoutId = undefined;
    }
    this.appStateSubscription?.remove();
    this.appStateSubscription = undefined;
  }

  stop(): void {
    this.pause();
    AppOpenAdPreloader.destroy(this.preloadId);
  }

  showAdIfAvailable() {
    if (!AppOpenAdPreloader.isAdAvailable(this.preloadId)) {
      console.log('App open ad is not preloaded or available right now.');
      return;
    }

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

    // Pause listener while presenting the ad
    this.pause();

    ad.adEventCallback = {
      onAdShowedFullScreenContent: () => {
        console.log('Preloaded app open ad showed full screen content.');
      },
      onAdDismissedFullScreenContent: () => {
        console.log('Preloaded app open ad dismissed full screen content.');
        ad.destroy();
        this.start();
      },
      onAdFailedToShowFullScreenContent: (error) => {
        console.error('Failed to show preloaded app open ad:', error);
        ad.destroy();
        this.start();
      },
    };

    ad.show();
  }
}

Memproses peristiwa transisi aplikasi ke latar depan

Untuk menampilkan iklan Display saat aplikasi Anda kembali ke latar depan, daftarkan pemroses change pada modul AppState di komponen root aplikasi Anda, seperti App.tsx. Periksa kapan status bertransisi ke active. Misalnya, panggil metode start pada instance pengelola iklan Anda di komponen App.tsx.

Menampilkan overlay iklan atau halaman landing, seperti menampilkan iklan layar penuh atau mengetuk iklan banner, akan mendorong aplikasi Anda ke latar belakang. Saat pengguna kembali ke aplikasi, aplikasi Anda akan menerima peristiwa status active baru. Untuk mencegah presentasi atau pengulangan iklan yang tidak diinginkan saat kembali dari iklan menampilkan iklan di layar pembuka aplikasi dari cache, lakukan tindakan berikut:

  1. Hapus pemroses peristiwa AppState sebelum menampilkan iklan layar penuh.
  2. Untuk memastikan pemrosesan dilanjutkan, baik saat pengguna menutup iklan maupun saat iklan gagal ditampilkan, tambahkan pemroses peristiwa AppState lagi di callback onAdDismissedFullScreenContent dan onAdFailedToShowFullScreenContent.

Untuk contoh lengkap cara mengontrol kapan pemroses peristiwa latar depan dijeda dan dilanjutkan, lihat implementasi AppOpenAdManager.

Mempelajari cold start dan layar pemuatan

Cold start terjadi saat aplikasi Anda diluncurkan dari awal, misalnya, saat pengguna membuka aplikasi Anda untuk pertama kalinya atau setelah perangkat menutup aplikasi untuk mengosongkan memori. Selama cold start, Anda tidak memiliki iklan di layar pembuka aplikasi yang dimuat sebelumnya untuk ditampilkan berikutnya.

Karena penundaan permintaan iklan, pengguna Anda mungkin berinteraksi dengan aplikasi Anda sebelum iklan muncul. Tampilkan iklan di layar pembuka aplikasi saat cold start hanya dari layar pemuatan saat aset aplikasi dimuat. Jika aset selesai dimuat dan pengguna mencapai konten utama sebelum iklan dimuat, jangan tampilkan iklan.

Membersihkan resource

Jika pramuat tidak lagi diperlukan untuk layar atau ID unit iklan, seperti saat berpindah dari layar yang melakukan pramuat iklan, panggil metode AppOpenAdPreloader.destroy untuk merilis resource pra-pemuat dan mencegah penyimpanan objek iklan yang tidak digunakan dalam memori:

export function destroyAppOpenAdPreloader(preloadId: string) {
  AppOpenAdPreloader.destroy(preloadId);
}

Selain menghancurkan antrean preloader, pastikan untuk menghancurkan setiap instance iklan yang di-polling saat pengguna menutup iklan atau iklan gagal ditampilkan. Untuk mengetahui detailnya, lihat Melakukan polling dan menampilkan iklan.

Lihat contoh lengkapnya

Contoh komponen berikut memulai pramuat saat pemasangan, melacak jumlah iklan yang tersedia, dan menyediakan kontrol untuk menampilkan iklan di layar pembuka aplikasi yang telah dipramuat:

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

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

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

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

  const handleShowAd = () => {
    setStatus('Showing preloaded ad...');
    showPreloadedAppOpenAd(PRELOAD_ID, {
      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 App Open Ads</Text>
      <Text style={styles.status}>Status: {status}</Text>
      <Text style={styles.status}>Ads Available: {numAdsAvailable}</Text>
      <View style={styles.buttonGroup}>
        <Button
          title="Show Preloaded Ad"
          onPress={handleShowAd}
          disabled={numAdsAvailable === 0}
        />
      </View>
    </View>
  );
}

Ganti kode berikut:

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

Langkah berikutnya

Setelah Anda mengintegrasikan iklan di layar pembuka aplikasi, pelajari topik berikut: