Setup App Open Ad

App Open Ad is slightly different from other Full Screen Ads.

Creating App Open Ad

Hook API

Simplest way to add App Open Ad to your app is wrapping your app components with AppOpenAdProvider and using useAppOpenAd hook.

When you wrap your app components with AppOpenAdProvider it automatically creates AppOpenAd instance and start to provide App Open Ad to your app.

Class API

If you are not going to use useAppOpenAd hook, you don't need to wrap your app with AppOpenAdProvider. But, you need to create ad instance using AppOpenAd.create method. While other Full Screen Ads can be created multiple times and each ads have their own instance, only one AppOpenAd instance can be exist in a app. If you create App Open Ad using AppOpenAd.createAd() static method more than once, previous ad instance will be destroyed and newly created ad instance will replace it.

You don't need to keep reference to AppOpenAd instance because it is managed to be singleton and you can access the ad via static methods.

Loading App Open Ad

Library automatically loads ad when it is created or dismissed.

Also, ad is automatically loaded when app comes to foreground from background, but has no ad loaded.

Showing App Open Ad

Ad is automatically shown when app comes to foreground and has loaded ad previously.

Cold starts and loading screens

"Cold starts" occur when your app is launched but was not previously suspended in memory.

An example of a cold start is when a user opens your app for the first time. With cold starts, you won't have a previously loaded app open ad that's ready to be shown right away. The delay between when you request an ad and receive an ad back can create a situation where users are able to briefly use your app before being surprised by an out of context ad. This should be avoided because it is a bad user experience.

The preferred way to use app open ads on cold starts is to use a loading screen to load your game or app assets, and to only show the ad from the loading screen. If your app has completed loading and has sent the user to the main content of your app, do not show the ad.

Accessing Ad's status

You can access to ad's status by using derived values of useAppOpenAd hook.

If you are using Class API instead of using hook, add listeners to listen for ad's status changes such as adDismissed event.

Usage Example

Example below uses external library react-native-bootsplash to implement splash screen. This is not necessary, but we recommend you to use this library with App Open Ad because App Open Ad must be showed before the app content showed.

In this example, we want to show app open ad when app starts and when app comes to foreground from background. Also, we want to run async task on app startup while showing ad to user and until the job is done and ad is dismissed, we need to show splash screen.

App.tsx

import { AppOpenAdProvider, TestIds } from '@react-native-admob/admob';

export default function App() {
  const [splashDismissed, setSplashDismissed] = useState(false);

  return (
    <AppOpenAdProvider
      unitId={TestIds.APP_OPEN}
      options={{ showOnColdStart: true, loadOnDismissed: splashDismissed }}
    >
      {splashDismissed ? (
        <MainScreen />
      ) : (
        <SplashScreen onSplashDismissed={() => setSplashDismissed(true)} />
      )}
    </AppOpenAdProvider>
  );
}

In order to display ad as soon as the ad loads (only on app startup), we need to set showOnColdStart to true. Also, we need to set loadOnDismissed to splashDismissed because in the splash screen, we don't want to let ad to be loaded as soon as it is dismissed, otherwise, derived value adDismissed will be initialized to false as soon as new ad is requested.

SplashScreen.tsx

import RNBootSplash from 'react-native-bootsplash';
import { useAppOpenAd } from '@react-native-admob/admob';

export default function SplashScreen({ onSplashDismissed }) {
  const [loaded, setLoaded] = useState(false);
  const { adDismissed, adLoadError } = useAppOpenAd();

  useEffect(() => {
    const load = async () => {
      // Dummy Long Running Task
      await new Promise((resolve) => setTimeout(resolve, 3000));
      setLoaded(true);
    };
    load();
  }, []);

  useEffect(() => {
    async function hide() {
      await RNBootSplash.hide({ fade: true });
      onSplashDismissed();
    }
    if (loaded && (adDismissed || adLoadError)) {
      hide();
    }
  }, [loaded, adDismissed, adLoadError, onSplashDismissed]);

  return <View />;
}

In the splash screen component, we use useAppOpenAd hook to watch for ad's status changes. If ad gets error or dismissed, we need to hide the splash screen.