Unity 앱 연동¶
Unity 앱의 메트릭 데이터를 수집하여 앱 성능을 시각화하여 분석합니다.
읽기 경로¶
- 최초 연동: 먼저 연동 방식 선택을 진행합니다. 수동 연동은 빠른 시작을 참고하세요.
- 전체 연동: 이 문서를 계속 읽습니다.
- 파라미터 상세: SDK 초기화, RUM 설정, Log 설정, Trace 설정을 참고하세요.
- 사용자 정의 기능: 사용자 정의 태그 사용, RUM 수동 계측, 데이터 수집 마스킹을 참고하세요.
- 고급 시나리오: 네이티브와 Unity 혼합 개발을 참고하세요.
- 문제 해결: 트러블슈팅을 참고하세요.
사전 조건¶
주의
RUM Headless 서비스를 이미 개통한 경우 사전 조건이 자동으로 구성되므로 앱을 바로 연동할 수 있습니다.
로컬 환경 배포를 사용하는 경우 다음 데이터 수신 측 구성을 완료해야 합니다. 공용 네트워크 DataWay를 사용하는 경우에는 DataKit을 직접 배포할 필요가 없습니다.
- DataKit 설치
- RUM 수집기 구성
- DataKit을 공용 네트워크에서 액세스 가능하도록 구성하고 IP 지리 정보 라이브러리 설치
앱 연동¶
- RUM > 앱 생성 > Android/iOS로 이동합니다.
- Android와 iOS 플랫폼의 RUM 데이터를 각각 수신할 수 있도록 Unity Android용과 Unity iOS용 앱을 각각 두 개 생성합니다.
- 각 플랫폼의 앱에 해당하는 앱 이름과 앱 ID를 입력합니다.
- 「연동 방식 선택」에서 Agent 자동 연동 또는 수동 연동을 선택한 후 「연동 설정」을 완료합니다.
연동 방식 선택¶
앱 설정 페이지에서 「Agent 자동 연동」 또는 「수동 연동」을 선택한 후 「연동 설정」을 완료합니다. 기존 앱은 설정 페이지로 바로 이동하여 연동을 계속할 수 있습니다.
| 연동 방식 | 사용 사례 | 작업 진입점 |
|---|---|---|
| Agent 자동 연동 | 프로그래밍 어시스턴트가 프로젝트를 분석하여 SDK 연동을 완료하도록 하려는 경우 | 콘솔에서 생성된 프롬프트를 복사하여 앱 코드 저장소에서 프로그래밍 어시스턴트에게 실행하도록 전달 |
| 수동 연동 | SDK를 직접 설치하고 파라미터를 구성하려는 경우 | 데이터 보고 방식을 확인한 후 이 문서와 빠른 시작에 따라 구성 완료 |
Agent 자동 연동¶
- 현재 앱의 설정 페이지에서 「Agent 자동 연동」을 선택합니다.
- 「연동 설정」의 전체 프롬프트를 복사하고, 현재 앱의 연동 정보가 사용되는지 확인합니다.
- 앱 코드 저장소에서 프로그래밍 어시스턴트를 열고 프롬프트를 붙여넣으면 Agent가 연동 가이드에 따라 프로젝트를 분석하고 SDK 구성을 완료합니다.
- 앱을 빌드하고 실행하여 페이지 방문 등의 작업을 트리거한 뒤, 현재 앱의 탐색기에서 데이터가 수신되는지 확인합니다.
크로스 플랫폼 프레임워크를 사용하는 경우 Agent에게 프레임워크와 대상 플랫폼을 설명하고 각 플랫폼에 해당하는 앱 정보를 각각 제공하세요.
페이지에서 개인 API Key 또는 임시 인증 코드가 준비되지 않았다고 안내하는 경우, 안내에 따라 보완한 후 프롬프트를 다시 복사하세요.
수동 연동¶
앱 설정 페이지에서 「수동 연동」을 선택하고 데이터 보고 방식을 확인합니다.
- 공용 네트워크 DataWay: RUM 데이터를 직접 수신하며 DataKit 수집기를 설치할 필요가 없습니다.
- 로컬 환경 배포: 사전 조건을 충족한 후 RUM 데이터를 수신합니다.
아래 설치와 빠른 시작에 따라 SDK 설치, 초기화 및 검증을 완료합니다. 기존 SDK 구성이 있는 경우 먼저 확인하여 재사용하고 중복 초기화를 피해야 합니다.
설치¶
소스 코드 주소: https://github.com/GuanceCloud/datakit-unity
Demo 주소: https://github.com/GuanceCloud/datakit-unity/blob/dev/Assets/Scenes
- 최신 ft-sdk-unity.unitypackage를 다운로드합니다.
Assets->Import Package->Custom Package...를 통해ft-sdk-unity.unitypackage를 가져옵니다.- JSON 파싱 서드파티 라이브러리
"com.unity.nuget.newtonsoft-json"을 추가하며,Package Manager->Add Package by name ...에서 완료할 수 있습니다. FTSDK.prefab을 첫 번째 씬 페이지로 드래그하고FTSDK.cs의_InitSDK메서드 내에서 SDK를 초기화합니다.FTViewObserver.prefab을 다른 씬 페이지로 드래그하여 페이지View라이프사이클과 앱 슬립 및 웨이크업을 모니터링합니다.Application.logMessageReceived를 통해 Unity 크래시 데이터와 일반 로그 데이터를 수신하고 변환합니다. 예시는 빠른 시작과 RUM 수동 계측을 참고하세요.
Assets/Plugins
├── Android
│ ├── FTUnityBridge.java // Android bridge
│ ├── InnerClassProxy.java // Android Inner Setting Proxy
│ ├── ft-sdk-release.aar // Android SDK
│ ├── gson-2.8.5.jar // Android SDK 의존 서드파티 라이브러리
├── iOS
│ ├── FTMobileSDK.xcframework // iOS SDK
│ ├── FTUnityBridge.mm // iOS bridge
├── FTSDK.cs // FTSDK.prefab 바인딩 스크립트
├── FTSDK.prefab // SDK 초기화 프리팹
├── FTUnityBridge.cs // iOS, Android 등 플랫폼 메서드를 브리징하는 Unity bridge
├── FTViewObserver.cs // FTViewObserver.prefab 바인딩 스크립트
├── FTViewObserver.prefab // View 페이지 모니터링 프리팹
├── UnityMainThreadDispatcher.cs // UnityMainThreadDispatcher.prefab 바인딩 스크립트
├── UnityMainThreadDispatcher.prefab // 메인 스레드 소비 큐 프리팹
- 네이티브 Android 및 iOS 프로젝트에 이미 네이티브 SDK가 연동된 경우 중복 설정을 피하기 위해
_InitSDK메서드를 주석 처리해야 합니다. 구체적인 시나리오는 네이티브와 Unity 혼합 개발을 참고하세요. - iOS Plugin Inspector 설정:
FTMobileSDK.xcframework는 동적 라이브러리이므로Add to Embedded Binaries를 체크해야 합니다. 이 옵션을 선택하면 Unity가 Xcode 프로젝트 옵션을 설정하여 플러그인 파일을 최종 앱 번들에 복사합니다.
네이티브 SDK가 이미 연동된 경우 Android의
gson-2.8.5.jar,ft-sdk-release.aar와 iOS의FTMobileSDK.framework는 Unity 프로젝트에서 제거할 수 있습니다.
Android의 OkHttp 요청 및 시작 소요 시간 기능은ft-plugin과 함께 사용해야 하며, 자세한 구성은 Android SDK를 참고하세요.
초기화 설명¶
최소 초기화 예시는 빠른 시작을 참고하세요.
전체 SDKConfig 파라미터 설명은 SDK 초기화를 참고하세요.
상세 구성 진입점¶
고급 시나리오¶
자주 묻는 질문¶
필드 충돌 방지를 위한 변수 추가¶
사용자 정의 필드와 SDK 데이터의 충돌을 방지하기 위해 태그 이름에 프로젝트 약어 접두사를 추가하는 것을 권장합니다(예: custom_tag_name). 프로젝트에서 사용하는 key 값은 소스 코드 확인을 통해 확인할 수 있습니다. SDK 전역 변수에 RUM, Log와 동일한 변수가 있는 경우 RUM, Log가 SDK의 전역 변수를 덮어씁니다.
