iOS/tvOS/macOS 앱 연동¶
iOS, tvOS, macOS 앱의 메트릭 데이터를 수집하여 Apple 플랫폼 앱의 성능을 시각화된 방식으로 분석합니다.
읽기 경로¶
- 최초 연동: 먼저 연동 방식 선택을 확인합니다. 수동 연동은 빠른 시작을 참고할 수 있습니다.
- 전체 연동: 이 문서를 계속 읽습니다.
- 1.6.6 이전 버전에서 업그레이드: 마이그레이션 가이드를 확인합니다.
- 초기화 파라미터: SDK 초기화, RUM 설정, Log 설정, Trace 설정을 확인합니다.
- 사용자 정의 기능: 사용자 정의 태그 사용, 사용자 정의 수집 규칙, 데이터 수집 마스킹을 확인합니다.
- 고급 시나리오: "고급 시나리오" 그룹의 전용 페이지를 확인합니다.
- 문제 해결: 문제 해결을 확인합니다.
사전 요구 사항¶
SDK 1.6.8+는 iOS 15, tvOS 15, macOS 12 이상을 요구합니다. 업그레이드 요구 사항은 1.6.8로 업그레이드를, 제품 이름 변경 및 이전 버전 배포 요구 사항은 1.6.6으로 업그레이드를 참고하세요.
주의
이미 RUM Headless 서비스를 활성화한 경우 사전 요구 사항이 자동으로 구성되었으므로 앱을 바로 연동할 수 있습니다.
로컬 환경 배포를 사용하는 경우 다음 데이터 수신 측 구성을 완료해야 합니다. 공용 DataWay를 사용하는 경우 DataKit을 직접 배포할 필요가 없습니다.
- DataKit 설치;
- RUM 수집기 구성;
- DataKit을 공용 네트워크에서 액세스 가능하게 하고 IP 지리 정보 라이브러리 설치.
macOS Alpha 안내
SDK 1.6.6 이상 버전에서 GuanceSDK 메인 SDK는 iOS, tvOS, macOS를 지원합니다. 이 중 macOS는 현재 Alpha 버전으로, 모든 iOS 기능의 지원을 보장하지 않습니다. macOS를 연동하기 전에 테스트 환경에서 초기화, RUM, Log, Trace, 데이터 동기화 등 핵심 경로를 먼저 검증하세요. Widget Extension은 macOS를 지원하지 않습니다. macOS Electron Session Replay의 연동 및 지원 범위는 macOS Electron 모니터링을 참고하세요.
앱 연동¶
- RUM > 앱 생성으로 이동하여 iOS, tvOS 또는 macOS 앱 유형을 선택합니다;
- 앱 이름을 입력합니다;
- 앱 ID를 입력합니다;
- 「연동 방식 선택」에서 Agent 자동 연동 또는 수동 연동을 선택한 후 「연동 설정」을 완료합니다.
연동 방식 선택¶
앱 설정 페이지에서 「Agent 자동 연동」 또는 「수동 연동」을 선택한 후 「연동 설정」을 완료합니다. 이미 앱이 있는 경우 설정 페이지로 바로 이동하여 연동을 계속할 수 있습니다.
| 연동 방식 | 사용 사례 | 작업 경로 |
|---|---|---|
| Agent 자동 연동 | 프로그래밍 어시스턴트가 프로젝트를 분석하여 SDK 연동을 완료하도록 하려는 경우 | 콘솔에서 생성된 프롬프트를 복사하여 앱 코드 저장소에서 프로그래밍 어시스턴트에게 실행하도록 전달 |
| 수동 연동 | SDK를 직접 설치하고 파라미터를 구성하려는 경우 | 데이터 보고 방식을 확인한 후 이 문서와 빠른 시작에 따라 설정 완료 |
Agent 자동 연동¶
- 현재 앱의 설정 페이지에서 「Agent 자동 연동」을 선택합니다.
- 「연동 설정」의 전체 프롬프트를 복사하여 현재 앱의 연동 정보를 사용하도록 합니다.
- 앱 코드 저장소에서 프로그래밍 어시스턴트를 열고 프롬프트를 붙여넣어 Agent가 연동 가이드에 따라 프로젝트를 분석하고 SDK 설정을 완료하도록 합니다.
- 앱을 빌드하고 실행하여 페이지 방문 등의 작업을 트리거한 후, 현재 앱의 탐색기에서 데이터 수신을 확인합니다.
페이지에 사용자 API Key 또는 임시 인증 코드가 준비되지 않았다는 안내가 표시되면, 안내에 따라 보완한 후 프롬프트를 다시 복사하세요.
수동 연동¶
앱 설정 페이지에서 「수동 연동」을 선택하고 데이터 보고 방식을 확인합니다:
- 공용 DataWay: RUM 데이터를 직접 수신하며 DataKit 수집기를 설치할 필요가 없습니다.
- 로컬 환경 배포: 사전 요구 사항을 충족한 후 RUM 데이터를 수신합니다.
아래 설치와 빠른 시작에 따라 SDK 설치, 초기화 및 검증을 완료합니다. 이미 SDK 설정이 있는 경우 먼저 확인하여 재사용하고 중복 초기화를 피해야 합니다.
설치¶
소스 코드 주소: https://github.com/GuanceCloud/datakit-ios
Demo: https://github.com/GuanceDemo/guance-app-demo
CocoaPods 향후 유지 관리 안내
CocoaPods 공식 공지에 따르면, CocoaPods는 2026년 12월 2일 이후 trunk를 읽기 전용 상태로 전환하여 새로운 Podspec을 더 이상 받지 않을 예정입니다. 이미 배포된 Pod 버전과 기존 빌드는 즉시 무효화되지 않지만, 이후 CocoaPods를 통해 새 버전, 호환성 수정 및 보안 업데이트를 가져오는 것이 제한될 수 있습니다. 따라서 새로 SDK를 연동하거나 업그레이드할 때는 Swift Package Manager 방식을 우선적으로 사용하여 통합할 것을 권장합니다.
Using Xcode UI
-
Xcode에서
File->Add Package Dependency...를 선택합니다. -
표시되는 페이지의 검색 상자에
https://github.com/GuanceCloud/datakit-ios.git를 입력합니다. -
Xcode가 패키지를 해석한 후 종속성 버전 규칙을 선택합니다.
Up to Next Major Version을 선택하는 것을 권장합니다.추가할 프로젝트를 선택한 후
Add Package를 클릭하고 로딩이 완료될 때까지 기다립니다. -
패키지 해석이 완료되면 Package Products 목록에서 각 Target에 추가할 제품을 선택하고
Add Package를 클릭합니다.GuanceSDK: 메인 프로젝트 Target에 추가하며 iOS, tvOS, macOS를 지원합니다. 이 중 macOS는 Alpha 버전입니다.GuanceWidgetExtension: iOS Widget Extension Target에만 추가합니다.
Using Package.swift
프로젝트 자체가 Swift Package인 경우 SDK를 종속성으로 추가하고 Package.swift에 dependencies를 추가합니다.
// 메인 프로젝트
dependencies: [
.package(url: "https://github.com/GuanceCloud/datakit-ios.git",
.upToNextMajor(from: "[latest_version]"))
]
Targets에 종속성을 추가합니다:
targets: [
.target(
name: "YourTarget",
dependencies: [
.product(name: "GuanceSDK", package: "GuanceSDK"),
]),
.target(
name: "YourWidgetExtensionTarget",
dependencies: [
.product(name: "GuanceWidgetExtension", package: "GuanceSDK"),
]),
]
주의: 1.4.0-beta.1 이상에서 Swift Package Manager를 지원합니다. SDK 1.6.6 이상 버전에서 SPM 제품 이름이 GuanceSDK, GuanceWidgetExtension, GuanceSessionReplay로 조정되었습니다. 이전 제품 이름 마이그레이션은 마이그레이션 가이드를 참고하세요.
-
Cartfile파일을 구성합니다. -
종속성을 업데이트합니다.
대상 플랫폼(iOS, tvOS 또는 macOS)에 따라 해당
carthage update명령을 실행하고,--use-xcframeworks파라미터를 추가하여 XCFrameworks를 생성합니다:-
iOS 플랫폼의 경우:
-
tvOS 플랫폼의 경우:
-
macOS 플랫폼의 경우:
생성된 xcframework는 일반 Framework와 사용 방법이 동일합니다. 컴파일로 생성된 라이브러리를 프로젝트에 추가합니다.
GuanceSDK: 메인 프로젝트 Target에 추가하며 iOS, tvOS, macOS를 지원합니다. 이 중 macOS는 Alpha 버전입니다.GuanceWidgetExtension: iOS 위젯 Widget Extension Target에만 추가합니다. -
-
TARGETS->Build Setting->Other Linker Flags에-ObjC를 추가합니다. -
Carthage 통합 시 지원 SDK 버전:
GuanceSDK: >=1.6.6GuanceWidgetExtension: >=1.6.6
CocoaPods 적용 안내
CocoaPods 공식 공지에 따르면, CocoaPods는 2026년 12월 2일 이후 trunk를 읽기 전용 상태로 전환하여 새로운 Podspec을 더 이상 받지 않을 예정입니다. 새 프로젝트이거나 종속성 관리 방식을 조정 중인 프로젝트는 위의 Swift Package Manager 방식을 우선적으로 사용하여 SDK를 통합하세요.
-
Podfile파일을 구성합니다.-
Dynamic Library 사용
-
Static Library 사용
-
Podfile파일:use_modular_headers! # 메인 프로젝트 target 'yourProjectName' do pod 'GuanceSDK', :path => '[folder_path]' end # Widget Extension target 'yourWidgetExtensionName' do pod 'GuanceSDK/WidgetExtension', :path => '[folder_path]' endfolder_path:GuanceSDK.podspec이 위치한 폴더의 경로입니다.GuanceSDK.podspec파일:GuanceSDK.podspec파일의s.version과s.source를 수정합니다.Pod::Spec.new do |s| s.name = "GuanceSDK" s.version = "[latest_version]" s.source = { :git => "https://github.com/GuanceCloud/datakit-ios.git", :tag => s.version } ends.version: 지정된 버전으로 수정하며,Sources/Agent/Core/FTSDKVersion.h의SDK_VERSION과 일치시키는 것을 권장합니다.s.source:tag => s.version
-
Widget Extension 호환 표기:
SDK 1.6.6 이상 버전에서는 GuanceSDK/WidgetExtension 사용을 권장합니다. 기존 프로젝트에서 pod 'FTMobileSDK', :subspecs => ['Extension']을 사용하던 경우 GuanceSDK로 업그레이드한 후에도 호환 subspec을 계속 사용할 수 있습니다:
Podfile디렉터리에서pod install을 실행하여 SDK를 설치합니다.
호환 안내: SDK 1.6.6 이상 버전의 메인 Pod 이름은 GuanceSDK입니다. 이전 FTMobileSDK 통합 방식은 1.6.6 이전 버전에 적용됩니다. 1.6.6 이상 버전으로 업그레이드할 때는 마이그레이션 가이드를 참고하여 종속성 이름을 조정하세요.
헤더 파일 추가¶
상세 설정 항목¶
고급 시나리오¶
- 사용자 정의 태그 사용
- 데이터 수집 사용자 정의 규칙
- 데이터 수집 마스킹
- URLSession 사용자 정의 Network 수집
- 동적 설정
- 심볼 파일 업로드
- Widget Extension 데이터 수집
- WebView 데이터 모니터링
- macOS Electron 모니터링
- tvOS 데이터 수집
- 방문자 식별자 Visitor ID
자주 묻는 질문¶
크래시 로그 분석¶
개발 시 Debug 및 Release 모드에서는 Crash 시 캡처된 스레드 백트레이스가 심볼화되어 있습니다. 반면 배포 패키지에는 심볼 테이블이 포함되지 않기 때문에, 예외 스레드의 주요 백트레이스에는 이미지 이름이 표시되고 유효한 코드 심볼로 변환되지 않습니다. 수집된 crash log의 관련 정보는 모두 16진수 메모리 주소여서 크래시 코드를 특정할 수 없으므로, 16진수 메모리 주소를 해당 클래스 및 메서드로 해석해야 합니다.
컴파일 또는 패키징 후 dSYM 파일을 찾는 방법¶
- Xcode에서 dSYM 파일은 일반적으로 컴파일된 .app 파일과 함께 생성되며 같은 디렉터리에 위치합니다.
- 프로젝트를 아카이브한 경우 Xcode의
Window메뉴에서Organizer를 선택한 후 해당 아카이브 파일을 선택합니다. 아카이브 파일을 마우스 오른쪽 버튼으로 클릭하고Show in Finder를 선택하여 Finder에서 해당.xcarchive파일을 찾습니다..xcarchive파일을 마우스 오른쪽 버튼으로 클릭하고Show Package Contents를 선택한 후dSYMs폴더로 이동하면 해당 dSYM 파일을 찾을 수 있습니다.
XCode 컴파일 후 dSYM 파일이 생성되지 않았나요?¶
XCode Release 컴파일은 기본적으로 dSYM 파일을 생성하지만 Debug 컴파일은 기본적으로 생성하지 않습니다. 해당 Xcode 설정은 다음과 같습니다:
Build Settings -> Code Generation -> Generate Debug Symbols -> Yes
Build Settings -> Build Option -> Debug Information Format -> DWARF with dSYM File
bitCode를 활성화한 경우 심볼 테이블을 업로드하는 방법은?¶
bitcode App을 App Store에 업로드할 때 제출 대화 상자에서 심볼 파일(dSYM 파일) 생성 선언을 선택합니다:
- 심볼 테이블 파일을 구성하기 전에 App Store에서 해당 버전에 대응하는 dSYM 파일을 로컬로 다운로드한 후, 스크립트를 사용하여 입력 파라미터에 따라 심볼 테이블 파일을 처리하고 업로드해야 합니다.
- 스크립트를 Xcode 프로젝트의 Target에 통합할 필요가 없으며, 로컬에서 생성된 dSYM 파일로 심볼 테이블 파일을 생성해서도 안 됩니다. 로컬 컴파일로 생성된 dSYM 파일의 심볼 테이블 정보는 모두 숨겨져 있기 때문입니다. 로컬 컴파일로 생성된 dSYM 파일을 업로드하면 복원 결과가 "__hiden#XXX"와 같은 심볼로 나타납니다.
App Store에 배포된 App의 dSYM 파일을 찾는 방법은?¶
| App을 App Store Connect에 업로드할 때의 Distribution options | dSYM 파일 |
|---|---|
| Don’t include bitcode Upload symbols |
Xcode를 통해 찾기 |
| Include bitcode Upload symbols |
iTunes Connect를 통해 찾기 Xcode를 통해 찾기, .bcsymbolmap을 사용하여 난독화 해제 필요. |
| Include bitcode Don’t upload symbols |
Xcode를 통해 찾기, .bcsymbolmap을 사용하여 난독화 해제 필요. |
| Don’t include bitcode Don’t upload symbols |
Xcode를 통해 찾기 |
Xcode를 통해 찾기¶
-
Xcode -> Window -> Organizer -
Archives탭을 선택합니다. -
배포된 아카이브 패키지를 찾아 해당 아카이브 패키지를 마우스 오른쪽 버튼으로 클릭하고
Show in Finder작업을 선택합니다. -
定位된 아카이브 파일을 마우스 오른쪽 버튼으로 클릭하고
패키지 내용 보기작업을 선택합니다. -
dSYMs디렉터리를 선택하면 해당 디렉터리 안에 다운로드된 dSYM 파일이 있습니다.
iTunes Connect를 통해 찾기¶
- App Store Connect에 로그인합니다;
- "내 앱(My Apps)"으로 이동합니다;
- "App Store" 또는 "TestFlight"에서 특정 버전을 선택하고 "빌드 메타데이터(Build Metadata)"를 클릭합니다. 이 페이지에서 "dSYM 다운로드(Download dSYM)" 버튼을 클릭하여 dSYM 파일을 다운로드합니다.
.bcsymbolmap 난독화 해제 처리¶
Xcode를 통해 dSYM 파일을 찾으면 BCSymbolMaps 디렉터리를 볼 수 있습니다.
터미널을 열고 다음 명령을 사용하여 난독화를 해제합니다.
xcrun dsymutil -symbol-map <BCSymbolMaps_path> <.dSYM_path>
충돌 필드를 피하기 위한 전역 변수 추가¶
사용자 정의 필드와 SDK 데이터 간의 충돌을 피하기 위해 태그 이름에 프로젝트 약어 접두사를 추가하는 것을 권장합니다(예: custom_tag_name). 프로젝트에서 사용하는 key 값은 소스 코드에서 확인할 수 있습니다. SDK 전역 변수에 RUM, Log와 동일한 변수가 있는 경우 RUM, Log가 SDK의 전역 변수를 덮어씁니다.






