FAQ

Will it slow my game down?

The loader is a small async script, and the rest of the SDK is imported only when it's needed (and warmed up once the page is idle, so the first break() doesn't wait). Bonus Round models are budgeted (about 10k triangles for a hero, 3k for a collectible) with 1K textures. Nothing loads until there's an ad to show.

What happens with an ad blocker?

The script doesn't load, window.BonusRound is undefined, and if you wrote window.BonusRound?.break('intermission') the line does nothing and your game carries on. Use the bonusround queue for attach() and ?. for everything else and an ad blocker can never break your game.

Which three.js versions work?

The SDK builds everything with the THREE you pass to attach(), so it uses your version and never loads a second copy. It reports your revision to the dashboard. Use WebGLRenderer.

I use React Three Fiber / a framework on top of three.js.

Fine. You need access to the scene, the camera and the renderer; R3F gives you all three from useThree(). See Install → React Three Fiber. Engines that hide three.js entirely may need a native-mode adapter; get in touch.

Does it work in multiplayer games?

Yes. In overlay mode and native mode without net, each player's round runs locally in their browser. To have everyone drop into the same round with the same item layout and a shared leaderboard, pass host.net and relay Bonus Round messages through your game server (native-net mode). Our demo game, Hop Isle, works this way.

Does it work on phones?

Rounds use the same controls the game does. In native mode that's your own touch controls. In overlay mode the round uses the control scheme our agent learned from your game, so make sure your game's touch controls work in a browser.

My game runs in an iframe (itch.io, a CDN host).

Put the script tag in the page inside the iframe, the one that runs three.js. Add the iframe's host to your game's domains so ads are served there.

My game is also on Poki, CrazyGames, GameDistribution or Y8.

Keep the same build. Those portals don't allow third-party ads, so the SDK detects them and switches itself off there (no ad requests, break() resolves with reason: 'portal'), and your dashboard shows a notice. See portal mode.

Will rounds interrupt my players mid-game?

Only if you call break() mid-game. Intermission rounds happen where you call them; interval rounds are offers the player can decline (and you can block them with BonusRound.safe(false)); rewarded rounds are opt-in.

What should my game do while a round plays?

In overlay mode, pause what you like: your canvas is covered. In native mode, keep rendering and keep player movement running (the player is playing the round in your world), but pause timers, enemies, damage and scoring. Use the start and end events for rounds you didn't start yourself.

How much will I earn?

It depends on your audience, your game's engagement and how many brands match it. You get 70% of net ad revenue (spend, minus any disclosed agency commission). Rewarded and intermission rounds earn the most per player; the interval trigger and ambient props add volume. Real numbers appear in your dashboard as soon as there's real traffic. Test traffic never counts.

Why does break() resolve immediately?

There was nothing to show. Check the reason in the result: no_eligible_campaigns (no brand has an approved round for your game yet), below_floor, game_frequency_cap or frequency_cap, takeover_disabled/trigger_disabled/format_disabled, origin_not_allowed (the page isn't on your game's domains), game_paused, not_attached (attach() hasn't finished: call it first, and wait for it when you call the SDK right after), busy (a round is already playing), ad_server_unreachable or load_timeout (network trouble), or sdk_unavailable (the script didn't load).

Can I test on localhost?

Yes. localhost, 127.0.0.1 and *.localhost are always allowed, and a game in test mode always gets the Fizzpop test round.

How do I remove it?

Delete the script tag and the lines that call BonusRound. Nothing else in your game depends on it. To stop ads without a deploy, pause the game in the dashboard.

Something's wrong.

Run await BonusRound.debug() in the console on your game's page and include the output when you contact us. It has the SDK mode, whether it's attached, test mode, settings, the current round, the ambient prop, and the last ad requests (with the reason each one didn't fill) and events. Warnings and errors from the SDK are in the console with a [bonusround] prefix.