# Advanced Banners

Advanced Banners let you define responsive, context-aware banner ad layouts that adapt to device type, screen orientation, and screen size. Unlike regular banners (which support only top/bottom positioning), Advanced Banners allow you to place multiple banners at arbitrary positions on the screen and automatically switch layouts when conditions change.

### Checking Support

Use the **Is Advanced Banners Supported** condition to check availability.

<figure><img src="https://1088849411-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ukgSPDBOdbQp4FYtbz1%2Fuploads%2F7uWKEzpSAuPjlQWB9uqJ%2FScreenshot%202026-04-13%20at%2003.14.52.png?alt=media&#x26;token=18156cec-d90f-48fa-a2cf-de72d676d8c1" 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>

### Usage

#### Show Advanced Banners

Display Advanced Banners for a given placement. The placement string must match a key configured in `playgama-bridge-config.json`. Parameters:

* Placement (optional)

<figure><img src="https://1088849411-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ukgSPDBOdbQp4FYtbz1%2Fuploads%2FDniWZSFRtjG4A4dbmqtB%2FScreenshot%202026-04-13%20at%2003.22.53.png?alt=media&#x26;token=c854c938-bf66-458d-93b9-c37abf2739e8" 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>

#### Hide Advanced Banners

Hide the currently displayed Advanced Banners.

<figure><img src="https://1088849411-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ukgSPDBOdbQp4FYtbz1%2Fuploads%2Fk1TBTKXlTaJd4RoEQiV2%2FScreenshot%202026-04-13%20at%2003.23.31.png?alt=media&#x26;token=f8c8c5ce-d604-4a8c-b42d-3f65a6e7d94e" 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>

#### Automatic via Platform Messages

Advanced Banners automatically react to platform messages. When you use the **Send Message** or **Send Custom Message** action, the system checks if a matching placement exists in the config and triggers it.

This will automatically show banners if `gameplay_stopped` placement is configured:

<figure><img src="https://1088849411-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ukgSPDBOdbQp4FYtbz1%2Fuploads%2FqWxFDNzwI0PksTT3Ux4Q%2FScreenshot%202026-04-13%20at%2003.22.24.png?alt=media&#x26;token=bf62df3e-ae74-41dd-aa43-944184405ce2" 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="https://1088849411-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ukgSPDBOdbQp4FYtbz1%2Fuploads%2Fyj5V0E2cYCrjHV7t8UJj%2FScreenshot%202026-04-13%20at%2012.06.15.png?alt=media&#x26;token=cda0927f-af99-49d2-86f8-ddae14699482" 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="https://1088849411-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ukgSPDBOdbQp4FYtbz1%2Fuploads%2FYPVJ0qNETXywusAPtVNi%2FScreenshot%202026-04-13%20at%2012.06.51.png?alt=media&#x26;token=088ed09f-7dbc-43ab-9d6a-a354e4f8e84d" 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>

This is the recommended approach because it ties banner visibility to your game's lifecycle without extra actions.

#### State Change Conditions

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="https://1088849411-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ukgSPDBOdbQp4FYtbz1%2Fuploads%2FcHAEEbtALi55mC75U29i%2FScreenshot%202026-04-13%20at%2012.08.15.png?alt=media&#x26;token=b41ba6ab-c1d9-46ff-99e9-6694fa3e1efe" 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="https://1088849411-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ukgSPDBOdbQp4FYtbz1%2Fuploads%2FgbfAUGZZPSiP6lW5lWj9%2FScreenshot%202026-04-13%20at%2012.08.49.png?alt=media&#x26;token=b3dc17c5-efc8-4cca-bcfe-c41b4d3239a8" 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="https://1088849411-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ukgSPDBOdbQp4FYtbz1%2Fuploads%2F6ptWyDWgF0z8kPvCcQmS%2FScreenshot%202026-04-13%20at%2012.09.24.png?alt=media&#x26;token=85bf13a3-94e0-4a2d-8336-6514fa1d27e5" 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="https://1088849411-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ukgSPDBOdbQp4FYtbz1%2Fuploads%2F406ubLVoz3nDB0NA4Be6%2FScreenshot%202026-04-13%20at%2012.10.05.png?alt=media&#x26;token=b0bc767f-d806-42a4-822c-5cfe1625c94b" 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="https://1088849411-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ukgSPDBOdbQp4FYtbz1%2Fuploads%2FaBWnqWgfxyIQrHQNmgks%2FScreenshot%202026-04-13%20at%2012.10.36.png?alt=media&#x26;token=56e7b7ce-e4b9-4fa4-941d-364c8e0970d3" 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>

### 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 additional events are 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, the system automatically re-evaluates conditions and switches to a better-matching variant if one exists. This happens with a 200ms debounce to avoid excessive updates.

For example, if a user rotates their phone from portrait to landscape, and your config has different layouts for each orientation, the banners will seamlessly switch.

### Complete Example

#### Config

```json
{
    "advertisement": {
        "advancedBanners": {
            "placementFallback": "gameplay_stopped",
            "gameplay_started": {
                "action": "hide"
            },
            "gameplay_stopped": {
                "action": "show",
                "default": [
                    { "width": "300px", "height": "250px", "bottom": "10%", "right": "5%" }
                ],
                "mobile:portrait": [
                    { "width": "320px", "height": "50px", "bottom": "0", "left": "0" }
                ],
                "mobile:landscape": [
                    { "width": "300px", "height": "250px", "top": "50%", "right": "0" }
                ],
                "desktop:w>1200": [
                    { "width": "160px", "height": "600px", "top": "10%", "left": "1%" },
                    { "width": "160px", "height": "600px", "top": "10%", "right": "1%" }
                ],
                "desktop:w<=1200": [
                    { "width": "728px", "height": "90px", "bottom": "0", "left": "50%" }
                ],
                "desktop:landscape:ar>=1.78": [
                    { "width": "200px", "height": "600px", "top": "5%", "left": "0" },
                    { "width": "200px", "height": "600px", "top": "5%", "right": "0" },
                    { "width": "970px", "height": "90px", "bottom": "0", "left": "50%" }
                ]
            },
            "<your_placement_here>": {
                "default": [
                    { "width": "728px", "height": "90px", "bottom": "0", "left": "50%" }
                ]
            },
            "<your_placement_here>": {
                "action": "hide"
            }
        }
    }
}
```

### Configuration

Advanced Banners are configured in `playgama-bridge-config.json` under `advertisement.advancedBanners`.

```json
{
    "advertisement": {
        "advancedBanners": {
            "disable": false,
            "placementFallback": "main_menu",
            "main_menu": {
                "default": [
                    { "width": "300px", "height": "250px", "top": "10%", "right": "10%" }
                ]
            },
            "level_paused": {
                "action": "show",
                "default": [
                    { "width": "300px", "height": "250px", "top": "10%", "right": "10%" }
                ],
                "mobile:portrait": [
                    { "width": "100%", "height": "80px", "bottom": "0", "left": "0" }
                ],
                "desktop:landscape:w>1200": [
                    { "width": "160px", "height": "600px", "top": "10%", "left": "2%" },
                    { "width": "160px", "height": "600px", "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` (other than `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": "160px", "height": "600px", "top": "10%", "left": "2%" },
    { "width": "160px", "height": "600px", "top": "10%", "right": "2%" },
    { "width": "728px", "height": "90px", "bottom": "0", "left": "50%" }
]
```

### Condition Keys

Condition keys are colon-separated segments that describe when a variant should be used. The system 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             | —                            |