Skip to content
rdlabo.devdocs
日本語

Rewarded Ads

Rewarded ads let you give in-app items for interacting with video ads, playable ads, or surveys. Google's rewarded guides for Android and iOS explain the format.

Treat rewarded ads as a reward flow, not as another non-rewarded interstitial. Call this after initialize and consent. Grant the reward only from the returned result or the Rewarded event, not from Dismissed.

Rewarded video

Use a rewarded ad for a dedicated reward flow.

import {
  AdLoadInfo,
  AdMob,
  AdMobRevenueData,
  AdMobRewardItem,
  RewardAdOptions,
  RewardAdPluginEvents,
} from '@capacitor-community/admob';

await AdMob.addListener(RewardAdPluginEvents.Loaded, (info: AdLoadInfo) => {
  console.log('Rewarded ad loaded', info.adUnitId);
});
await AdMob.addListener(RewardAdPluginEvents.FailedToLoad, console.error);
await AdMob.addListener(RewardAdPluginEvents.Rewarded, (reward: AdMobRewardItem) => {
  console.log('Reward earned', reward.amount, reward.type);
});
await AdMob.addListener(RewardAdPluginEvents.AdImpression, (data: AdMobRevenueData) => {
  console.log(data);
});

const options: RewardAdOptions = {
  adId: 'YOUR_AD_UNIT_ID',
  // isTesting: true,
  // npa: true,
  // immersiveMode: true,
  // ssv: {
  //   userId: 'USER_ID',
  //   customData: JSON.stringify({ placement: 'bonus' }),
  // },
};
await AdMob.prepareRewardVideoAd(options);
const rewardItem = await AdMob.showRewardVideoAd();
// Grant the reward once, using this result or the Rewarded event — not both.
console.log(rewardItem);

method prepareRewardVideoAd(...)

Loads a rewarded ad and returns the loaded ad unit ID.

prepareRewardVideoAd(options: RewardAdOptions) => Promise<AdLoadInfo>

method showRewardVideoAd(...)

Shows a loaded rewarded ad and resolves when the user earns the reward.

showRewardVideoAd(options?: AdShowOptions | undefined) => Promise<AdMobRewardItem>

interface RewardAdOptions

Options for loading a rewarded ad.

Prop Type Description Default Since
ssv AtLeastOne<{ /** * A user identifier passed to the SSV callback. */ userId: string; /** * Custom data passed to the SSV callback. */ customData: string; }> Server-side verification options for the rewarded ad. Provide at least one of userId or customData.
adId string The ad unit ID to load. 1.1.2
isTesting boolean Whether to request a test ad. false 1.1.2
margin number The banner margin in logical display units (dp on Android and points on iOS). For BOTTOM_CENTER, this is the bottom margin. For TOP_CENTER, this is the top margin. 0 1.1.2
npa boolean Whether to request non-personalized ads. false 1.2.0
immersiveMode boolean Whether to display a full-screen ad in immersive mode on Android. 7.0.3

interface AdMobRewardItem

The reward earned by the user after viewing a rewarded ad.

Prop Type Description
type string The reward item type configured for the ad unit.
amount number The reward amount earned by the user.

When no adId is passed to showRewardVideoAd(), the most recently prepared ad is shown.

Prepare more than one ad

await AdMob.prepareRewardVideoAd({ adId: 'ca-app-pub-xxx/reward-1' });
await AdMob.prepareRewardVideoAd({ adId: 'ca-app-pub-xxx/reward-2' });

const reward = await AdMob.showRewardVideoAd({ adId: 'ca-app-pub-xxx/reward-1' });

Rewarded interstitial

Rewarded interstitial ads are incentivized full-screen ads that appear during natural app transitions. Unlike rewarded video, the user does not opt in first. Google's rewarded interstitial guides for Android and iOS explain the format.

Use a rewarded interstitial when the rewarded experience belongs at a natural transition in the app.

import {
  AdMob,
  AdMobRewardInterstitialItem,
  RewardInterstitialAdOptions,
  RewardInterstitialAdPluginEvents,
} from '@capacitor-community/admob';

await AdMob.addListener(RewardInterstitialAdPluginEvents.FailedToLoad, console.error);

const options: RewardInterstitialAdOptions = {
  adId: 'YOUR_AD_UNIT_ID',
};
const { adUnitId } = await AdMob.prepareRewardInterstitialAd(options);
const rewardItem: AdMobRewardInterstitialItem = await AdMob.showRewardInterstitialAd({
  adId: adUnitId,
});
console.log(rewardItem);

method prepareRewardInterstitialAd(...)

Loads a rewarded interstitial ad and returns the loaded ad unit ID.

prepareRewardInterstitialAd(options: RewardInterstitialAdOptions) => Promise<AdLoadInfo>

method showRewardInterstitialAd(...)

Shows a loaded rewarded interstitial ad and resolves when the user earns the reward.

showRewardInterstitialAd(options?: AdShowOptions | undefined) => Promise<AdMobRewardInterstitialItem>

interface RewardInterstitialAdOptions

Options for loading a rewarded interstitial ad.

Prop Type Description Default Since
ssv AtLeastOne<{ /** * A user identifier passed to the SSV callback. */ userId: string; /** * Custom data passed to the SSV callback. */ customData: string; }> Server-side verification options for the rewarded interstitial ad. Provide at least one of userId or customData.
adId string The ad unit ID to load. 1.1.2
isTesting boolean Whether to request a test ad. false 1.1.2
margin number The banner margin in logical display units (dp on Android and points on iOS). For BOTTOM_CENTER, this is the bottom margin. For TOP_CENTER, this is the top margin. 0 1.1.2
npa boolean Whether to request non-personalized ads. false 1.2.0
immersiveMode boolean Whether to display a full-screen ad in immersive mode on Android. 7.0.3

interface AdMobRewardInterstitialItem

The reward earned by the user after viewing a rewarded interstitial ad.

Prop Type Description
type string The reward item type configured for the ad unit.
amount number The reward amount earned by the user.

See Testing for isTesting.

Server-side verification

Server-side verification (SSV) lets your backend confirm that a reward was earned. See Google's SSV documentation. Callbacks fire only for production ads; test ads do not invoke your SSV endpoint.

For local validation of the ssv payload, you can send a mock request after RewardAdPluginEvents.Rewarded. Replace ENVIRONMENT_IS_DEVELOPMENT with your own development flag:

const userId = 'USER_ID';
const customData = JSON.stringify({ placement: 'bonus' });

await AdMob.addListener(RewardAdPluginEvents.Rewarded, async () => {
  if (!ENVIRONMENT_IS_DEVELOPMENT) {
    return;
  }
  try {
    const params = new URLSearchParams({
      ad_network: 'TEST',
      ad_unit: 'TEST',
      custom_data: customData,
      reward_amount: 'TEST',
      reward_item: 'TEST',
      timestamp: 'TEST',
      transaction_id: 'TEST',
      user_id: userId,
      signature: 'TEST',
      key_id: 'TEST',
    });
    await fetch(`https://your-staging-ssv-endpoint?${params.toString()}`);
  } catch (err) {
    console.error(err);
  }
});
Edit this page on GitHub