Advanced Banners

You are reading the documentation for Bridge SDK v2. If you need the obsolete v1 documentation, see Documentation (v1).

Advanced Banners let you define responsive banner layouts that adapt to device type, orientation, and screen size. Unlike regular banners, which support one top/bottom placement, Advanced Banners can render multiple banners at custom positions and switch layouts automatically when conditions change.

When to use Advanced Banners over regular Banner

You need banner placement other than top/bottom (corners, sides, multiple banners at once).
Layouts must differ between mobile and desktop, or portrait and landscape.
You want banner visibility to react to game lifecycle messages (e.g. show on level_paused, hide on level_resumed) without writing show/hide calls everywhere.

Configuration

Advanced Banner settings live in the config under the advertisement.advancedBanners key.

{
    "advertisement": {
        "advancedBanners": {
            "disable": false, // disable Advanced Banners entirely
            "placementFallback": "main_menu", // placement used when showAdvancedBanners() is called without one
            "main_menu": { // every other key defines a placement
                "action": "show", // 'show' (default) or 'hide' — what to do when the placement is triggered
                "default": [ // layout used when no condition key matches
                    { "width": "20%", "height": "25%", "top": "10%", "right": "10%" }
                ],
                "mobile:portrait": [ // condition key — layout for a specific environment
                    { "width": "100%", "height": "10%", "bottom": "0%", "left": "0%" }
                ],
                "desktop:landscape:w>1200": [ // several banner objects = several banners shown at once
                    { "width": "10%", "height": "60%", "top": "10%", "left": "2%" },
                    { "width": "10%", "height": "60%", "top": "10%", "right": "2%" }
                ]
            },
            "level_resumed": {
                "action": "hide"
            }
        }
    }
}

Every key except disable and placementFallback defines a placement. The placement name matches a built-in or custom platform message (level_paused, gameplay_started, shop_opened, …) or the string you pass to showAdvancedBanners(). Each banner object inside a layout positions the banner with width, height, top, bottom, left, right.

All sizes and positions must be specified as percentages (e.g. "20%", "0%"). Percentages keep banners responsive across every device and screen size. Do not use pixels or any other unit — only the % value is supported.

Condition keys

A condition key is a colon-separated list of segments; its layout is used only when all segments match the current environment:

Device type — mobile, desktop, tablet, tv
Orientation — portrait, landscape
Width / height — w>600, w<=1024, h>400, … (window size)
Aspect ratio — ar>1.5, ar>=1.78, … (width ÷ height)
canvas — evaluate the size and aspect-ratio segments against the game canvas instead of the window

Combine segments with :, e.g. desktop:landscape:w>1200. When several variants match, the most specific one wins: device type weighs the most, then orientation, then each size / aspect-ratio segment; ties go to the key with more segments, then to the threshold closest to the actual value. If no variant matches, default is used.

Is Advanced Banners Supported

Check this before showing banner-related UI.

if (bridge.advertisement.isAdvancedBannersSupported) {
    // Advanced Banners are available
}

Use Is Advanced Banners Supported to check availability before showing banner-related UI.

Copy This Example

{"is-c3-clipboard-data":true,"type":"events","items":[{"eventType":"block","conditions":[{"id":"is-advanced-banners-supported","objectClass":"PlaygamaBridge"}],"actions":[]}]}

Use Is Advanced Banners Supported to check availability before showing banner-related UI.

Copy This Example

{"000kind":"GDEVELOP_EventsAndInstructions_CLIPBOARD_KIND-jsBdHbLy912y8Rc","content":{"eventsList":[{"type":"BuiltinCommonInstructions::Standard","conditions":[{"type":{"value":"PlaygamaBridge::IsAdvancedBannersSupported"},"parameters":[""]}],"actions":[]}],"eventsCount":1,"actionsList":[],"actionsCount":0,"conditionsList":[],"conditionsCount":0}}

Platform support · 3 of 26 platforms

Supports: crazy_games, msn, playgama

Does not support: discord, dlightek, facebook, game_distribution, gamepush, gamesnacks, huawei, jio_games, lagged, microsoft_store, ok, playdeck, poki, portal, reddit, samsung, telegram, tiktok, vk, xiaomi, y8, yandex, youtube

Show Advanced Banners

