> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/unity/sentry-ji-cheng.md).

# Sentry 集成

## Sentry 集成

AIT SDK [Sentry Unity SDK](https://docs.sentry.io/platforms/unity/)支持与之自动集成。若已安装 Sentry，会自动将 AIT 平台上下文（设备 ID、环境、部署 ID 等）注入到崩溃和错误事件中。

**零成本选择加入**: 在未安装 Sentry SDK 的项目中，相关代码根本不会被编译。没有运行时开销，也没有编译错误。

***

### 安装

#### 方法 1：Unity 菜单（推荐）

1. 在 Unity Editor 中 `AIT` > `Install Sentry SDK`点击。
2. Package Manager 会自动安装 Sentry Unity SDK 4.1.0。

{% hint style="info" %}
如果已安装 Sentry SDK，该菜单会被禁用。
{% endhint %}

#### 方法 2：直接添加 manifest.json

`Packages/manifest.json`可以直接添加到其中：

```json
{
  "dependencies": {
    "io.sentry.unity": "https://github.com/getsentry/unity.git#4.1.0"
  }
}
```

#### 支持版本

* **最低**: `io.sentry.unity` 4.0.0
* **建议**: 4.1.0 及以上

***

### 设置

只需要配置 Sentry SDK 本身。AIT 集成无需单独配置，会自动工作。

#### DSN 设置

在 Unity Editor 中 `工具` > `Sentry`打开 **DSN**输入。

DSN 可在 Sentry 项目的 `Settings > Client Keys (DSN)`中查看。配置值会 `Assets/Resources/Sentry/SentryOptions.asset`保存到其中。

***

### 自动注入的 AIT 上下文

当 Sentry SDK 处于启用状态时，AIT SDK 会自动注入以下上下文。

#### 标签

| 标签                     | 说明          | 示例                      |
| ---------------------- | ----------- | ----------------------- |
| `ait.sdk_version`      | AIT SDK 版本  | `1.11.2`                |
| `ait.unity_version`    | Unity 引擎版本  | `6000.3.3f1`            |
| `ait.device_id`        | 设备唯一 ID     | `abc123...`             |
| `ait.platform_os`      | 平台 OS       | `iOS`, `Android`        |
| `ait.locale`           | 设备区域设置      | `ko-KR`                 |
| `ait.toss_app_version` | Toss 应用版本   | `5.80.0`                |
| `ait.environment`      | 运行环境        | `production`, `staging` |
| `ait.deployment_id`    | 部署 ID       | `deploy-xyz`            |
| `ait.current_scene`    | 当前 Unity 场景 | `MainMenu`              |

#### 用户

| 字段        | 值                               |
| --------- | ------------------------------- |
| `User.Id` | AIT 设备 ID (`AIT.GetDeviceId()`) |

#### 上下文对象

`apps_in_toss` 会添加一个名为的自定义上下文对象：

```json
{
  "sdk_version": "1.11.2",
  "unity_version": "6000.3.3f1",
  "device_id": "abc123...",
  "platform_os": "iOS",
  "locale": "ko-KR",
  "toss_app_version": "5.80.0",
  "environment": "production",
  "deployment_id": "deploy-xyz"
}
```

#### 面包屑

每次加载 Unity 场景时，都会自动记录 breadcrumb：

| 字段       | 值                                              |
| -------- | ---------------------------------------------- |
| 消息       | `Scene loaded: MainMenu`                       |
| category | `scene`                                        |
| level    | `Info`                                         |
| data     | `scene_name`, `scene_build_index`, `load_mode` |

***

### CI/CD 环境变量

#### Sentry SDK 核心（构建时自动注入）

AIT SDK 在 WebGL 构建时 `SENTRY_DSN` 在环境变量中 `SentryOptions.asset`会自动生成。

| 变量                   | 用途                               | 示例                          |
| -------------------- | -------------------------------- | --------------------------- |
| `SENTRY_DSN`         | DSN → `SentryOptions.asset` 自动生成 | `https://key@sentry.io/123` |
| `SENTRY_ENVIRONMENT` | 环境标识符（自动注入）                      | `production`, `staging`     |
| `SENTRY_RELEASE`     | 发布版本（自动注入）                       | `my-app@1.0.0`              |

#### sentry-cli（构建时）

用于上传调试符号和 source map。请在 CI/CD 流水线中配置。

| 变量                  | 用途       | 示例           |
| ------------------- | -------- | ------------ |
| `SENTRY_AUTH_TOKEN` | API 认证令牌 | `sntrys_...` |
| `SENTRY_ORG`        | 组织 slug  | `my-org`     |
| `SENTRY_PROJECT`    | 项目 slug  | `unity-game` |

#### CI/CD 流水线示例

```yaml
# GitHub Actions
env:
  SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
  SENTRY_ORG: my-org
  SENTRY_PROJECT: unity-game
```

***

### 工作原理

#### 条件编译

Sentry 集成通过 Unity 的 `versionDefines`实现条件编译：

1. `io.sentry.unity` 当安装 4.0.0 及以上版本时 `AIT_SENTRY_AVAILABLE` define 会自动启用。
2. `AppsInToss.Sentry` 程序集的 `defineConstraints`中 `AIT_SENTRY_AVAILABLE`会设置为此项。
3. 如果未安装 Sentry SDK，整个程序集都会被排除在编译之外。

#### IL2CPP 剥离保护

为了防止在 WebGL（IL2CPP）构建中代码被移除，应用了三重保护：

| 保护手段                             | 作用            |
| -------------------------------- | ------------- |
| `[assembly: AlwaysLinkAssembly]` | 防止程序集本身被链接器移除 |
| `[Preserve]`                     | 保留单个类型/方法     |
| `link.xml`                       | 声明保留程序集内所有类型  |

#### Unity 6+ IL2CPP 堆栈跟踪

在 Unity 6 及以上版本中，WebGL 构建时会自动启用 IL2CPP 堆栈跟踪中的 C# 文件/行号信息。这样可以在 Sentry 中将崩溃位置精确定位到源代码行。

***

### 故障排查

<details>

<summary>Sentry 事件没有发送</summary>

1. `Tools > Sentry`中 DSN 是否已正确设置。
2. 控制台中 `[AIT:Sentry] Sentry is not enabled` 如果有该消息，说明 Sentry SDK 处于禁用状态。
3. 对于 WebGL CI/CD， `SENTRY_DSN` 如果设置环境变量，在构建时 `SentryOptions.asset`它会自动生成。

</details>

<details>

<summary>IL2CPP 构建中没有 AIT 标签</summary>

集成代码可能因 IL2CPP 剥离而被移除。

1. `Assets/link.xml`请确认其中包含以下内容：

```xml
<linker>
    <assembly fullname="AppsInToss.Sentry" preserve="all"/>
</linker>
```

2. `Library/Bee/artifacts/WebGL/` 请删除该文件夹并执行干净构建。

</details>

<details>

<summary>AIT 上下文的部分值显示为 `unavailable`</summary>

这是 AIT 平台 API 调用失败的情况。各 API 独立失败，其余上下文仍会正常注入。

* 在 Mock Bridge 环境中，部分 API 可能不受支持。
* 如果是网络超时，则不会重试而是 `unavailable`被设置为 \`unavailable\`。

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/unity/sentry-ji-cheng.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.