---
metadata:
  - name: generator
    content: Diplodoc Platform v5.52.0
alternate:
  - https://yandex.com/dev/games/doc/en/sdk/sdk-adv.md
  - https://yandex.com/dev/games/doc/hi/sdk/sdk-adv.md
  - https://yandex.com/dev/games/doc/ko/sdk/sdk-adv.md
  - https://yandex.com/dev/games/doc/ru/sdk/sdk-adv.md
  - https://yandex.com/dev/games/doc/tr/sdk/sdk-adv.md
  - https://yandex.com/dev/games/doc/vi/sdk/sdk-adv.md
  - https://yandex.com/dev/games/doc/zh/sdk/sdk-adv.md
  - href: zh/sdk/sdk-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)。
1. 使用 SDK [配置广告调用](#settings)。
1. 在开发人员控制台中[启用变现](https://yandex.com/dev/games/doc/zh/console/adv-monetization.md)。

## 广告放置的特点和建议 {#recommendations}

- 合理放置广告，让用户注意到这是一个广告单元，而不是游戏的一部分。
- 建议在用户操作后或通过计时器显示广告（如果通过关卡需要超过 5 分钟）。详见[广告位置](https://yandex.com/dev/games/doc/zh/requirements/4/4.md)。
- 调用[视频广告（奖励视频）](#rewarded-video)的频率不受限制。
- 全屏广告块的调用频率由 [Yandex Games](https://yandex.com/games/){.external} 平台控制。


{% note alert %}

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

为避免发生这种情况，请不要在用户积极与游戏互动时调用广告显示，因为这时用户可能会无意中点击广告块。

错误调用的示例：

```javascript
setInterval(() => ysdk.adv.showFullscreenAdv(), 180000)
```

{% endnote %}


## 全屏广告块 {#full-screen-block}

完全覆盖应用并在用户请求某些信息（例如进入下一游戏关卡）与获得该信息之间显示的广告块。

### ysdk.adv.showFullscreenAdv() {#show-fullscreen-adv}

调用全屏广告块。

**方法签名**

```typescript showLineNumbers
function showFullscreenAdv(callbacks?: {
    onOpen?: () => void;
    onClose?: (wasShown: boolean) => void;
    onError?: (error: object) => void;
}) => void {}
```

在 `callbacks` 参数中可以传递可选的回调函数：

#|
|| **回调函数** | **描述** ||
|| `onOpen` | 在成功打开广告时调用。||
|| `onClose` | 在广告关闭、发生错误或广告因调用过于频繁而未能打开时调用。与 `wasShown` 参数（`boolean` 类型）一起使用，它的值表示是否显示广告。||
|| `onError` | 在发生错误时调用。错误对象会传递给回调函数。||
|#

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

```javascript showLineNumbers
const ysdk = await YaGames.init();

ysdk.adv.showFullscreenAdv({
    [callbacks](*key_callbacks): {
        [onOpen](*key_onOpen): () => console.log('广告已打开。'),
        [onClose](*key_onClose): (wasShown) => console.log(wasShown ? '已显示并关闭。' : '未显示。'),
        [onError](*key_onError): (error) => console.log('调用错误。'),
    }
})
```


## 视频广告（奖励视频） {#rewarded-video}

用户可通过观看获得奖励（例如游戏内货币）的视频广告块。

### ysdk.adv.showRewardedVideo() {#show-rewarded-video}

调用视频广告（奖励视频）。

**方法签名**

```typescript showLineNumbers
function showRewardedVideo(callbacks?: {
    onOpen?: () => void;
    onRewarded?: () => void;
    onClose?: (wasShown: boolean) => void;
    onError?: (error: object) => void;
}) => void {}
```

在 `callbacks` 参数中可以传递可选的回调函数：

#|
|| **回调函数** | **描述** ||
|| `onOpen` | 在屏幕上显示视频广告时调用。||
|| `onRewarded` | 在计算视频广告展示次数时调用。在此函数中指定用户观看后将获得的奖励。||
|| `onClose` | 在视频广告关闭时调用。||
|| `onError` | 在发生错误时调用。错误对象会传递给回调函数。||
|#


#### 示例 {#rewarded-video-example}

```javascript showLineNumbers
const ysdk = await YaGames.init();

ysdk.adv.showRewardedVideo({
    [callbacks](*key_callbacks): {
        [onOpen](*key_onOpen): () => console.log('广告已打开。'),
        [onRewarded](*key_onRewarded): () => console.log('用户已获得奖励。'),
        [onClose](*key_onClose2): (wasShown) => console.log(wasShown ? '已显示并关闭。' : '未显示。'),
        [onError](*key_onError): (error) => console.log('调用错误。'),
    }
})
```

## 粘性横幅 {#sticky-banner}

在游戏过程中显示的广告块。

### 启用粘性横幅显示 {#banner-on}

1. 打开[开发人员控制台](https://games.yandex.com/console){.external}并转到 **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** 选项。横幅将在右侧显示。

### 管理粘性横幅显示 {#banner-adv}

默认情况下，粘性横幅会在游戏启动时出现，并在整个会话期间显示。要使用 SDK 方法管理粘性横幅显示，请在[开发人员控制台](https://games.yandex.com/console){.external}的 **Advertising** 选项卡中启用 **Use the API to display a sticky-banner** 选项。

#### ysdk.adv.getBannerAdvStatus() {#get-banner-adv-status}

获取粘性横幅的当前状态。

**方法签名**

```typescript showLineNumbers
function getBannerAdvStatus(): Promise<{
    stickyAdvIsShowing: boolean;
    reason?: 'ADV_IS_NOT_CONNECTED' | 'UNKNOWN';
}> {}
```

返回粘性横幅显示状态 `stickyAdvIsShowing`。如果横幅未显示，还会返回可选字段 `reason`，指示横幅缺失的原因：

#|
|| **原因** | **描述** ||
|| `ADV_IS_NOT_CONNECTED` | 横幅未连接。||
|| `UNKNOWN` | Yandex 端显示广告时出错。||
|#

#### ysdk.adv.showBannerAdv() {#show-banner-adv}

显示粘性横幅。

**方法签名**

```typescript showLineNumbers
function showBannerAdv(): Promise<{
    stickyAdvIsShowing: boolean;
    reason?: 'ADV_IS_NOT_CONNECTED' | 'UNKNOWN';
}>
```

返回值与 [ysdk.adv.getBannerAdvStatus()](#get-banner-adv-status) 相同。

#### ysdk.adv.hideBannerAdv() {#hide-banner-adv}

隐藏粘性横幅。

**方法签名**

```typescript showLineNumbers
function hideBannerAdv(): Promise<{
    stickyAdvIsShowing: boolean;
}>
```

返回粘性横幅显示状态 `stickyAdvIsShowing`。

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

```javascript showLineNumbers
const ysdk = await YaGames.init();

const { stickyAdvIsShowing , reason } = await ysdk.adv.getBannerAdvStatus();

if (stickyAdvIsShowing) {
    // 显示广告。
} else if (reason) {
    // 不显示广告。
    console.log(reason);
} else {
    ysdk.adv.showBannerAdv();
}
```

---

<!-- source: zh/_includes/sdk-support.md -->
{% note info %}

技术支持团队将协助您将已完成的游戏发布到 Yandex 游戏平台。关于开发和测试方面的具体问题，其他开发人员将在[Discord 频道](https://discord.com/invite/wU4p3whr4T){.external}中进行回答。

{% endnote %}

如果您遇到 Yandex Games SDK 方面的问题或有其他问题想要咨询，请联系支持部门：

<!-- source: zh/_includes/button-chat.md -->
<a href="https://yandex.com/chat/#/user/a4fa5c06-75db-9b38-6eea-b1673785f7d5">
  <span class="button">写入聊天信息</span>
</a>
<!-- endsource: zh/_includes/button-chat.md -->
<!-- endsource: zh/_includes/sdk-support.md -->

[*key_callbacks]: `callbacks`：可选的回调函数。将为每个广告单元单独配置。

[*key_onOpen]: `onOpen`：在屏幕上显示视频广告的时候调用。

[*key_onRewarded]: `onRewarded`：在计算视频广告展示次数时调用此函数。使用此函数可指定观看视频广告的奖励。

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

[*key_onClose2]: `onClose`：在用户关闭视频广告的时候调用。

[*key_onError]: `onError`：在发生错误的时候调用。错误对象会传递给回调函数。