---
metadata:
  - name: generator
    content: Diplodoc Platform v5.52.0
alternate:
  - https://yandex.com/dev/games/doc/en/sdk/sdk-environment.md
  - https://yandex.com/dev/games/doc/hi/sdk/sdk-environment.md
  - https://yandex.com/dev/games/doc/ko/sdk/sdk-environment.md
  - https://yandex.com/dev/games/doc/ru/sdk/sdk-environment.md
  - https://yandex.com/dev/games/doc/tr/sdk/sdk-environment.md
  - https://yandex.com/dev/games/doc/vi/sdk/sdk-environment.md
  - https://yandex.com/dev/games/doc/zh/sdk/sdk-environment.md
  - href: zh/sdk/sdk-environment.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 -->

您可以获取有关游戏环境的信息。为此，请使用 `environment` 对象。

```javascript showLineNumbers
{
  [app](*key_app): {
    [id](*key_id): string;
  };
  [i18n](*key_i18n): {
    [lang](*key_lang2): string;
  };
  [payload?](*key_payload): string;
  [referrer?](*key_referrer): {
    [type](*key_type): "promo";
    [promoId](*key_promo_id): string;
    [intent?](*key_intent): string;
    [inappId?](*key_inapp_id): string;
  }
}
```

## environment 对象 {#environment-object}

包含游戏环境变量。

#|
|| **参数** | **类型** | **描述** ||
|| `app` | `object` | 游戏数据。 ||
|| `i18n` | `object` | 服务国际化。 ||
|| `payload` | `string` | 游戏地址的 `payload` 参数值。可选。例如，在 `https://yandex.ru/games/app/123?payload=test` 中，您可以按如下所示返回 `test`：`ysdk.environment.payload`。 ||
|#


### app 结构 {#structure-app}

#|
|| **参数** | **类型** | **描述** ||
|| `id` | `string` | 游戏 ID。 ||
|#


### i18n 结构 {#structure-i18n}

