Sentry 集成

Sentry 集成

AIT SDK Sentry Unity SDK与其支持自动集成。安装了 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。

如果已经安装了 Sentry SDK，菜单会被禁用。

方法 2：直接添加 manifest.json

Packages/manifest.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 会添加一个名为的自定义上下文对象：

{
  "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://[e-mail]/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 管道示例

# 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 中将崩溃位置精确定位到源代码行。

---

故障排查

Sentry 事件没有发送

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

IL2CPP 构建中没有 AIT 标签

集成代码可能已被 IL2CPP 裁剪移除。

1. Assets/link.xml中包含以下内容：

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

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

AIT 上下文的部分值显示为 `unavailable`

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

• 在 Mock 桥接环境中，部分 API 可能不受支持。
• 如果是网络超时，则不会重试， unavailable会被设为。