---
metadata:
  - name: generator
    content: Diplodoc Platform v5.54.4
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: zh/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/zh/llms.txt

# 管理广告

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

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

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

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

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

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


您可以通过在游戏中放置广告块来获得收入。为此，您需要：
1. 查看关于放置广告的[提示和建议](#recommendations)。
2. 使用 SDK 配置广告调用。
3. 使用 Yandex Games 开发者仪表板[启用货币化](https://yandex.com/dev/games/doc/zh/console/adv-monetization.md)。


## 关于放置广告的提示和建议 {#recommendations}

- 合理放置广告，让用户注意到这是一个广告单元，而不是游戏的一部分。
- 在游戏中插入广告的建议位置：开始游戏前、进入下一关卡前，以及输掉游戏后。
- 您可以根据所需的频率调用[奖励视频](#rewarded-video)。
- 调用插屏广告单元的频率由 [Yandex Games](https://yandex.com/games/){.external} 控制。


{% note alert %}

当用户随机点击广告单元时，Yandex 广告网络会将其视为广告欺诈的迹象，从而减少游戏的广告收入。

为避免发生这种情况，请不要在游戏进行期间调用广告，因为这时用户可能会无意中点击广告块。

{% endnote %}

## 配置广告调用 {#settings}

### 插屏广告 {#full-screen-block}

插屏广告是指完全覆盖应用背景并在用户获得所请求的数据（例如进入下一游戏关卡）之前显示的广告单元。

要调用广告，请使用 `ysdk.adv.show_fullscreen_adv()` 方法。

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

`callbacks: table` —— 可选的回调函数。将为每个广告单元单独配置。

- `on_close` — 在广告关闭、发生错误或广告因调用过于频繁而未能打开的时候调用。与 `wasShown` 参数（`boolean` 类型）一起使用，它的值表示是否显示广告。

- `on_open` — 在成功打开广告的时候调用。

- `on_error` — 在发生错误的时候调用。错误对象会传递给回调函数。

- `on_offline` —— 在网络连接丢失（进入离线模式）时被调用。

#### 示例 {#full-screen-example}

```lua showLineNumbers
ysdk.adv.show_fullscreen_adv({
  on_close = function (self, was_shown)
    -- 关闭后的操作。
  end,
  on_error = function (self, error)
    -- 发生错误时的操作。
  end
})
```

### 奖励视频 {#rewarded-video}

奖励视频是用于游戏货币化的视频广告块。用户可通过观看奖励视频获得奖励或游戏货币。

要调用广告，请使用 `ysdk.adv.show_rewarded_video()` 方法。

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

`callbacks: table` — 可选的回调函数。将为每个广告单元单独配置。

- `on_close` — 在用户关闭视频广告的时候调用。

- `on_open` — 在屏幕上显示视频广告的时候调用。

- `on_error` — 在发生错误的时候调用。错误对象会传递给回调函数。

- `on_rewarded` — 在计算视频广告展示次数的时候调用。使用此函数可指定观看视频广告的奖励。

#### 示例 {#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}

启用[粘性横幅](*key_sticky)显示：

1. 打开开发者控制台并切换至 **Advertising** 选项卡。
1. 在 **Sticky banners** 区域设置横幅显示：
    - 对于移动设备：
        - **Sticky banner in portrait orientation** —— 选择位置为 **At the bottom** 或 **At the top**；
        - **Sticky banner in landscape orientation** —— 选择位置为 **At the bottom**、**At the top** 或 **On the right**。

    - 对于桌面设备 —— 启用选项 **Sticky banner on the desktop**。横幅将显示在右侧。


默认情况下，粘性横幅会在游戏启动时出现，并在整个游戏期间显示。设置显示横幅的时间：

1. 在 **Sticky banners** 块中启用 **Use the API to display a sticky-banner** 选项。
2. 使用以下方法设置横幅显示：
    - `ysdk.adv.get_banner_adv_status()` —— 显示横幅状态。
    - `ysdk.adv.show_banner_adv()` —— 调用横幅。
    - `ysdk.adv.hide_banner_adv()` —— 移除横幅。

`ysdk.adv.get_banner_adv_status()` 方法返回一个 `sticky_adv_is_showing: boolean` 值。如果 `sticky_adv_is_showing = false`，该方法
`ysdk.adv.get_banner_adv_status()` 可能会返回一个可选的 `reason` 字段，表示可能的原因：

- `ADV_IS_NOT_CONNECTED` —— 横幅未连接。
- `UNKNOWN` —— 在 Yandex 端显示广告时出错。

#### 示例 {#sticky-banner-example}

```lua showLineNumbers
ysdk.adv.get_banner_adv_status(
  function (self, sticky_adv_is_showing, reason)
    if sticky_adv_is_showing then
      -- 显示广告。
    elseif reason then
      -- 不显示广告。
      print(reason)
    else
      ysdk.adv.show_banner_adv()
    end
  end
)
```

---



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

[*key_sticky]: 在游戏期间显示的广告单元。