#|
|| **参数** | **类型** | **描述** ||
|| `lang` | `string` | ISO 639-1 格式的 [Yandex Games 界面语言](https://yandex.com/dev/games/doc/zh/concepts/languages-and-domains.md#languages)。例如，`"tr"` 表示游戏当前正在 Yandex Games 土耳其语界面下运行。此参数用于自动确定游戏中用户的语言（[项 2.14](https://yandex.com/dev/games/doc/zh/concepts/requirements.md#2-14)）。 ||
|#

#### 示例 {#i18n-example}

```javascript showLineNumbers
const ysdk = (await YaGames.init());
const lang = ysdk.environment.i18n.lang; // 'en', 'ru', ...
```

### referrer 结构 {#structure-referrer}

使用 `ysdk.environment.referrer` 处理玩家从目录中促销横幅跳转的情况。优点：

- **对于玩家**：点击促销后，玩家会直接进入目标页面 —— 看到的正是他们点击的那个优惠。这有助于提升转化率，并降低启动时的流失率。
- **对于您**：您可以跟踪每次促销的效果 —— 有多少玩家跳转，有多少完成了购买。如需收集统计数据，请额外启用 [Yandex Metrica](https://yandex.com/dev/games/doc/zh/concepts/yandex-metrica.md)。

#### 配置 {#referrer-setup}

1. 在开发人员控制台中添加[促销活动](https://yandex.com/dev/games/doc/zh/console/promo-and-discounts.md)。平台将自动为目录中的促销横幅生成深层链接（deeplink）。

    带有促销参数的链接示例：

    ```text
    https://yandex.ru/games/app/{id}?lang=ru&referrer=promo&promo_id={PROMO_ID}&promo_intent={INTENT}&inapp_id={INAPP_ID}
    ```

    #|
    || **参数** | **说明** | **是否必填** | **来源** ||
    || `referrer` | 告知平台该跳转来自促销活动。 |::{align="center"}
    ![SVG](../_images/icons/yes-button.svg) | 始终为 `promo` ||
    || `promo_id` | 用于路由和分析的促销活动 ID。 |::{align="center"}
    ![SVG](../_images/icons/yes-button.svg) | **ID** ||
    || `promo_intent` | 用于游戏内路由和分析的自定义提示。 |  | **Intent** ||
    || `inapp_id` | 与游戏中该促销活动关联的应用内购买 ID。 |  | **In-app ID** ||
    |#

1. 在游戏中添加[跳转处理](#referrer-example)：SDK 会将深层链接的参数传入 `ysdk.environment.referrer` 对象 —— 使用这些参数向玩家显示目标页面。

    #|
    || **参数** | **类型** | **说明** | **来源** ||
    || `type` | `"promo"` | 显示跳转来源。跟踪 `type: "promo"` 可收集促销活动的分析数据。 | `referrer=promo` ||
    || `promoId` | `string` | 控制台 **Promos** 标签页中的促销活动 ID。用于为特定促销活动配置操作并收集相关分析数据。 | `promo_id` ||
    || `intent` | `string` | 任意字符串，例如 `open_starter_pack`。用于配置点击促销活动后的标准操作并收集相关分析数据。可选参数。 | `promo_intent` ||
    || `inappId` | `string` | 控制台 **Inaps** 标签页中的[应用内购买 ID](https://yandex.com/dev/games/doc/zh/console/purchases.md#add-purchases)。用于打开平台购买对话框。可选参数（仅适用于折扣促销活动）。 | `inapp_id` ||
    |#

1. 验证跳转：在 **Promos** 标签页的 **Check transition** 字段中，点击 **In the published version** 或 **In the draft**。如果配置正确，您将看到带有促销内容的页面：优惠、商店或具体的应用内购买。

#### 示例 {#referrer-example}

```javascript showLineNumbers
// 1. 初始化 SDK
const ysdk = await YaGames.init();

// 2. 获取 referrer
const { referrer } = ysdk.environment;

// 3. 处理来自促销活动的跳转
if (referrer?.type === 'promo') {
    if (referrer.inappId) {
        showPurchaseScreen(referrer.inappId);
    } else if (referrer.intent) {
        openScreen(referrer.intent);
    }
}
```

#### 典型场景 {#referrer-scenarios}

#|
|| **场景** | **目标受众** | **目的** | **示例** ||
|| 商品折扣 | 未付费玩家 | 首次付款 | `promo_id=SPRING_DISCOUNT`<br>`promo_intent=open_starter_pack`<br>`inapp_id=starter_pack_001`

→ `showPurchaseScreen()` ||
|| VIP 优惠或开启商店 | 付费玩家 | 提升客单价 | `promo_id=VIP_PROMO`<br>`promo_intent=open_shop`

→ `openShop()` ||
|| 季节性活动 | 所有活跃玩家 | 留存 | `promo_id=SALE_SPRING_2026`

→ 基础流程、横幅 ||
|#


---

<!-- 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_app]: 游戏数据。

[*key_id]: 游戏 ID。

[*key_browser]: 浏览器数据。

[*key_lang]: ISO 639-1 格式的首选浏览器语言。

[*key_i18n]: 服务国际化。

[*key_lang2]: ISO 639-1 格式的 [Yandex Games 界面语言](https://yandex.com/dev/games/doc/zh/concepts/languages-and-domains.md#languages)。例如，`"tr"` 表示游戏当前正在 Yandex Games 土耳其语界面下运行。建议使用此参数确定用户在游戏中使用的语言。

[*key_payload]: 游戏地址的 `payload` 参数值。
可选。
例如，在 `https://yandex.ru/games/app/123?payload=test` 中，您可以按如下所示返回 `test`：`ysdk.environment.payload`。

[*key_referrer]: 促销活动跳转数据。如果游戏是通过促销横幅的深层链接打开的，则存在此参数。否则为 `undefined`。

[*key_type]: 跳转来源。始终为 `"promo"`。

[*key_promo_id]: 控制台中 **Promos** 标签页上的活动 ID。

[*key_intent]: 任意字符串，例如 `open_starter_pack`。可选参数。

[*key_inapp_id]: 控制台中 **Inaps** 标签页上的[应用内购买 ID](https://yandex.com/dev/games/doc/zh/console/purchases.md#add-purchases)。可选参数（仅适用于折扣促销活动）。