Show banners for a placement configured in the config file. If placementFallback is set, the placement argument can be omitted.

// Show banners for a specific placement
bridge.advertisement.showAdvancedBanners('main_menu')

If placementFallback is set in the config, you can call without arguments:

bridge.advertisement.showAdvancedBanners()

// Show banners for a specific placement
Bridge.advertisement.ShowAdvancedBanners("main_menu");

If placementFallback is set in the config, you can call without arguments:

Bridge.advertisement.ShowAdvancedBanners();

Display Advanced Banners for a placement configured in playgama-bridge-config.json. Parameters:

Placement (optional)

Copy This Example

{"is-c3-clipboard-data":true,"type":"events","items":[{"eventType":"block","conditions":[],"actions":[{"id":"show-advanced-banners","objectClass":"PlaygamaBridge","parameters":{"placement":"\"main_menu\""}}]}]}

Display Advanced Banners for a placement configured in playgama-bridge-config.json. Parameters:

Placement (optional)

Copy This Example

{"000kind":"GDEVELOP_EventsAndInstructions_CLIPBOARD_KIND-jsBdHbLy912y8Rc","content":{"eventsList":[{"type":"BuiltinCommonInstructions::Standard","conditions":[],"actions":[{"type":{"value":"PlaygamaBridge::ShowAdvancedBanners"},"parameters":["","\"main_menu\""]}]}],"eventsCount":1,"actionsList":[],"actionsCount":0,"conditionsList":[],"conditionsCount":0}}

# Show banners for a specific placement
Bridge.advertisement.show_advanced_banners("main_menu")

If placementFallback is set in the config, you can call without arguments:

Bridge.advertisement.show_advanced_banners()

// Show banners for a specific placement
playgama_bridge_advertisement_show_advanced_banners("main_menu")

If placementFallback is set in the config, you can call with an empty string:

playgama_bridge_advertisement_show_advanced_banners("")

-- Show banners for a specific placement
bridge.advertisement.show_advanced_banners("main_menu")

If placementFallback is set in the config, you can call without arguments:

bridge.advertisement.show_advanced_banners()

// Show banners for a specific placement
bridge.advertisement.showAdvancedBanners('main_menu')

If placementFallback is set in the config, you can call without arguments:

bridge.advertisement.showAdvancedBanners()

Hide Advanced Banners

bridge.advertisement.hideAdvancedBanners()

Hide the currently displayed Advanced Banners.

Copy This Example

{"is-c3-clipboard-data":true,"type":"events","items":[{"eventType":"block","conditions":[],"actions":[{"id":"hide-advanced-banners","objectClass":"PlaygamaBridge"}]}]}

Hide the currently displayed Advanced Banners.

Copy This Example

{"000kind":"GDEVELOP_EventsAndInstructions_CLIPBOARD_KIND-jsBdHbLy912y8Rc","content":{"eventsList":[{"type":"BuiltinCommonInstructions::Standard","conditions":[],"actions":[{"type":{"value":"PlaygamaBridge::HideAdvancedBanners"},"parameters":[""]}]}],"eventsCount":1,"actionsList":[],"actionsCount":0,"conditionsList":[],"conditionsCount":0}}

Show / Hide via Platform Messages

Advanced Banners can react to platform messages. When you send a built-in or custom message, Bridge checks whether the config has a matching placement and runs that placement action.

// This will automatically show banners if "level_paused" placement is configured
bridge.platform.sendMessage('level_paused')

// This will hide banners if "level_resumed" has action: "hide"
bridge.platform.sendMessage('level_resumed')

// Custom messages work the same way
bridge.platform.sendCustomMessage('shop_opened')

// This will automatically show banners if "level_paused" placement is configured
Bridge.platform.SendMessage(PlatformMessage.LevelPaused);

// This will hide banners if "level_resumed" has action: "hide"
Bridge.platform.SendMessage(PlatformMessage.LevelResumed);

// Custom messages work the same way
Bridge.platform.SendCustomMessage("shop_opened");

Use Send Message or Send Custom Message to trigger placements configured in playgama-bridge-config.json.

This will automatically show banners if gameplay_stopped placement is configured:

Copy This Example

