# Advanced Banners Advanced Banners let you define responsive banner layouts that adapt to device type, orientation, and screen size. Unlike [regular banners](/playgama/sdk/api/advertisement/banner.md), 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). {% hint style="info" %} Advanced Banner settings are stored in `playgama-bridge-config.json`. Use the [config editor](https://playgama.github.io/bridge-config-editor/) to create or update them. {% endhint %} #### Checking Support {% tabs %} {% tab title="Plain JS" %} ```javascript if (bridge.advertisement.isAdvancedBannersSupported) { // Advanced Banners are available } ``` {% endtab %} {% tab title="Unity" %} ```csharp if (Bridge.advertisement.isAdvancedBannersSupported) { // Advanced Banners are available } ``` {% endtab %} {% tab title="Construct 3" %} 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":[]}]} ```
{% endtab %} {% tab title="GDevelop" %} 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}} ```
{% endtab %} {% tab title="Godot" %} ```gdscript if Bridge.advertisement.is_advanced_banners_supported: # Advanced Banners are available pass ``` {% endtab %} {% tab title="GameMaker" %} ```javascript var _supported = playgama_bridge_advertisement_is_advanced_banners_supported() if (_supported) { // Advanced Banners are available } ``` {% endtab %} {% tab title="Defold" %} ```lua if bridge.advertisement.is_advanced_banners_supported() then -- Advanced Banners are available end ``` {% endtab %} {% tab title="Cocos Creator" %} ```typescript if (bridge.advertisement.isAdvancedBannersSupported) { // Advanced Banners are available } ``` {% endtab %} {% endtabs %} ### 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** {% tabs %} {% tab title="Plain JS" %} ```javascript // Show banners for a specific placement bridge.advertisement.showAdvancedBanners('main_menu') ``` If `placementFallback` is set in the config, you can call without arguments: ```javascript bridge.advertisement.showAdvancedBanners() ``` {% endtab %} {% tab title="Unity" %} ```csharp // Show banners for a specific placement Bridge.advertisement.ShowAdvancedBanners("main_menu"); ``` If `placementFallback` is set in the config, you can call without arguments: ```csharp Bridge.advertisement.ShowAdvancedBanners(); ``` {% endtab %} {% tab title="Construct 3" %} 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\""}}]}]} ```
{% endtab %} {% tab title="GDevelop" %} 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}} ```
{% endtab %} {% tab title="Godot" %} ```gdscript # 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: ```gdscript Bridge.advertisement.show_advanced_banners() ``` {% endtab %} {% tab title="GameMaker" %} ```javascript // 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: ```javascript playgama_bridge_advertisement_show_advanced_banners("") ``` {% endtab %} {% tab title="Defold" %} ```lua -- 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: ```lua bridge.advertisement.show_advanced_banners() ``` {% endtab %} {% tab title="Cocos Creator" %} ```typescript // Show banners for a specific placement bridge.advertisement.showAdvancedBanners('main_menu') ``` If `placementFallback` is set in the config, you can call without arguments: ```typescript bridge.advertisement.showAdvancedBanners() ``` {% endtab %} {% endtabs %} **Hide Advanced Banners** {% tabs %} {% tab title="Plain JS" %} ```javascript bridge.advertisement.hideAdvancedBanners() ``` {% endtab %} {% tab title="Unity" %} ```csharp Bridge.advertisement.HideAdvancedBanners(); ``` {% endtab %} {% tab title="Construct 3" %} 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"}]}]} ```
{% endtab %} {% tab title="GDevelop" %} 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}} ```
{% endtab %} {% tab title="Godot" %} ```gdscript Bridge.advertisement.hide_advanced_banners() ``` {% endtab %} {% tab title="GameMaker" %} ```javascript playgama_bridge_advertisement_hide_advanced_banners() ``` {% endtab %} {% tab title="Defold" %} ```lua bridge.advertisement.hide_advanced_banners() ``` {% endtab %} {% tab title="Cocos Creator" %} ```typescript bridge.advertisement.hideAdvancedBanners() ``` {% endtab %} {% endtabs %} #### 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. {% tabs %} {% tab title="Plain JS" %} ```javascript // 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') ``` {% endtab %} {% tab title="Unity" %} ```csharp // 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"); ``` {% endtab %} {% tab title="Construct 3" %} 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\""}}]}]} ```
{% endtab %} {% tab title="GDevelop" %} 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}} ```
{% endtab %} {% tab title="Godot" %} ```gdscript # 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") ``` {% endtab %} {% tab title="GameMaker" %} ```javascript // 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", "") ``` {% endtab %} {% tab title="Defold" %} ```lua -- 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") ``` {% endtab %} {% tab title="Cocos Creator" %} ```typescript 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') ``` {% endtab %} {% endtabs %} 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`. {% tabs %} {% tab title="Plain JS" %} ```javascript // 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 } }) ``` {% endtab %} {% tab title="Unity" %} ```csharp // 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: ```csharp Bridge.advertisement.advancedBannersStateChanged -= OnAdvancedBannersStateChanged; ``` {% endtab %} {% tab title="Construct 3" %} 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":[]}]} ```
{% endtab %} {% tab title="GDevelop" %} 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}} ```
{% endtab %} {% tab title="Godot" %} ```gdscript # Check current state var state = Bridge.advertisement.advanced_banners_state ``` {% tabs %} {% tab title="Godot 3.x" %} ```gdscript # 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 ``` {% endtab %} {% tab title="Godot 4.x" %} ```gdscript # 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 ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="GameMaker" %} ```javascript // Check current state var _state = playgama_bridge_advertisement_advanced_banners_state() ``` To listen for state changes, handle the Async Social event (`Other_70.gml`): ```javascript 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 } } ``` {% endtab %} {% tab title="Defold" %} ```lua -- 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) ``` {% endtab %} {% tab title="Cocos Creator" %} ```typescript 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 } }) ``` {% endtab %} {% endtabs %} ### 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 ```json { "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%" } ] }, "": { "default": [ { "width": "60%", "height": "10%", "bottom": "0", "left": "20%" } ] }, "": { "action": "hide" } } } } ``` #### Game Code {% tabs %} {% tab title="Plain JS" %} ```javascript // 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() ``` {% endtab %} {% tab title="Unity" %} ```csharp 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; } } ``` {% endtab %} {% tab title="Godot" %} {% tabs %} {% tab title="Godot 3.x" %} ```gdscript 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) ``` {% endtab %} {% tab title="Godot 4.x" %} ```gdscript 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) ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="GameMaker" %} **Create Event (`Create_0.gml`):** ```gml playgama_bridge_platform_send_message("game_ready", "") ``` **Game Logic (e.g. in a Step or button handler):** ```javascript // 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`):** ```javascript 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 } } ``` {% endtab %} {% tab title="Defold" %} ```lua 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 ``` {% endtab %} {% tab title="Cocos Creator" %} ```typescript 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) } } ``` {% endtab %} {% endtabs %} ### Configuration Use the [config editor](https://playgama.github.io/bridge-config-editor/) to configure Advanced Banners in `playgama-bridge-config.json` under `advertisement.advancedBanners`. ```json { "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 platform message (e.g. `game_ready`, `level_paused`, `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: ```json "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: ```json { "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.) | +4 | | Orientation (`portrait`, `landscape`) | +2 | | Canvas mode (`canvas`) | +1 | | Each dimension/aspect ratio condition | +1 | 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 | 4 | | `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` | no | — | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://wiki.playgama.com/playgama/sdk/api/advertisement/advanced-banners.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.