> 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/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에서 `Tools` > `Sentry`를 열고 **DSN**을 입력해요.

DSN은 Sentry 프로젝트의 `Settings > Client Keys (DSN)`에서 확인할 수 있어요. 설정값은 `Assets/Resources/Sentry/SentryOptions.asset`에 저장돼요.

***

### 자동 주입되는 AIT 컨텍스트

Sentry SDK가 활성 상태이면, AIT SDK가 다음 컨텍스트를 자동으로 주입해요.

#### Tags

| Tag                    | 설명          | 예시                      |
| ---------------------- | ----------- | ----------------------- |
| `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` | 토스 앱 버전     | `5.80.0`                |
| `ait.environment`      | 운영 환경       | `production`, `staging` |
| `ait.deployment_id`    | 배포 ID       | `deploy-xyz`            |
| `ait.current_scene`    | 현재 Unity 씬  | `MainMenu`              |

#### User

| 필드        | 값                               |
| --------- | ------------------------------- |
| `User.Id` | AIT 기기 ID (`AIT.GetDeviceId()`) |

#### Context Object

`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"
}
```

#### Breadcrumbs

Unity 씬이 로드될 때마다 breadcrumb가 자동 기록돼요:

| 필드       | 값                                              |
| -------- | ---------------------------------------------- |
| message  | `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 (빌드 타임)

디버그 심볼 및 소스맵 업로드 시 사용해요. 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) 빌드에서 코드가 제거되지 않도록 3중 보호가 적용돼요:

| 보호 수단                            | 역할                       |
| -------------------------------- | ------------------------ |
| `[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/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.