Ads

FRVR.ads wraps a waterfall of ad providers. You ask for an ad type; it picks a ready provider and shows it.

Ad types

Type	Use for	Opt‑in?	Pauses game?
`INTERSTITIAL`	Full‑screen break between levels	No	Yes
`REWARD`	Extra life, 2× coins, etc.	Yes (user tapped)	Yes
`BANNER`	Persistent strip at top/bottom	No	No

All live under the FRVR.ads.AdType enum.

Show an ad

Every call returns a promise that resolves with an AdShowResult:

FRVR.ads.show(FRVR.ads.AdType.INTERSTITIAL).then(result => {
  // result is one of:
  //   FRVR.ads.AdShowResult.NOT_DISPLAYED  — nothing was ready, or throttled
  //   FRVR.ads.AdShowResult.DELIVERED      — shown, user dismissed
  //   FRVR.ads.AdShowResult.COMPLETED      — (rewarded) watched to the end
});

For rewarded flows you only hand out the reward on COMPLETED. Use DELIVERED to detect a user‑skipped ad — the ad showed but was dismissed before the end, so no reward is owed. A rejected promise (or any other result) means the ad failed to show at all:

FRVR.ads.show(FRVR.ads.AdType.REWARD).then((result) => {
  if (result === FRVR.ads.AdShowResult.COMPLETED) {
    giveReward();
  } else if (result === FRVR.ads.AdShowResult.DELIVERED) {
    showAdSkipped();   // user skipped — no reward
  } else {
    showAdError();     // nothing was ready / couldn't show
  }
}).catch(() => {
  showAdError();
});

Gate your UI on readiness

Nothing worse than a “Watch ad” button that does nothing. Check isReady before showing it:

if (FRVR.ads.isReady(FRVR.ads.AdType.REWARD)) {
  showWatchAdButton();
}

isSupported(type) tells you whether any configured provider can handle that type at all (useful for hiding banners on platforms that have no banner network).

Banners

Banners stay up until you hide them:

FRVR.ads.show(FRVR.ads.AdType.BANNER);
// later:
FRVR.ads.hide(FRVR.ads.AdType.BANNER);

Throttling (and why `NOT_DISPLAYED` is the default state)

Interstitials are throttled out of the box — the SDK enforces a minimum interval between interstitials (default ~5 minutes) and will refuse to show one during the first ~100 seconds of a session. Asking for an interstitial inside that window resolves to AdShowResult.NOT_DISPLAYED with no provider call. This is expected behavior, not an integration bug.

Override for testing or to tune frequency:

FRVR.config.ads = {
  throttling: {
    maxfrequency: 60000,   // 60 s minimum between interstitials (ms). 0 disables.
    initTimeBlock: 0,      // block-all window after init (ms). 0 disables.
    forceFirstAd: true,    // allow the very first interstitial through immediately
  },
};

REWARD and BANNER are not throttleable — they always reach the provider.

Lifecycle

Full‑screen ads automatically trigger onSuspend → onAudioSuspend when they open, and the paired …Resume calls when they close. You don’t need to pause your game manually — just implement the hooks (they’re required).

Listening for ads

const unsubscribe = FRVR.ads.onAdShown(({ type, providerId }) => {
  analytics.tag('ad_shown', { type, providerId });
});

getAdShownCount() returns a per‑type counter useful for capping lifetime impressions.

Try it live

This demo uses the dev channel, which ships a fake provider. We also pass throttling: { maxfrequency: 0, forceFirstAd: true } so you can click repeatedly without hitting the default 5‑minute cooldown. The dev provider pops a browser confirm() dialog — accept to simulate “ad completed”, cancel to simulate “ad skipped/dismissed”.

Ads: interstitial, reward, banner

loading SDK…

Interstitial

Rewarded

Banner

API summary

Method	Purpose
`show(type)`	Show an ad. Returns a promise resolving to an `AdShowResult`.
`hide(type)`	Hide a persistent ad (typically banners).
`isReady(type)`	Any provider ready right now?
`isSupported(type)`	Is this ad type available on this channel at all?
`onAdShown(fn)`	Subscribe to impressions. Returns an unsubscribe.
`getAdShownCount()`	Per‑type impression counter since app start.
`setUserConsent(bool)`	Pass updated consent to providers.