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에서 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 이름의 커스텀 컨텍스트 오브젝트가 추가돼요:

{
  "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://[e-mail]/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 파이프라인 예시

# 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에서 크래시 위치를 정확한 소스 코드 라인으로 확인할 수 있어요.

---

트러블슈팅

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로 설정돼요.