---
metadata:
  - name: generator
    content: Diplodoc Platform v5.55.2
alternate:
  - https://yandex.com/dev/games/doc/en/sdk/defold/adv.md
  - https://yandex.com/dev/games/doc/hi/sdk/defold/adv.md
  - https://yandex.com/dev/games/doc/ko/sdk/defold/adv.md
  - https://yandex.com/dev/games/doc/ru/sdk/defold/adv.md
  - https://yandex.com/dev/games/doc/tr/sdk/defold/adv.md
  - https://yandex.com/dev/games/doc/vi/sdk/defold/adv.md
  - https://yandex.com/dev/games/doc/zh/sdk/defold/adv.md
  - href: en/sdk/defold/adv.md
    type: text/markdown
    title: Markdown version
  - href: ../../llms.txt
    type: text/markdown
    title: llms.txt
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/games/doc/en/llms.txt

# Ad management

<!-- source: en/_includes/script-common.md -->
<!-- source: en/_includes/script/index-js.md -->

<!-- endsource: en/_includes/script/index-js.md -->

<!-- source: en/_includes/script/requirements-js.md -->

<!-- endsource: en/_includes/script/requirements-js.md -->

<!-- source: en/_includes/script/image-modal-js.md -->

<!-- endsource: en/_includes/script/image-modal-js.md -->
<!-- endsource: en/_includes/script-common.md -->

You can generate revenue from placing ad units in your games. To do this:

1. Learn about the [tips and recommendations](#recommendations) for ad placement.
1. Set up ad calls using the SDK.
1. [Enable monetization](https://yandex.com/dev/games/doc/en/console/adv-monetization.md) in the Yandex Games Console.

## Tips and recommendations for placing ads {#recommendations}

- Ad calls should be placed in such a way that the user clearly perceives them as ads, not as an actual gameplay element.
- Recommended timings for calling ads in the game: before the game starts, during level transitions, and after losing.
- You can call [rewarded video ads](#rewarded-video) as often as you want.
- The frequency of calling an interstitial ad unit is controlled by [Yandex Games](https://yandex.com/games/){.external}.


{% note alert %}

The Yandex Advertising Network considers incidental user clicks on ad units as ad fraud and reduces revenue from in-game advertising.

To avoid this, do not call ads during gameplay, when users may unintentionally click on the ad unit.

{% endnote %}

## Configure ad calls {#settings}

### Interstitial ad {#full-screen-block}

Interstitial ad units completely cover the app background and are shown after certain data requests from the user (for example, when transitioning to the next game level) but before this data is returned.

To call an ad, use the `ysdk.adv.show_fullscreen_adv()` method.

```lua
ysdk.adv.show_fullscreen_adv(callbacks: table)
```

`callbacks: table` — Optional callback functions. They are configured individually for each ad unit.

- `on_close` — called when the ad closes, after an error, or after an ad failed to open due to too frequent calls. It's used with the `wasShown` argument (`boolean` type), the value of which indicates whether the ad was shown or not.

- `on_open` — called when the ad is opened successfully.

- `on_error` — called when an error occurs. The error object is passed to the callback function.

- `on_offline` — called when the network connection is lost (switching to offline mode).

#### Example {#full-screen-example}

```lua showLineNumbers
ysdk.adv.show_fullscreen_adv({
  on_close = function (self, was_shown)
    -- An action on ad closing.
  end,
  on_error = function (self, error)
    -- An action in case of an error.
  end
})
```

### Rewarded videos {#rewarded-video}

Rewarded videos are ad units for in-game monetization. that users can view in exchange for certain rewards or in-game currency.

To call an ad, use the `ysdk.adv.show_rewarded_video()` method.

```lua
ysdk.adv.show_rewarded_video(callbacks: table)
```

`callbacks: table` — optional callback functions. They are configured individually for each ad unit.

- `on_close` — called when the video ad closes.

- `on_open` — called when the video ad is shown on the screen.

- `on_error` — called when an error occurs. The error object is passed to the callback function.

- `on_rewarded` — called when a video ad impression is counted. This function should specify a reward for viewing the ad.

#### Example {#rewarded-video-example}

```lua showLineNumbers
ysdk.adv.show_rewarded_video({
  on_open = function (self)
    print("Video ad open")
  end,
  on_close = function (self)
    print("Rewarded!")
  end,
  on_rewarded = function (self)
    print("Video ad closed.")
  end,
  on_error = function (self, error)
    print("Error while open video ad: " .. error)
  end
})
```

### Sticky banner {#sticky-banner}

To enable a [sticky banner](*key_sticky):

1. Open the Games Console and go to the **Advertising** tab.
1. Go to **Sticky banners** and set up the display of banners:

   - For mobile devices:

      - **Sticky banner in portrait orientation**: Select the banner's position — **At the bottom** or **At the top**.
      - **Sticky banner in landscape orientation**: Select the banner's position — **At the bottom**, **At the top**, or **On the right**.

   - For computers: Enable the **Sticky banner on the desktop** option. The banner will be displayed on the right.


By default, the sticky banner appears upon launch and remains visible throughout the entire session. To configure the time for displaying the banner:

1. Under **Sticky banners**, enable the **Use the API to display a sticky-banner** option.
1. Set up banner display using the following methods:

    - `ysdk.adv.get_banner_adv_status()` — shows the status of the banner.
    - `ysdk.adv.show_banner_adv()` — calls the banner.
    - `ysdk.adv.hide_banner_adv()` — hides the banner.

The method `ysdk.adv.get_banner_adv_status()` returns a value `sticky_adv_is_showing: boolean`. If `sticky_adv_is_showing = false`, the method
`ysdk.adv.get_banner_adv_status()` may return an optional field `reason` with possible reasons:

- `ADV_IS_NOT_CONNECTED` — banners are not enabled.
- `UNKNOWN` — error displaying ads on the Yandex side.

#### Example {#sticky-banner-example}

```lua showLineNumbers
ysdk.adv.get_banner_adv_status(
  function (self, sticky_adv_is_showing, reason)
    if sticky_adv_is_showing then
      -- Advertisement is shown.
    elseif reason then
      -- Advertisement is not shown.
      print(reason)
    else
      ysdk.adv.show_banner_adv()
    end
  end
)
```

---



<!-- source: en/_includes/button-git.md -->
<a href="https://github.com/yandex-games-plugins/defold">
  <span class="button">Repository</span>
</a>
<!-- endsource: en/_includes/button-git.md -->

[*key_sticky]: An ad unit that is displayed during the game.