Load a single app open ad

App open ads appear when your users open or return to your app. Your users can close app open ads at any time. To monetize your app load screen, use app open ads. For details, see

App open ad guidance and best practices.

This guide explains how to integrate app open ads into a React Native app.

Prerequisites

Before you continue, do the following:

Android 

ca-app-pub-3940256099942544/9257395921

iOS 

ca-app-pub-3940256099942544/5575463023

Load an ad

To load an app open ad, call the load method.

The following example loads an app open ad on success and logs an error on failure:

export async function loadAppOpenAd(
  adUnitId: string,
): Promise<AppOpenAd | null> {
  try {
    const ad = await AppOpenAd.load({adUnitId});
    return ad;
  } catch (error) {
    const loadError = error as LoadAdError;
    console.error('Failed to load app open ad:', loadError.message);
    return null;
  }
}

Listen to ad events

Before you show the ad, set the adEventCallback listener on the loaded AppOpenAd instance. This listener receives callbacks of ad lifecycle events, such as the ad showing on the screen or a user tapping the ad. For available callbacks, see AdEventCallback.

The following example sets callbacks to listen for ad events:

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

This example also uses the destroy method when a user closes the ad or when the ad fails to show. This process releases the resources the ad used.

Show the ad

To show an app open ad, call the show method:

export function showAppOpenAd(ad: AppOpenAd) {
  ad.show();
}

Manage ads with an app-level manager

We recommend that you manage app open ads in an app-level manager outside the React component tree. Because app open ads appear globally when your user opens or returns to your app, an app-level manager keeps ads separate from the user interface.

The following example creates a SingleLoadAppOpenAdManager instance that loads an ad, listens for ad events, and checks ad availability:

export class SingleLoadAppOpenAdManager {
  private ad: AppOpenAd | null = null;
  private loadTime = 0;
  private isShowingAd = false;

  async loadAd(adUnitId: string) {
    // Avoid re-loading if an ad is already loaded or showing.
    if (this.ad) {
      return;
    }
    try {
      this.ad = await AppOpenAd.load({adUnitId});
      this.loadTime = Date.now();
      this.ad.adEventCallback = {
        onAdDismissedFullScreenContent: () => {
          this.ad?.destroy();
          this.ad = null;
          this.isShowingAd = false;
          // Preload the next ad for future foreground transitions.
          this.loadAd(adUnitId);
        },
        onAdFailedToShowFullScreenContent: () => {
          // An ad object that fails to present is consumed and cannot be reused.
          // Clean up native resources and preload a new ad for future events.
          this.ad?.destroy();
          this.ad = null;
          this.isShowingAd = false;
          this.loadAd(adUnitId);
        },
      };
    } catch (error) {
      console.error('Failed to load app open ad:', error);
    }
  }

  showAdIfAvailable() {
    if (!this.ad || !this.isAdAvailable()) {
      console.warn(
        'App open ad cannot be shown: ad is not loaded or has expired.',
      );
      return;
    }
    if (this.isShowingAd) {
      console.warn('App open ad cannot be shown: an ad is already displaying.');
      return;
    }

    this.ad.show();
    this.isShowingAd = true;
  }

  isAdAvailable(): boolean {
    // App Open ads expire after 4 hours per Google Mobile Ads policy.
    const FOUR_HOURS_IN_MS = 4 * 60 * 60 * 1000;
    return this.ad !== null && Date.now() - this.loadTime < FOUR_HOURS_IN_MS;
  }
}

An app-level manager helps you do the following:

  • Keep ad state independent of screen navigation and component lifecycles.
  • Track ad presentation state across native thread events.
  • Handle app foreground transitions to avoid showing repeated ads.
  • Preload ads in the background to make ads available for when your app opens.
  • Check the four-hour ad expiration limit to avoid showing expired ads.
  • Combine loading, showing, and cleaning up ad resources.

Listen to app foreground events

To display ads when your app returns to the foreground, use the AppState module to listen for app state changes at the root of your app, for example, in the App.tsx file. Do the following:

  1. Register an AppState listener for the 'change' event.
  2. When the state transitions to the 'active' state, call the showAdIfAvailable method on the ad manager instance.

The following example listens to app foreground events and shows an ad if available:

export function setupAppOpenAdForegroundListener(adManager: {
  showAdIfAvailable: () => void;
}): NativeEventSubscription {
  return AppState.addEventListener('change', (nextAppState: AppStateStatus) => {
    if (nextAppState === 'active') {
      adManager.showAdIfAvailable();
    }
  });
}

Learn cold starts and loading screens

A cold start occurs when your app launches from scratch, for example, when a user opens your app for the first time or after the device closes the app to free memory. During a cold start, you lack a previously loaded app open ad to show next.

Due to ad request delays, your users might interact with your app before an ad appears. To avoid a poor user experience, show app open ads on cold starts only from a loading screen while app assets load. If assets finish loading and the user reaches the main content before the ad loads, don't show the ad.

Set up a test screen

To test ads interactively or display the ads on a specific screen, manage the ad instance in component state.

The following example integrates an app open ad into a React Native component with a useEffect cleanup hook. If the component unmounts before the ad shows, this hook releases native resources.

export function AppOpenSingleLoadScreen() {
  const [ad, setAd] = useState<AppOpenAd | null>(null);
  const [isLoaded, setIsLoaded] = useState(false);
  const [status, setStatus] = useState<string>('Idle');

  useEffect(() => {
    return () => {
      ad?.destroy();
    };
  }, [ad]);

  const handleLoad = async () => {
    setStatus('Loading App Open ad...');
    const loadedAd = await loadAppOpenAd(APP_OPEN_AD_UNIT_ID);
    if (loadedAd) {
      registerAdEvents(loadedAd);
      const onDismiss =
        loadedAd.adEventCallback?.onAdDismissedFullScreenContent;
      loadedAd.adEventCallback = {
        ...loadedAd.adEventCallback,
        onAdDismissedFullScreenContent: () => {
          onDismiss?.();
          setStatus('Ad dismissed.');
        },
      };
      setAd((prevAd) => {
        prevAd?.destroy();
        return loadedAd;
      });
      setIsLoaded(true);
      setStatus('App Open ad loaded!');
    } else {
      setStatus('Failed to load App Open ad.');
    }
  };

  const handleShow = () => {
    if (ad) {
      showAppOpenAd(ad);
      setIsLoaded(false);
    }
  };

  return (
    <View style={styles.container}>
      <Text style={styles.title}>App Open Ad</Text>
      <Text style={styles.status}>Status: {status}</Text>
      <View style={styles.buttonGroup}>
        <Button title="Load Ad" onPress={handleLoad} />
        <View style={styles.spacerSmall} />
        <Button title="Show Ad" onPress={handleShow} disabled={!isLoaded} />
      </View>
    </View>
  );
}

Next steps

After you integrate an app open ad, explore the following topics: