Skip to main content

QSPlaySDK.ad

Full-screen video ads: midgame interstitials shown in a natural pause, and rewarded ads the player opts into for an in-game reward. The portal renders the ad inside your game's own document rather than as a separate overlay, so it stays visible in fullscreen the same way the rest of the game does — see Fullscreen mode.

For when and how ads may be requested, and what your game must do around them, see Requirements · Ads.

Requesting an ad​

ad.requestAd(kind, callbacks):

await QSPlaySDK.ad.requestAd("midgame", {
adStarted: () => { pauseGame(); muteAudio(); },
adFinished: () => { unmuteAudio(); resumeGame(); },
adError: () => { unmuteAudio(); resumeGame(); },
});

kind is "midgame" or "rewarded":

  • "midgame" — an interstitial for a natural pause: the end of a level, a restart, a return to the menu. Request it only after game.gameplayStop() — the portal rejects the request while gameplay is active.
  • "rewarded" — shown only after the player explicitly chooses to watch it (for example, a "Watch ad for reward" button). Tell the player what the reward is before the ad starts, and grant it only from adRewarded — never earlier, and never if the ad doesn't finish.

The call resolves once the whole flow is over — the ad was shown and closed, or it failed to show — and never rejects. Handle both outcomes through callbacks, not try/catch:

interface AdCallbacks {
adStarted?(): void;
adFinished?(): void;
adRewarded?(): void;
adError?(error: { code: string; message?: string }): void;
}
CallbackWhenWhat to do
adStartedThe ad is actually on screen.Pause gameplay and mute audio.
adFinishedThe ad closed normally (shown or not). Always fires after adStarted, never together with adError.Resume gameplay and audio.
adRewardedkind: "rewarded" only — the player watched it through. Fires before adFinished.Grant the reward. Never grant it anywhere else.
adErrorNo ad was shown — see Error codes.Resume gameplay and audio, same as adFinished.

Timing rules​

The portal enforces these limits itself — a request outside them is simply rejected with the matching error code:

RuleLimit
First "midgame" after the session's first game.gameplayStart()Not before 60 seconds
Interval between two "midgame" adsAt least 120 seconds
Interval between two "rewarded" adsAt least 15 seconds
"rewarded" ads per sessionUp to 60
"midgame" while gameplay is activeNever — request it only after gameplayStop()

These numbers may change as the portal tunes them against real ad performance — branch your handling on error.code, never on a specific wait time.

Error codes​

adError's error.code:

CodeWhen
unfilledNo ad was available to show.
cooldownThe minimum interval for this ad type hasn't passed yet (see Timing rules).
maxReachedThe per-session limit for this ad type was reached.
gameplayActive"midgame" was requested while gameplay is active — call game.gameplayStop() first.
videoAdPlayingAnother video ad is already showing.
adsDisabledAds are off for this session (for example, a kids-mode game, or the game opened outside the portal).
otherThe ad didn't become ready within ~8 seconds — most often an ad blocker (blocking the ad-frame itself, or just Playgama's script inside it), but also covers any other render failure or timeout.

banner.* methods use a few additional, banner-specific codes — see Banner module · Error codes.

Testing without ads​

In mock mode, ad.requestAd() doesn't show a real ad, but it is visible: a full-screen placeholder appears (labeled with the requested kind and the current state) while the SDK simulates a ~3-second ad locally, firing adStarted, then adRewarded (for kind: "rewarded"), then adFinished — enough to see and test pausing, muting, and reward granting without a live portal.