{"is-c3-clipboard-data":true,"type":"events","items":[{"eventType":"block","conditions":[],"actions":[{"id":"send-message","objectClass":"PlaygamaBridge","parameters":{"message":"gameplay-stopped"}}]}]}

This will hide banners if gameplay_started has action: "hide":

Copy This Example

{"is-c3-clipboard-data":true,"type":"events","items":[{"eventType":"block","conditions":[],"actions":[{"id":"send-message","objectClass":"PlaygamaBridge","parameters":{"message":"gameplay-started"}}]}]}

Custom messages work the same way:

Copy This Example

{"is-c3-clipboard-data":true,"type":"events","items":[{"eventType":"block","conditions":[],"actions":[{"id":"send-custom-message","objectClass":"PlaygamaBridge","parameters":{"id":"\"shop_opened\""}}]}]}

Use Send Message or Send Custom Message to trigger placements configured in playgama-bridge-config.json.

This will automatically show banners if gameplay_stopped placement is configured:

Copy This Example

{"000kind":"GDEVELOP_EventsAndInstructions_CLIPBOARD_KIND-jsBdHbLy912y8Rc","content":{"eventsList":[{"type":"BuiltinCommonInstructions::Standard","conditions":[],"actions":[{"type":{"value":"PlaygamaBridge::SendMessage"},"parameters":["","\"GAMEPLAY_STOPPED\""]}]}],"eventsCount":1,"actionsList":[],"actionsCount":0,"conditionsList":[],"conditionsCount":0}}

This will hide banners if gameplay_started has action: "hide":

Copy This Example

{"000kind":"GDEVELOP_EventsAndInstructions_CLIPBOARD_KIND-jsBdHbLy912y8Rc","content":{"eventsList":[{"type":"BuiltinCommonInstructions::Standard","conditions":[],"actions":[{"type":{"value":"PlaygamaBridge::SendMessage"},"parameters":["","\"GAMEPLAY_STARTED\""]}]}],"eventsCount":1,"actionsList":[],"actionsCount":0,"conditionsList":[],"conditionsCount":0}}

Custom messages work the same way:

Copy This Example

{"000kind":"GDEVELOP_EventsAndInstructions_CLIPBOARD_KIND-jsBdHbLy912y8Rc","content":{"eventsList":[{"type":"BuiltinCommonInstructions::Standard","conditions":[],"actions":[{"type":{"value":"PlaygamaBridge::SendCustomMessage"},"parameters":["","\"shop_opened\""]}]}],"eventsCount":1,"actionsList":[],"actionsCount":0,"conditionsList":[],"conditionsCount":0}}

# This will automatically show banners if "level_paused" placement is configured
Bridge.platform.send_message(Bridge.PlatformMessage.LEVEL_PAUSED)

# This will hide banners if "level_resumed" has action: "hide"
Bridge.platform.send_message(Bridge.PlatformMessage.LEVEL_RESUMED)

# Custom messages work the same way
Bridge.platform.send_custom_message("shop_opened")

// This will automatically show banners if "level_paused" placement is configured
playgama_bridge_platform_send_message("level_paused", "")

// This will hide banners if "level_resumed" has action: "hide"
playgama_bridge_platform_send_message("level_resumed", "")

// Custom messages work the same way
playgama_bridge_platform_send_custom_message("shop_opened", "")

-- This will automatically show banners if "level_paused" placement is configured
bridge.platform.send_message(bridge.PLATFORM_MESSAGE.LEVEL_PAUSED)

-- This will hide banners if "level_resumed" has action: "hide"
bridge.platform.send_message(bridge.PLATFORM_MESSAGE.LEVEL_RESUMED)

-- Custom messages work the same way
bridge.platform.send_custom_message("shop_opened")

import { PLATFORM_MESSAGE } from '../../extensions/playgama-bridge/playgama-bridge'

// This will automatically show banners if "level_paused" placement is configured
bridge.platform.sendMessage(PLATFORM_MESSAGE.LEVEL_PAUSED)

// This will hide banners if "level_resumed" has action: "hide"
bridge.platform.sendMessage(PLATFORM_MESSAGE.LEVEL_RESUMED)

// Custom messages work the same way
bridge.platform.sendCustomMessage('shop_opened')

This is the recommended approach because banner visibility follows your game lifecycle without extra show/hide calls.

Advanced Banners State

Possible values: loading, shown, hidden, failed.

// Check current state
const state = bridge.advertisement.advancedBannersState

// Listen for state changes
bridge.advertisement.on('advanced_banners_state_changed', (state) => {
    switch (state) {
        case 'loading':
            // Banners are being loaded
            break
        case 'shown':
            // Banners are visible
            break
        case 'hidden':
            // Banners were hidden
            break
        case 'failed':
            // Banners failed to load
            break
    }
})

// Check current state
BannerState state = Bridge.advertisement.advancedBannersState;
// Possible values: BannerState.Loading, BannerState.Shown, BannerState.Hidden, BannerState.Failed

// Listen for state changes
Bridge.advertisement.advancedBannersStateChanged += OnAdvancedBannersStateChanged;

private void OnAdvancedBannersStateChanged(BannerState state)
{
    switch (state)
    {
        case BannerState.Loading:
            // Banners are being loaded
            break;
        case BannerState.Shown:
            // Banners are visible
            break;
        case BannerState.Hidden:
            // Banners were hidden
            break;
        case BannerState.Failed:
            // Banners failed to load
            break;
    }
}

Unsubscribe when the listener is no longer needed:

Bridge.advertisement.advancedBannersStateChanged -= OnAdvancedBannersStateChanged;

Use these conditions to react to specific state transitions. Each fires once per transition.

On Advanced Banners State Changed

Fires whenever the state changes to any value.

Copy This Example

{"is-c3-clipboard-data":true,"type":"events","items":[{"eventType":"block","conditions":[{"id":"on-advanced-banners-state-changed","objectClass":"PlaygamaBridge"}],"actions":[]}]}

On Advanced Banners Loading

Copy This Example

{"is-c3-clipboard-data":true,"type":"events","items":[{"eventType":"block","conditions":[{"id":"on-advanced-banners-loading","objectClass":"PlaygamaBridge"}],"actions":[]}]}

On Advanced Banners Shown

Copy This Example

{"is-c3-clipboard-data":true,"type":"events","items":[{"eventType":"block","conditions":[{"id":"on-advanced-banners-shown","objectClass":"PlaygamaBridge"}],"actions":[]}]}

On Advanced Banners Hidden

Copy This Example

{"is-c3-clipboard-data":true,"type":"events","items":[{"eventType":"block","conditions":[{"id":"on-advanced-banners-hidden","objectClass":"PlaygamaBridge"}],"actions":[]}]}

On Advanced Banners Failed

Copy This Example

{"is-c3-clipboard-data":true,"type":"events","items":[{"eventType":"block","conditions":[{"id":"on-advanced-banners-failed","objectClass":"PlaygamaBridge"}],"actions":[]}]}

Use these conditions to react to specific state transitions. Each fires once per transition.

On Advanced Banners State Changed

Fires whenever the state changes to any value.

Copy This Example

{"000kind":"GDEVELOP_EventsAndInstructions_CLIPBOARD_KIND-jsBdHbLy912y8Rc","content":{"eventsList":[{"type":"BuiltinCommonInstructions::Standard","conditions":[{"type":{"value":"PlaygamaBridge::OnAdvancedBannersStateChanged"},"parameters":[""]}],"actions":[]}],"eventsCount":1,"actionsList":[],"actionsCount":0,"conditionsList":[],"conditionsCount":0}}

On Advanced Banners Loading

Copy This Example

{"000kind":"GDEVELOP_EventsAndInstructions_CLIPBOARD_KIND-jsBdHbLy912y8Rc","content":{"eventsList":[{"type":"BuiltinCommonInstructions::Standard","conditions":[{"type":{"value":"PlaygamaBridge::OnAdvancedBannersLoading"},"parameters":[""]}],"actions":[]}],"eventsCount":1,"actionsList":[],"actionsCount":0,"conditionsList":[],"conditionsCount":0}}

On Advanced Banners Shown

Copy This Example

{"000kind":"GDEVELOP_EventsAndInstructions_CLIPBOARD_KIND-jsBdHbLy912y8Rc","content":{"eventsList":[{"type":"BuiltinCommonInstructions::Standard","conditions":[{"type":{"value":"PlaygamaBridge::OnAdvancedBannersShown"},"parameters":[""]}],"actions":[]}],"eventsCount":1,"actionsList":[],"actionsCount":0,"conditionsList":[],"conditionsCount":0}}

