QSPlaySDK.banner
Banner ads rendered inside your game's own document — in an HTML element you provide, or, for
canvas-based engines, in an overlay the SDK positions over the canvas for you. Because they live in
the game's document, they stay visible through fullscreen and resize, the same way
ad.requestAd() does.
For where banners may and may not appear, see Requirements · Ads.
Banner sizes
Every width/height must be one of:
| Size | |
|---|---|
| 970×90 | Large leaderboard |
| 728×90 | Leaderboard |
| 320×50 | Mobile banner |
| 300×600 | Half page |
| 300×300 | Square |
| 300×250 | Medium rectangle |
| 300×100 | Small rectangle |
| 300×50 | Small banner |
| 160×600 | Wide skyscraper |
| 120×600 | Skyscraper |
A size outside this list rejects with error.code === "invalidSize".
Rendering into your own element
banner.requestBanner({ id, width, height }) renders a banner into an existing element:
<div id="sidebar-ad" style="width: 300px; height: 250px;"></div>
await QSPlaySDK.banner.requestBanner({ id: "sidebar-ad", width: 300, height: 250 });
The element must already exist in the DOM and be fully visible in the viewport — a banner scrolled
partly out of view, or hidden, doesn't count as shown and may reject with notVisible.
The creative refreshes itself on its own on the portal's own schedule — there is nothing to call
periodically to keep it current. Call requestBanner() again with the same id only when you
actually need to change something about that slot (for example a new width/height), subject to
the refresh limits below.
Responsive sizing
banner.requestResponsiveBanner(id) picks the widest size from the list above that fits the
element's current width, instead of a fixed one:
await QSPlaySDK.banner.requestResponsiveBanner("sidebar-ad");
Rejects with invalidSize if the element is narrower than even the smallest size (320px).
Overlaying a canvas
For engines that render everything to a single <canvas> (Unity, Godot, Construct, GameMaker, …)
with no HTML element to put a banner in: banner.requestOverlayBanner() creates and positions the
banner for you, anchored to the canvas.
await QSPlaySDK.banner.requestOverlayBanner({
id: "menu-bottom-ad",
width: 320,
height: 50,
anchor: "bottom-center",
offsetY: 12,
});
| Option | Description |
|---|---|
id | An id of your choosing — pass the same one again to change it, or to clear it. |
width, height | One of the banner sizes. |
anchor | One of nine points: top-left, top-center, top-right, middle-left, middle-center, middle-right, bottom-left, bottom-center, bottom-right. |
offsetX, offsetY | Distance in CSS pixels from the matching edge(s), default 0. |
The SDK keeps the overlay aligned to the canvas as it resizes or the game enters/exits fullscreen — there is nothing to reposition manually.
Placement and refresh limits
The rules below are about calling requestBanner()/requestResponsiveBanner()/
requestOverlayBanner() again for a slot that's already showing something — not about the
creative's own automatic refresh, which isn't affected by them. Enforced by the portal, independent
of what your game requests:
| Rule | Limit |
|---|---|
Calling requestBanner() etc. again for the same slot | No more than every 30 seconds |
| Such calls per size, per session | Up to 120 |
| Identical-size banners shown at once | Up to 2 |
Banners while a video ad (ad.requestAd()) is showing | Never |
Clearing banners
await QSPlaySDK.banner.clearBanner("sidebar-ad"); // one banner
await QSPlaySDK.banner.clearAllBanners(); // every banner the SDK rendered
Error codes
All banner.* methods reject with an SdkError (see Error handling):
| Code | When |
|---|---|
invalidSize | width/height isn't one of the whitelisted sizes. |
notCreated | No element with the given id exists in the DOM. |
notVisible | The container isn't fully visible in the viewport. |
unfilled | No ad was available for this slot. |
cooldown | The refresh limit hasn't been reached yet. |
maxReached | A per-session or per-size limit was reached. |
videoAdPlaying | A video ad (ad.requestAd()) is currently showing. |
adsDisabled | Ads are off for this session. |
other | No render result 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. |
Testing without ads
In mock mode, every banner.* call renders a plain gray placeholder box of
the requested size instead of a real ad — enough to verify your layout locally. Mock mode doesn't
simulate the automatic refresh described above; the placeholder is static until you clear or
re-request it.