> 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.md).

# Sentry 集成

## Sentry 集成

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

**零成本 opt-in**：如果项目未安装 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 项目的 `设置 > 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 都会自动记录：

| 字段 | 值                                              |
| -- | ---------------------------------------------- |
| 消息 | `场景已加载：MainMenu`                               |
| 类别 | `scene`                                        |
| 级别 | `信息`                                           |
| 数据 | `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`     | 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 桥接环境中，部分 API 可能不受支持。
* 如果是网络超时，则不会重试， `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.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.