Set up rewarded ads

Rewarded ads give your users in-app items for interacting with video ads, playable ads, and surveys. For details, see Overview of rewarded ad units.

To eliminate presentation latency and make sure an ad is available when a user earns a reward, Google Mobile Ads SDK for React Native uses ad preloading to manage background loading, caching, and buffer replenishment.

This guide shows you how to integrate rewarded ads in a React Native app.

Prerequisites

Before you continue, do the following:

Android 

ca-app-pub-3940256099942544/5224354917

iOS 

ca-app-pub-3940256099942544/1712485313

Understand ad preloading

Ad preloading in Google Mobile Ads SDK for React Native automates ad loading and caching.

Ad preloading provides the following benefits:

  • Reference management: maintains references until ads are shown.
  • Automatic reloading: loads a new ad when one is retrieved from the cache.
  • Managed retries: loads a new ad when one fails to load.
  • Expiration handling: refreshes ads before expiring.
  • Cache optimization: optimizes the cache order to deliver the highest priority ad.

To load ads manually, see Load a single rewarded ad.

Start preloading

To start preloading ads, call the RewardedAdPreloader.start method and pass your preloadId value, configuration settings, and event callbacks to monitor buffer state changes:

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;
}

A preload ID is a string that uniquely identifies an ad preloading configuration. If you use the ad unit ID for a single preloading configuration in your app, you can use that ad unit ID as the preload ID. If your app requires multiple preloaders for the same ad unit ID, pass distinct strings for each preload ID.

When your app polls a preloaded ad from the buffer, Google Mobile Ads SDK for React Native requests a replacement ad in the background to refill the buffer. If no preloaded ads remain in the buffer, Google Mobile Ads SDK for React Native invokes the onAdsExhausted.

Preload cache limits

Google Mobile Ads SDK for React Native enforces an app-wide limit on the total number of preloaded ads across all ad units and preload IDs:

  • Default limit: Google holds a maximum of six preloaded ads in memory. This limit is shared across all formats and preload IDs.
  • Recommended buffer size: Two for each preload ID.

If your app reaches the app-wide limit, background requests for preloaded ads pause until existing ads are polled from the cache or destroyed. Preloading also temporarily pauses while a full-screen ad is actively displayed on screen.

Poll and show the ad

Before showing an ad, verify an ad is available by calling the RewardedAdPreloader.isAdAvailable method. To retrieve the ad, call the RewardedAdPreloader.pollAd method.

To listen for presentation events, like ad dismissals or display failures, set the adEventCallback property on the ad instance before calling the show method:

The following example checks for ad availability, and listens for presentation events before showing the ad:

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);
}

To release memory and resources, call the ad.destroy method in the onAdDismissedFullScreenContent and onAdFailedToShowFullScreenContent callbacks.

Read the response info

To inspect response info for the next preloaded ad without removing the ad from the cache, call the RewardedAdPreloader.peekAdResponseInfo method:

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;
}

If an ad is available, the peekAdResponseInfo method returns a ResponseInfo object containing information about the loaded ad source and network adapters.

Optional: Validate server-side verification callbacks

If your app requires custom verification parameters, such as a user ID or custom reward metadata, in server-side verification (SSV) callbacks, set the serverSideVerificationOptions property on the polled ad instance before calling show.

The values you set are passed to the SSV callback query parameters:

  • userId: Passes to the user_id query parameter to identify the user.
  • customData: Passes to the custom_data query parameter to forward custom metadata.

The following example sets ServerSideVerificationOptions (customData and userId) on a rewarded ad object before showing an ad:

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

Clean up resources

If you no longer need to show ads for a specific preload ID for the rest of the session, call the RewardedAdPreloader.destroy method. This process stops preloading for that preload ID and frees unused preloaded ads from memory.

The following example stops preloading:

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

After your user dismisses the ad or the ad fails to show, destroy individual polled ad instances. For details, see Poll and show the ad.

View the full example

The following example component starts preloading on mount, tracks available ad counts, and provides controls to show preloaded rewarded ads:

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>
  );
}

Replace the following:

  • REWARDED_AD_UNIT_ID with your ad unit ID.
  • PRELOAD_ID with your preloader ID.

Next steps

After you integrate rewarded ads, explore the following topics: