Advanced Banners

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.

Automatic behavior

Fullscreen ad coordination — Advanced Banners are auto-hidden when an interstitial or rewarded opens, and restored when it closes/fails.
Responsive re-evaluation — on orientation change or window resize, Bridge re-evaluates condition keys and switches to the best-matching variant (200ms debounce).

Advanced Banner settings are stored in playgama-bridge-config.json. Use the config editor to create or update them.

Checking Support

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 28 platforms

Supports: crazy_games, msn, playgama

Does not support: absolute_games, bitquest, 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

Usage

Method 1: Explicit API Call

Show and hide Advanced Banners directly from game code when placement timing is controlled by your own UI flow.

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

// 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}}

Method 2: Automatic 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.

Tracking 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 automatically hidden when an interstitial or rewarded ad starts (loading or opened) and automatically restored when the ad finishes (closed or failed). No extra code is needed.

Interstitial starts → Advanced Banners hidden
Interstitial ends   → Advanced Banners restored

Rewarded starts     → Advanced Banners hidden
Rewarded ends       → Advanced Banners restored

Responsive Re-evaluation

When the screen orientation changes or the window is resized, Bridge re-evaluates conditions and switches to a better-matching variant if one exists. This uses a 200ms debounce to avoid excessive updates.

For example, if the player rotates a phone from portrait to landscape and your config has layouts for both orientations, Bridge switches banners automatically.

Complete Example

Config

{
    "advertisement": {
        "advancedBanners": {
            "placementFallback": "gameplay_stopped",
            "gameplay_started": {
                "action": "hide"
            },
            "gameplay_stopped": {
                "action": "show",
                "default": [
                    { "width": "20%", "height": "25%", "bottom": "10%", "right": "5%" }
                ],
                "mobile:portrait": [
                    { "width": "100%", "height": "8%", "bottom": "0", "left": "0" }
                ],
                "mobile:landscape": [
                    { "width": "25%", "height": "40%", "top": "30%", "right": "0" }
                ],
                "desktop:w>1200": [
                    { "width": "10%", "height": "60%", "top": "10%", "left": "1%" },
                    { "width": "10%", "height": "60%", "top": "10%", "right": "1%" }
                ],
                "desktop:w<=1200": [
                    { "width": "60%", "height": "10%", "bottom": "0", "left": "20%" }
                ],
                "desktop:landscape:ar>=1.78": [
                    { "width": "12%", "height": "70%", "top": "5%", "left": "0" },
                    { "width": "12%", "height": "70%", "top": "5%", "right": "0" },
                    { "width": "50%", "height": "10%", "bottom": "0", "left": "25%" }
                ]
            },
            "<your_placement_here>": {
                "default": [
                    { "width": "60%", "height": "10%", "bottom": "0", "left": "20%" }
                ]
            },
            "<your_placement_here>": {
                "action": "hide"
            }
        }
    }
}

Game Code

// Game lifecycle messages automatically trigger banners
bridge.platform.sendMessage('gameplay_started')   // hides banners
bridge.platform.sendMessage('gameplay_stopped')   // shows banners (best layout auto-selected)

// Custom messages for game-specific screens
bridge.platform.sendCustomMessage('your_placement_here')  // shows shop banners
bridge.platform.sendCustomMessage('your_placement_here')  // hides banners

// Or call directly
bridge.advertisement.showAdvancedBanners('gameplay_stopped')
bridge.advertisement.hideAdvancedBanners()

using Playgama;
using Playgama.Modules.Advertisement;
using Playgama.Modules.Platform;

public class AdManager : MonoBehaviour
{
    private void Start()
    {
        Bridge.advertisement.advancedBannersStateChanged += OnAdvancedBannersStateChanged;
    }

    public void OnGameplayStarted()
    {
        // Hides banners automatically via config
        Bridge.platform.SendMessage(PlatformMessage.GameplayStarted);
    }

    public void OnGameplayStopped()
    {
        // Shows banners automatically (best layout auto-selected)
        Bridge.platform.SendMessage(PlatformMessage.GameplayStopped);
    }

    public void OnShopOpened()
    {
        // Custom messages work the same way
        Bridge.platform.SendCustomMessage("your_placement_here");
    }

    public void OnShopClosed()
    {
        Bridge.platform.SendCustomMessage("your_placement_here");
    }

    public void ShowBannersDirectly()
    {
        // Or call directly
        Bridge.advertisement.ShowAdvancedBanners("gameplay_stopped");
    }

    public void HideBannersDirectly()
    {
        Bridge.advertisement.HideAdvancedBanners();
    }

    private void OnAdvancedBannersStateChanged(BannerState state)
    {
        Debug.Log($"Advanced Banners: {state}");
    }

    private void OnDestroy()
    {
        Bridge.advertisement.advancedBannersStateChanged -= OnAdvancedBannersStateChanged;
    }
}

func _ready():
    Bridge.advertisement.connect("advanced_banners_state_changed", self, "_on_advanced_banners_state_changed")

    # Game lifecycle messages automatically trigger banners
    Bridge.platform.send_message(Bridge.PlatformMessage.GAME_READY)

func on_gameplay_started():
    Bridge.platform.send_message(Bridge.PlatformMessage.GAMEPLAY_STARTED)  # hides banners

func on_gameplay_stopped():
    Bridge.platform.send_message(Bridge.PlatformMessage.GAMEPLAY_STOPPED)  # shows banners

func on_shop_opened():
    Bridge.platform.send_custom_message("your_placement_here")  # shows banners

func on_shop_closed():
    Bridge.platform.send_custom_message("your_placement_here")  # hides banners

func show_banners_directly():
    Bridge.advertisement.show_advanced_banners("gameplay_stopped")

func hide_banners_directly():
    Bridge.advertisement.hide_advanced_banners()

func _on_advanced_banners_state_changed(state):
    print("Advanced Banners: ", state)

func _ready():
    Bridge.advertisement.connect("advanced_banners_state_changed", Callable(self, "_on_advanced_banners_state_changed"))

    # Game lifecycle messages automatically trigger banners
    Bridge.platform.send_message(Bridge.PlatformMessage.GAME_READY)

func on_gameplay_started():
    Bridge.platform.send_message(Bridge.PlatformMessage.GAMEPLAY_STARTED)  # hides banners

func on_gameplay_stopped():
    Bridge.platform.send_message(Bridge.PlatformMessage.GAMEPLAY_STOPPED)  # shows banners

func on_shop_opened():
    Bridge.platform.send_custom_message("your_placement_here")  # shows banners

func on_shop_closed():
    Bridge.platform.send_custom_message("your_placement_here")  # hides banners

func show_banners_directly():
    Bridge.advertisement.show_advanced_banners("gameplay_stopped")

func hide_banners_directly():
    Bridge.advertisement.hide_advanced_banners()

func _on_advanced_banners_state_changed(state):
    print("Advanced Banners: ", state)

Create Event (Create_0.gml):

playgama_bridge_platform_send_message("game_ready", "")

Game Logic (e.g. in a Step or button handler):

// Game lifecycle messages automatically trigger banners
playgama_bridge_platform_send_message("gameplay_started", "")   // hides banners
playgama_bridge_platform_send_message("gameplay_stopped", "")   // shows banners (best layout auto-selected)

// Custom messages for game-specific screens
playgama_bridge_platform_send_custom_message("your_placement_here", "")  // shows banners
playgama_bridge_platform_send_custom_message("your_placement_here", "")  // hides banners

// Or call directly
playgama_bridge_advertisement_show_advanced_banners("gameplay_stopped")
playgama_bridge_advertisement_hide_advanced_banners()

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
    }
}

local bridge = require("bridge.bridge")

function init(self)
    -- Listen for state changes
    bridge.advertisement.on("advanced_banners_state_changed", function(self, state)
        print("Advanced Banners: " .. state)
    end)

    -- Game ready
    bridge.platform.send_message(bridge.PLATFORM_MESSAGE.GAME_READY)
end

function on_gameplay_started(self)
    -- Hides banners automatically via config
    bridge.platform.send_message(bridge.PLATFORM_MESSAGE.GAMEPLAY_STARTED)
end

function on_gameplay_stopped(self)
    -- Shows banners automatically (best layout auto-selected)
    bridge.platform.send_message(bridge.PLATFORM_MESSAGE.GAMEPLAY_STOPPED)
end

function on_shop_opened(self)
    -- Custom messages work the same way
    bridge.platform.send_custom_message("your_placement_here")
end

function on_shop_closed(self)
    bridge.platform.send_custom_message("your_placement_here")
end

function show_banners_directly(self)
    -- Or call directly
    bridge.advertisement.show_advanced_banners("gameplay_stopped")
end

function hide_banners_directly(self)
    bridge.advertisement.hide_advanced_banners()
end

import { _decorator, Component } from 'cc'
import {
    PLATFORM_MESSAGE, EVENT_NAME, BANNER_STATE,
} from '../../extensions/playgama-bridge/playgama-bridge'

const { ccclass } = _decorator

@ccclass('AdManager')
export class AdManager extends Component {

    start() {
        bridge.advertisement.on(
            EVENT_NAME.ADVANCED_BANNERS_STATE_CHANGED,
            this.onAdvancedBannersStateChanged.bind(this),
        )
    }

    onGameplayStarted() {
        // Hides banners automatically via config
        bridge.platform.sendMessage(PLATFORM_MESSAGE.GAMEPLAY_STARTED)
    }

    onGameplayStopped() {
        // Shows banners automatically (best layout auto-selected)
        bridge.platform.sendMessage(PLATFORM_MESSAGE.GAMEPLAY_STOPPED)
    }

    onShopOpened() {
        // Custom messages work the same way
        bridge.platform.sendCustomMessage('your_placement_here')
    }

    onShopClosed() {
        bridge.platform.sendCustomMessage('your_placement_here')
    }

    showBannersDirectly() {
        // Or call directly
        bridge.advertisement.showAdvancedBanners('gameplay_stopped')
    }

    hideBannersDirectly() {
        bridge.advertisement.hideAdvancedBanners()
    }

    private onAdvancedBannersStateChanged(state: BANNER_STATE) {
        console.log('Advanced Banners:', state)
    }
}

Configuration

Use the config editor to configure Advanced Banners in playgama-bridge-config.json under advertisement.advancedBanners.

{
    "advertisement": {
        "advancedBanners": {
            "disable": false,
            "placementFallback": "main_menu",
            "main_menu": {
                "default": [
                    { "width": "20%", "height": "25%", "top": "10%", "right": "10%" }
                ]
            },
            "level_paused": {
                "action": "show",
                "default": [
                    { "width": "20%", "height": "25%", "top": "10%", "right": "10%" }
                ],
                "mobile:portrait": [
                    { "width": "100%", "height": "10%", "bottom": "0", "left": "0" }
                ],
                "desktop:landscape:w>1200": [
                    { "width": "10%", "height": "60%", "top": "10%", "left": "2%" },
                    { "width": "10%", "height": "60%", "top": "10%", "right": "2%" }
                ]
            },
            "level_resumed": {
                "action": "hide"
            }
        }
    }
}

General Options

Parameter

Type

Default

Description

disable

boolean

false

Disable Advanced Banners entirely, even if the platform supports them

placementFallback

string

—

Default placement to use when Show Advanced Banners is called without a placement

Placement Configuration

Each key under advancedBanners except disable and placementFallback defines a placement. A placement is identified by a string that matches either:

A built-in or custom platform message, such as game_ready, level_paused, or gameplay_started
A custom message ID passed to Send Custom Message
A string passed directly to Show Advanced Banners

Each placement contains:

Property

Type

Default

Description

action

"show" | "hide"

"show"

Whether to show or hide banners when this placement is triggered

default

array

—

Fallback banner layout when no condition-based variant matches

condition key

array

—

Banner layout for a specific set of conditions (see Condition Keys below)

Banner Object

Each banner in the array is an object with CSS positioning values:

Property

Type

Description

width

string

CSS width (e.g. "300px", "100%")

height

string

CSS height (e.g. "250px", "80px")

top

string

CSS top offset (e.g. "0", "10%")

bottom

string

CSS bottom offset

left

string

CSS left offset

right

string

CSS right offset

You can define multiple banners per variant to show several ads simultaneously:

"desktop:landscape": [
    { "width": "10%", "height": "60%", "top": "10%", "left": "2%" },
    { "width": "10%", "height": "60%", "top": "10%", "right": "2%" },
    { "width": "40%", "height": "10%", "bottom": "0", "left": "30%" }
]

Condition Keys

Condition keys are colon-separated segments that describe when a variant should be used. Bridge evaluates all keys against the current environment and picks the best match.

Available Segments

Segment

Example

Description

Device type

mobile, desktop, tablet, tv

Matches the current device type

Orientation

portrait, landscape

Matches the current screen orientation

Width condition

w>600, w<=1024, w>=768

Matches against window width (or canvas width if canvas segment is present)

Height condition

h>400, h<=900

Matches against window height (or canvas height)

Aspect ratio

ar>1.5, ar>=1.78, ar<=1.0

Matches screen width/height ratio

Canvas mode

canvas

Use game canvas dimensions instead of window size for all w/h/ar conditions. If no canvas is found, the variant will not match

Combining Segments

Combine segments with : to create compound conditions. All segments must match for the variant to be selected:

{
    "mobile:portrait": [...],
    "mobile:portrait:w>400": [...],
    "desktop:landscape:w>1200:ar>=1.5": [...],
    "tablet:canvas:w>800": [...]
}

Priority Scoring

When multiple variants match, the one with the highest score wins:

Segment Type

Score

Device type (mobile, desktop, etc.)

Orientation (portrait, landscape)

Canvas mode (canvas)

Each dimension/aspect ratio condition

If two variants have the same score, the one with more segments wins. If they also have the same number of segments, the one whose dimension/aspect ratio threshold is closest to the actual value takes priority.

Example: screen is 1300px wide, device is desktop

Key

Matches?

Score

default

yes (fallback)

-1

desktop

yes

desktop:w>500

yes

4 + 1 = 5

desktop:w>1200

yes

5 + higher specificity bonus

desktop:landscape:w>1200

yes

4 + 2 + 1 = 7

mobile:portrait

—

PreviousBanner NextAdBlock

Last updated 3 days ago

hashtagWhen to use Advanced Banners over regular Banner

hashtagAutomatic behavior

hashtagChecking Support

hashtagUsage

hashtagMethod 1: Explicit API Call

hashtagMethod 2: Automatic via Platform Messages

hashtagTracking State

hashtagAutomatic Behavior

hashtagFullscreen Ad Coordination

hashtagResponsive Re-evaluation

hashtagComplete Example

hashtagConfig

hashtagGame Code

hashtagConfiguration

hashtagGeneral Options

hashtagPlacement Configuration

hashtagBanner Object

hashtagCondition Keys

hashtagAvailable Segments

hashtagCombining Segments

hashtagPriority Scoring

When to use Advanced Banners over regular Banner

Automatic behavior

Checking Support

Usage

Method 1: Explicit API Call

Method 2: Automatic via Platform Messages

Tracking State

Automatic Behavior

Fullscreen Ad Coordination

Responsive Re-evaluation

Complete Example

Config

Game Code

Configuration

General Options

Placement Configuration

Banner Object

Condition Keys

Available Segments

Combining Segments

Priority Scoring