> For the complete documentation index, see [llms.txt](https://wiki.playgama.com/playgama/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.playgama.com/playgama/bridge-sdk-v1/bridge-sdk/api/advertisement/advanced-banners.md).

# Advanced Banners

Advanced Banners let you define responsive banner layouts that adapt to device type, orientation, and screen size. Unlike [regular banners](/playgama/bridge-sdk-v1/bridge-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.

<figure><img src="/files/GTzk8rydNy5zV9hdsFtJ" alt=""><figcaption></figcaption></figure>

<details>

<summary>Copy This Example</summary>

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

</details>
{% endtab %}

{% tab title="GDevelop" %}
Use **Is Advanced Banners Supported** to check availability before showing banner-related UI.

<figure><img src="/files/oC9vJt6bTuY6CVLZBU2q" alt=""><figcaption></figcaption></figure>

<details>

<summary>Copy This Example</summary>

```
{"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}}
```

</details>
{% 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 %}

<details>

<summary>Platform support · 3 of 28 platforms</summary>

**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`

</details>

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

<figure><img src="/files/AvWFtetbeKTYPZF8BeMV" alt=""><figcaption></figcaption></figure>

<details>

<summary>Copy This Example</summary>

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

</details>
{% endtab %}

{% tab title="GDevelop" %}
Display Advanced Banners for a placement configured in `playgama-bridge-config.json`. Parameters:

* Placement (optional)

<figure><img src="/files/BZUwOmhmw8rC0Hy0UxQa" alt=""><figcaption></figcaption></figure>

<details>

<summary>Copy This Example</summary>

```
{"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}}
```

</details>
{% 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.

<figure><img src="/files/VkBekSNbFDGDhFGDLF2j" alt=""><figcaption></figcaption></figure>

<details>

<summary>Copy This Example</summary>

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

</details>
{% endtab %}

{% tab title="GDevelop" %}
Hide the currently displayed Advanced Banners.

<figure><img src="/files/crlpQjoEXNNIy9Esz5up" alt=""><figcaption></figcaption></figure>

<details>

<summary>Copy This Example</summary>

```
{"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}}
```

</details>
{% 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:

<figure><img src="/files/nt4JFCqc2Q0mC1SqzJ3t" alt=""><figcaption></figcaption></figure>

<details>

<summary>Copy This Example</summary>

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

</details>

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

<figure><img src="/files/980EK2YayJEAYo6gdK4H" alt=""><figcaption></figcaption></figure>

<details>

<summary>Copy This Example</summary>

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

</details>

Custom messages work the same way:

<figure><img src="/files/qUHTxPTsoDTS4FglqtCV" alt=""><figcaption></figcaption></figure>

<details>

<summary>Copy This Example</summary>

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

</details>
{% 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:

<figure><img src="/files/af6C1oeujLfJPpzdR7jg" alt=""><figcaption></figcaption></figure>

<details>

<summary>Copy This Example</summary>

```
{"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}}
```

</details>

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

<figure><img src="/files/Gi1Jg6vx23qQ8jdHdVYb" alt=""><figcaption></figcaption></figure>

<details>

<summary>Copy This Example</summary>

```
{"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}}
```

</details>

Custom messages work the same way:

<figure><img src="/files/MSeMEhVWWCzxn3k0YU4n" alt=""><figcaption></figcaption></figure>

<details>

<summary>Copy This Example</summary>

```
{"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}}
```

</details>
{% 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.

<figure><img src="/files/fZnK6kplBdTgDhSIt3Kh" alt=""><figcaption></figcaption></figure>

<details>

<summary>Copy This Example</summary>

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

</details>

**On Advanced Banners Loading**

<figure><img src="/files/uH3Kpoioib1uqcftp3a1" alt=""><figcaption></figcaption></figure>

<details>

<summary>Copy This Example</summary>

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

</details>

**On Advanced Banners Shown**

<figure><img src="/files/rmazrJCqk8sNdKtbcCjQ" alt=""><figcaption></figcaption></figure>

<details>

<summary>Copy This Example</summary>

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

</details>

**On Advanced Banners Hidden**

<figure><img src="/files/IZgQRx7zf1ZLTmqz6E3z" alt=""><figcaption></figcaption></figure>

<details>

<summary>Copy This Example</summary>

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

</details>

**On Advanced Banners Failed**

<figure><img src="/files/ueYjeLj7bsjmEzaZgXAX" alt=""><figcaption></figcaption></figure>

<details>

<summary>Copy This Example</summary>

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

</details>
{% 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.

<figure><img src="/files/iMsDUSKcckbD51XGLQqt" alt=""><figcaption></figcaption></figure>

<details>

<summary>Copy This Example</summary>

```
{"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}}
```

</details>

**On Advanced Banners Loading**

<figure><img src="/files/Px0JVJSGCo3LvZJ46uax" alt=""><figcaption></figcaption></figure>

<details>

<summary>Copy This Example</summary>

```
{"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}}
```

</details>

**On Advanced Banners Shown**

<figure><img src="/files/qTO9R84qYsjYwcKfAHNK" alt=""><figcaption></figcaption></figure>

<details>

<summary>Copy This Example</summary>

```
{"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}}
```

</details>

**On Advanced Banners Hidden**

<figure><img src="/files/puOszjXZMP5mD1iFpPIF" alt=""><figcaption></figcaption></figure>

<details>

<summary>Copy This Example</summary>

```
{"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}}
```

</details>

**On Advanced Banners Failed**

<figure><img src="/files/USmL9lvbjiaQB1B2X43D" alt=""><figcaption></figcaption></figure>

<details>

<summary>Copy This Example</summary>

```
{"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}}
```

</details>
{% 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%" }
                ]
            },
            "<your_placement_here>": {
                "default": [
                    { "width": "60%", "height": "10%", "bottom": "0", "left": "20%" }
                ]
            },
            "<your_placement_here>": {
                "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 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:

```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             | —                            |