Ads

Rewarded, interstitial, and preroll ads with automatic platform routing.

Setup

Configure via HyveSdkProvider:

<HyveSdkProvider config={{
  ads: {
    sound: 'on',
    onBeforeAd: (type) => pauseGame(),
    onAfterAd: (type) => resumeGame(),
    onRewardEarned: () => grantReward(),
  }
}}>

Or configure after construction:

hyve.configureAds({ sound: 'off', debug: true });

HTML Setup (Google H5 Ads)

Required in your index.html for the Google H5 fallback:

<script async src="https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js"></script>
<script>
  window.adBreak = window.adBreak || function(o) { (window.adsbygoogle = window.adsbygoogle || []).push(o); };
  window.adConfig = window.adConfig || function(o) { (window.adsbygoogle = window.adsbygoogle || []).push(o); };
</script>

Showing Ads

const result = await hyve.showAd('rewarded');     // user opts in for reward
const result = await hyve.showAd('interstitial'); // between levels / game over
const result = await hyve.showAd('preroll');      // at game start

if (result.success) {
  // grant reward, resume game, etc.
}

interface AdResult {
  success: boolean;
  type: 'rewarded' | 'interstitial' | 'preroll';
  error?: Error;
  requestedAt: number;
  completedAt: number;
}

Platform Routing

showAd() auto-routes in priority order:

Priority	Platform	Condition
1	CrazyGames	document.referrer or parent hostname contains crazygames.com
2	Playgama	?platform_id=playgama, referrer, or parent hostname contains playgama.com
3	Google H5 Games Ads	Fallback

hyve.areAdsReady(); // boolean — Google H5 Ads initialized successfully

Native AdMob (Hyve mobile shell)

When a game runs inside the Hyve mobile app (a React Native WebView), ads can be served by native AdMob instead of Google H5. This is gated behind the useNativeAds flag and is fully backward compatible — the game-facing API does not change.

Enable it in the provider config:

<HyveSdkProvider config={{
  ads: {
    useNativeAds: true, // opt in to native AdMob inside the mobile shell
    onRewardEarned: () => grantReward(),
  }
}}>

Or after construction:

hyve.configureAds({ useNativeAds: true });

Showing ads is unchanged. An optional placement key is forwarded to native to resolve a per-placement ad unit (ignored on the H5 web path):

await hyve.showAd('rewarded');               // routed to native inside the shell
await hyve.showAd('rewarded', 'level_end');  // with a placement key

Routing is decided at call time:

Condition	Path taken
window.ReactNativeWebView present and useNativeAds: true	Native AdMob bridge
Otherwise	Google H5 web path (unchanged)

Notes:

• preroll maps to a native interstitial — AdMob has no preroll primitive.
• The SDK never resolves ad unit IDs. It sends { gameId, format, placement? } and native owns the lookup. No unit IDs are stored or sent by the SDK.
• placement is optional — native falls back to the default placement when it is omitted or unknown for the format.
• Automatic web fallback. If native reports not_configured (the format has no ad unit) or config_fetch_failed (could not fetch config), that single call falls back to the H5 web path. Lifecycle callbacks still fire exactly once.
• Callbacks are unchanged. onRewardEarned() fires only on a successful rewarded view; onAfterAd(type) fires regardless of success, matching H5 behavior.

CrazyGames Signals

CrazyGames requires explicit gameplay start/stop signals. No-ops on all other platforms.

await hyve.gameplayStart(); // call when active gameplay begins
await hyve.gameplayStop();  // call when gameplay pauses (menu, cutscene, level end)
await hyve.happytime();     // trigger celebration for significant achievements

Troubleshooting

Symptom	Fix
Ads not showing	Confirm Google H5 <script> tags are in HTML
areAdsReady() false	Google Ads SDK did not initialize — check script tags and ad blocker
Wrong platform detected	Enable debug: hyve.configureAds({ debug: true })
Native AdMob not used in app	Confirm useNativeAds: true and that the game runs inside the Hyve mobile shell (window.ReactNativeWebView present)
Native ad falls back to web	Format reported not_configured / config_fetch_failed — verify the placement has an ad unit configured natively