Banners
Banners
SDK.banner places an ad inside an element that your page owns. Banners belong on screens that stay open for a while (menus, game-over and shop screens), never over the playfield. See the advertisement rules.
A container is any element with an id. It must be in the DOM, visible and at least partly on screen when you make the request.
requestBanner#
requestBanner(options: { id: string; width: number; height: number }): Promise<void>Places a banner of an exact size, centred inside the container. Allowed sizes:
Static sizes (width x height) |
|---|
| 728x90, 300x250, 320x50, 468x60, 320x100 |
<div id="menu-banner" style="width:300px;height:250px"></div>
<script>
SDK.banner.requestBanner({ id: "menu-banner", width: 300, height: 250 })
.catch((e) => console.warn("banner:", e.code, e.containerId));
</script>requestResponsiveBanner#
requestResponsiveBanner(id: string): Promise<void>Measures the container and picks the largest size from this list that fits inside it:
| Responsive sizes |
|---|
| 970x250, 970x90, 728x90, 468x60, 336x280, 300x600, 300x250, 250x250, 320x50, 160x600, 120x600 |
The banner is placed at the container's own position and size, so give the container explicit dimensions or a layout that resolves to a sensible box. If nothing fits you get noAvailableSizes.
await SDK.banner.requestResponsiveBanner("sidebar");Clearing#
clearBanner(id: string): Promise<void>
clearAllBanners(): Promise<void>Remove banners when the player leaves the screen they sit on. Clearing also resets that container's refresh timer.
function leaveMenu() {
SDK.banner.clearAllBanners();
startLevel();
}Limits#
- The same container can be requested again no sooner than 30 seconds after its previous request. Earlier calls reject with
bannerCooldown. - A session may refresh banners at most 60 times. After that,
maxRefreshReached. - While a video ad is on screen banner requests reject with
videoAdPlaying. Request the banner again afteradFinished.
Error codes#
All banner errors carry containerId.
| Code | Meaning |
|---|---|
bannersDisabled |
Reserved for contexts that refuse banners. When banners are off for a game (for example in basic launch) the portal currently answers the request without drawing anything, so a resolved call does not prove a banner is visible. |
unfilled |
Reserved for "no banner available". |
missingId |
id is empty or not a string. |
notCreated |
No element with that id exists. |
notVisible |
The element has no size, is hidden (display:none, visibility:hidden, opacity:0) or is outside the viewport. |
noAvailableSizes |
Responsive request: the container is smaller than every supported size. |
invalidSize |
Static request: the size is not in the static list. |
videoAdPlaying |
A video ad is playing. |
bannerCooldown |
Refresh interval below 30 seconds. |
maxRefreshReached |
Session refresh cap reached. |
other |
Anything else. |
Banners are never required for the game to work. On any error, keep the container empty or collapse it, and do not retry in a tight loop.
Local testing#
In local mode the banner is a dashed grey box labelled with its size and container id, appended to the container. Because it never fills or fails, test your error handling by temporarily hiding the container (notVisible) or passing a wrong size (invalidSize).