Skip to main content

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.

Every width/height must be one of:

Size
970×90Large leaderboard
728×90Leaderboard
320×50Mobile banner
300×600Half page
300×300Square
300×250Medium rectangle
300×100Small rectangle
300×50Small banner
160×600Wide skyscraper
120×600Skyscraper

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,
});
OptionDescription
idAn id of your choosing — pass the same one again to change it, or to clear it.
width, heightOne of the banner sizes.
anchorOne of nine points: top-left, top-center, top-right, middle-left, middle-center, middle-right, bottom-left, bottom-center, bottom-right.
offsetX, offsetYDistance 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:

RuleLimit
Calling requestBanner() etc. again for the same slotNo more than every 30 seconds
Such calls per size, per sessionUp to 120
Identical-size banners shown at onceUp to 2
Banners while a video ad (ad.requestAd()) is showingNever

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):

CodeWhen
invalidSizewidth/height isn't one of the whitelisted sizes.
notCreatedNo element with the given id exists in the DOM.
notVisibleThe container isn't fully visible in the viewport.
unfilledNo ad was available for this slot.
cooldownThe refresh limit hasn't been reached yet.
maxReachedA per-session or per-size limit was reached.
videoAdPlayingA video ad (ad.requestAd()) is currently showing.
adsDisabledAds are off for this session.
otherNo 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.