On Advanced Banners Hidden

Copy This Example

{"000kind":"GDEVELOP_EventsAndInstructions_CLIPBOARD_KIND-jsBdHbLy912y8Rc","content":{"eventsList":[{"type":"BuiltinCommonInstructions::Standard","conditions":[{"type":{"value":"PlaygamaBridge::OnAdvancedBannersHidden"},"parameters":[""]}],"actions":[]}],"eventsCount":1,"actionsList":[],"actionsCount":0,"conditionsList":[],"conditionsCount":0}}

On Advanced Banners Failed

Copy This Example

{"000kind":"GDEVELOP_EventsAndInstructions_CLIPBOARD_KIND-jsBdHbLy912y8Rc","content":{"eventsList":[{"type":"BuiltinCommonInstructions::Standard","conditions":[{"type":{"value":"PlaygamaBridge::OnAdvancedBannersFailed"},"parameters":[""]}],"actions":[]}],"eventsCount":1,"actionsList":[],"actionsCount":0,"conditionsList":[],"conditionsCount":0}}

# Check current state
var state = Bridge.advertisement.advanced_banners_state

# To track state changes, connect to the signal
func _ready():
    Bridge.advertisement.connect("advanced_banners_state_changed", self, "_on_advanced_banners_state_changed")

func _on_advanced_banners_state_changed(state):
    match state:
        "loading":
            # Banners are being loaded
            pass
        "shown":
            # Banners are visible
            pass
        "hidden":
            # Banners were hidden
            pass
        "failed":
            # Banners failed to load
            pass

# To track state changes, connect to the signal
func _ready():
    Bridge.advertisement.connect("advanced_banners_state_changed", Callable(self, "_on_advanced_banners_state_changed"))

func _on_advanced_banners_state_changed(state):
    match state:
        "loading":
            # Banners are being loaded
            pass
        "shown":
            # Banners are visible
            pass
        "hidden":
            # Banners were hidden
            pass
        "failed":
            # Banners failed to load
            pass

// Check current state
var _state = playgama_bridge_advertisement_advanced_banners_state()

To listen for state changes, handle the Async Social event (Other_70.gml):

if (async_load[? "type"] == "playgama_bridge_advertisement_advanced_banners_state_changed") {
    switch (async_load[? "data"]) {
        case "loading":
            // Banners are being loaded
            break
        case "shown":
            // Banners are visible
            break
        case "hidden":
            // Banners were hidden
            break
        case "failed":
            // Banners failed to load
            break
    }
}

-- Check current state
local state = bridge.advertisement.advanced_banners_state()

-- Listen for state changes
bridge.advertisement.on("advanced_banners_state_changed", function(self, state)
    if state == "loading" then
        -- Banners are being loaded
    elseif state == "shown" then
        -- Banners are visible
    elseif state == "hidden" then
        -- Banners were hidden
    elseif state == "failed" then
        -- Banners failed to load
    end
end)

import { EVENT_NAME, BANNER_STATE } from '../../extensions/playgama-bridge/playgama-bridge'

// Check current state
const state = bridge.advertisement.advancedBannersState

// Listen for state changes
bridge.advertisement.on(EVENT_NAME.ADVANCED_BANNERS_STATE_CHANGED, (state: BANNER_STATE) => {
    switch (state) {
        case BANNER_STATE.LOADING:
            // Banners are being loaded
            break
        case BANNER_STATE.SHOWN:
            // Banners are visible
            break
        case BANNER_STATE.HIDDEN:
            // Banners were hidden
            break
        case BANNER_STATE.FAILED:
            // Banners failed to load
            break
    }
})

Automatic Behavior

Fullscreen ad coordination — Advanced Banners are hidden automatically when an interstitial or rewarded ad starts (loading or opened) and restored when it finishes (closed or failed). No extra code is needed.
Responsive re-evaluation — when the screen orientation changes or the window is resized, Bridge re-evaluates condition keys and switches to the best-matching layout variant (with a 200 ms debounce).

PreviousBanner NextAdBlock

Last updated 11 days ago