iOS/tvOS/macOS SDK 마이그레이션 가이드¶
읽기 안내¶
이 문서는 버전 내림차순으로 각 버전에서 도입된 마이그레이션 사항을 설명합니다. 각 섹션의 시스템 요구 사항, 호환성 안내 및 예시는 해당 버전을 기준으로 합니다.
버전 간 업그레이드 시 현재 버전과 대상 버전 사이의 마이그레이션 사항을 낮은 버전부터 높은 버전 순서로 확인하고 적용하세요. 중간 버전을 하나씩 설치할 필요는 없습니다. 예를 들어 1.6.6 이전 버전에서 1.6.8로 업그레이드할 때는 1.6.6으로 업그레이드와 1.6.8로 업그레이드를 순서대로 확인해야 합니다. 1.6.7에서 1.6.8로 업그레이드할 때는 1.6.8 섹션만 확인하면 됩니다. 이후 섹션에서 동일한 설정을 변경한 경우에는 대상 버전 범위 내에서 더 최신의 안내를 기준으로 합니다.
1.6.8로 업그레이드¶
최소 시스템 버전¶
SDK 1.6.8은 최소 시스템 버전을 iOS 15, tvOS 15, macOS 12로 상향 조정합니다. 업그레이드 전에 해당 Target의 배포 버전을 조정하고 앱 지원 범위를 확인하세요.
샘플링 설정 마이그레이션¶
| 설정 클래스 | 기존 로컬 속성 | 권장 속성 |
|---|---|---|
FTRumConfig |
sampleRate / samplerate |
sessionSamplingRate |
FTRumConfig |
sessionOnErrorSampleRate |
sessionOnErrorSamplingRate |
FTLoggerConfig |
sampleRate / samplerate |
logSamplingRate |
FTTraceConfig |
sampleRate / samplerate |
traceSamplingRate |
FTSessionReplayConfig |
sampleRate |
sessionReplaySamplingRate |
FTSessionReplayConfig |
sessionReplayOnErrorSampleRate |
sessionReplayOnErrorSamplingRate |
새 로컬 속성은 모두 소수점을 지원하는 [0,100] 백분율입니다. 기존 로컬 정수 속성은 더 이상 사용되지 않는(deprecated) 것으로 표시되었으며, 향후 버전에서 제거될 수 있고 0.1%와 같은 소수 샘플링 비율을 표현할 수 없습니다. 새 속성과 기존 속성은 동일한 샘플링 설정에 기록되며, 두 번 중첩해 샘플링하는 것이 아닙니다. 기존 getter는 정수 부분만 반환합니다.
기존 원격 필드는 [0,1] 비율을 계속 사용하며, 새 원격 필드는 [0,100] 백분율로 변경되었습니다. 둘 다 동시에 유효한 경우 새 필드가 우선합니다. 자세한 내용은 원격 샘플링 설정을 참조하세요.
WebView 호스트 설정 마이그레이션¶
FTRumConfig.allowWebViewHost를 SDK 초기화 전의 FTSDKConfig.allowWebViewHost로 이동하세요. nil은 모든 호스트를 허용하고, 빈 배열은 모든 호스트를 금지합니다. 새 설정은 RUM, Log 및 Visitor ID 액세스에 공통으로 사용됩니다. 자세한 내용은 WebView 데이터 모니터링을 참조하세요.
신규 Visitor ID, NSURLConnection 및 WebView 로그는 모두 명시적으로 구성해야 합니다. 업그레이드 시 이러한 선택적 기능이 자동으로 활성화되지는 않습니다. 두 View 시간 메트릭은 기본 매칭 규칙을 사용하며, 기존에 유효하게 수집된 데이터가 조건을 충족할 때 생성됩니다.
1.6.6으로 업그레이드¶
이 섹션에서는 SDK 1.6.6에서 도입된 제품명 변경과 API 조정을 설명합니다. 이 버전부터 Apple 플랫폼 메인 SDK는 GuanceSDK로 통일되며, iOS, tvOS, macOS가 동일한 메인 SDK를 공유합니다.
macOS Alpha 안내
SDK 1.6.6에서 macOS는 Alpha 버전이며, 모든 iOS 기능이 지원된다고 보장하지 않습니다. macOS를 연동하기 전에 먼저 테스트 환경에서 초기화, RUM, Log, Trace, 데이터 동기화 등 핵심 경로를 검증하세요.
변경 개요¶
- 메인 SDK 라이브러리가
GuanceSDK로 통일되었습니다. datakit-macos는 더 이상 별도로 유지보수되지 않으며, macOS 기능이 현재 SDK 저장소로 통합되었습니다.- Session Replay는 독립 제품
GuanceSessionReplay로 제공되며 iOS만 지원합니다. - Widget Extension은 독립 제품
GuanceWidgetExtension로 제공되며 iOS Widget Extension Target에서만 사용됩니다. - iOS, tvOS, macOS가 메인 SDK를 공유하며, 특정 플랫폼을 지원하지 않는 API는 가용성 표시로 선언됩니다.
| 구성 요소 | iOS | tvOS | macOS |
|---|---|---|---|
GuanceSDK |
지원 | 지원 | Alpha |
GuanceSessionReplay |
지원 | 미지원 | 미지원 |
GuanceWidgetExtension |
지원 | 미지원 | 미지원 |
SDK 1.6.6의 최소 시스템 버전은 다음과 같습니다.
- iOS 12.0+
- tvOS 12.0+
- macOS 10.14+
설치 마이그레이션¶
CocoaPods¶
이전 버전 메인 SDK:
다음으로 변경:
Session Replay가 필요하면:
Widget Extension 데이터 수집이 필요하면 Widget Extension Target에서만 통합하세요. 신규 연동에는 WidgetExtension subspec 사용을 권장합니다.
기존 프로젝트에서 원래 pod 'FTMobileSDK', :subspecs => ['Extension']를 사용했다면 GuanceSDK로 업그레이드한 후에도 호환 subspec을 계속 사용할 수 있습니다.
호환성 안내:
GuanceSDK에는 기본적으로 메인 SDK 기능이 포함됩니다.GuanceSDK/SessionReplay는 iOS만 지원합니다.GuanceSDK/WidgetExtension은 iOS Widget Extension Target에서만 사용됩니다.- 기존
GuanceSDK/FTSessionReplay및GuanceSDK/Extension은 호환 별칭으로 유지됩니다.pod 'GuanceSDK', :subspecs => ['Extension']로 Widget Extension 기능을 계속 통합할 수도 있습니다. 신규 연동에는SessionReplay와WidgetExtension사용을 권장합니다. - macOS Target에는
SessionReplay또는WidgetExtensionsubspec을 통합하지 마세요.
Swift Package Manager¶
SPM 제품명이 새 브랜드 제품명으로 변경되었습니다.
| 이전 제품 | 새 제품 |
|---|---|
FTMobileSDK |
GuanceSDK |
FTSessionReplay |
GuanceSessionReplay |
FTMobileExtension |
GuanceWidgetExtension |
Xcode에서 Swift Package를 추가한 후 Target에 따라 해당 제품을 선택하세요.
- App Target:
GuanceSDK - iOS Session Replay가 포함된 Target:
GuanceSessionReplay - Widget Extension Target:
GuanceWidgetExtension
Swift import:
Session Replay가 필요하면:
Framework / XCFramework¶
Framework 제품명이 변경되었습니다.
| 이전 제품 | 새 제품 |
|---|---|
FTMobileSDK.xcframework |
GuanceSDK.xcframework |
FTSessionReplay.xcframework |
GuanceSessionReplay.xcframework |
FTMobileExtension.xcframework |
GuanceWidgetExtension.xcframework |
Objective-C에서는 새 진입 헤더 파일 사용을 권장합니다.
호환 진입점도 계속 사용할 수 있습니다.
Session Replay 권장 진입점은 통합 방식에 따라 선택하세요.
| 통합 방식 | Objective-C import |
|---|---|
| CocoaPods | #import <GuanceSDK/GuanceSessionReplay.h> |
| Swift Package Manager | @import GuanceSessionReplay; |
| Framework / XCFramework | #import <GuanceSessionReplay/GuanceSessionReplay.h> |
기존 Session Replay 헤더 파일도 계속 호환되어 사용할 수 있습니다. CocoaPods 통합은 GuanceSDK 경로를, Framework / XCFramework 통합은 GuanceSessionReplay 경로를 사용하며, Swift Package Manager는 모듈 import를 직접 사용합니다. |
// CocoaPods
#import <GuanceSDK/FTSessionReplay.h>
// Framework / XCFramework
#import <GuanceSessionReplay/FTSessionReplay.h>
// Swift Package Manager
@import GuanceSessionReplay;
API 마이그레이션¶
초기화 설정¶
새 코드에서는 FTMobileConfig에서 FTSDKConfig로 마이그레이션할 것을 권장합니다.
기존 작성 방식:
FTMobileConfig *config = [[FTMobileConfig alloc] initWithDatakitUrl:datakitUrl];
[FTMobileAgent startWithConfigOptions:config];
새 작성 방식:
FTSDKConfig *config = [[FTSDKConfig alloc] initWithDatakitUrl:datakitUrl];
[FTMobileAgent startWithConfigOptions:config];
설명:
FTMobileConfig는 현재도 사용할 수 있으며FTSDKConfig에서 상속됩니다.FTMobileConfig는 더 이상 사용되지 않습니다(deprecated). 새 코드에서는FTSDKConfig사용을 권장합니다.FTMobileAgent는 계속 시작 진입점으로 사용할 수 있습니다. 새 코드에서는 호환 별칭FTSDKAgent도 사용할 수 있습니다.
샘플링 비율 파라미터 이름¶
samplerate는 표준 카멜 표기법인 sampleRate로 변경되었습니다.
영향을 받는 설정:
FTRumConfigFTTraceConfigFTLoggerConfig
기존 작성 방식:
FTRumConfig *rumConfig = [[FTRumConfig alloc] initWithAppid:appId];
rumConfig.samplerate = 100;
FTTraceConfig *traceConfig = [[FTTraceConfig alloc] init];
traceConfig.samplerate = 100;
FTLoggerConfig *loggerConfig = [[FTLoggerConfig alloc] init];
loggerConfig.samplerate = 100;
새 작성 방식:
FTRumConfig *rumConfig = [[FTRumConfig alloc] initWithAppid:appId];
rumConfig.sampleRate = 100;
FTTraceConfig *traceConfig = [[FTTraceConfig alloc] init];
traceConfig.sampleRate = 100;
FTLoggerConfig *loggerConfig = [[FTLoggerConfig alloc] init];
loggerConfig.sampleRate = 100;
설명:
samplerate는 더 이상 사용되지 않는 것으로 표시되었으며 향후 버전에서 제거될 수 있습니다.sampleRate와samplerate는 동일한 값에 매핑됩니다.- SDK 1.6.6 미만 버전에서는 계속
samplerate를 사용하세요.
Session Replay¶
Session Replay 관련 공용 타입은 계속 FT 접두사를 사용합니다. 예:
기존 작성 방식은 통합 방식에 따라 다른 경로를 사용할 수 있습니다.
새 작성 방식은 통합 방식에 따라 진입 헤더 파일을 선택합니다.
| 통합 방식 | Objective-C import |
|---|---|
| CocoaPods | #import <GuanceSDK/GuanceSessionReplay.h> |
| Swift Package Manager | @import GuanceSessionReplay; |
| Framework / XCFramework | #import <GuanceSessionReplay/GuanceSessionReplay.h> |
| 개인정보 보호 오버레이 기능을 사용해야 한다면 통합 방식에 따라 진입점을 선택하세요. |
| 통합 방식 | 개인정보 보호 오버레이에 필요한 진입점 |
|---|---|
| CocoaPods | #import <GuanceSDK/UIView+FTSRPrivacy.h> |
| Swift Package Manager | @import GuanceSessionReplay; |
| Framework / XCFramework | #import <GuanceSessionReplay/UIView+FTSRPrivacy.h> |
| 새 코드에서는 진입점을 직접 import할 것을 권장합니다. 다음은 Swift Package Manager 작성 방식이며, CocoaPods 또는 Framework / XCFramework 통합에서는 위 표의 해당 경로를 사용하세요. |
Widget Extension¶
Widget Extension 구성 요소는 Widget Extension Target에서만 별도로 통합해야 합니다.
CocoaPods 예시입니다. 신규 연동에는 WidgetExtension subspec 사용을 권장합니다.
기존 프로젝트 업그레이드 시 원래 pod 'FTMobileSDK', :subspecs => ['Extension']를 사용했다면 subspec 형식을 계속 유지할 수도 있습니다.
Swift Package Manager 예시:
// Widget Extension Target에 제품을 추가하세요:
// GuanceWidgetExtension```
Objective-C import는 통합 방식에 따라 선택하세요.
| 통합 방식 | Objective-C import |
| --- | --- |
| CocoaPods | `#import <GuanceSDK/GuanceWidgetExtension.h>` |
| Swift Package Manager | `@import GuanceWidgetExtension;` |
| Framework / XCFramework | `#import <GuanceWidgetExtension/GuanceWidgetExtension.h>` |
Swift Package Manager 예시:
```objc
@import GuanceWidgetExtension;
Framework / XCFramework 예시:
macOS 주의 사항¶
SDK 1.6.6은 macOS를 메인 SDK로 통합하고 Alpha 버전으로 제공합니다. macOS 프로젝트를 마이그레이션할 때:
GuanceSessionReplay를 통합하지 마세요.GuanceWidgetExtension를 통합하지 마세요.- 모든 iOS 기능이 지원된다고 보장하지 않습니다.
API_UNAVAILABLE(macos)로 표시된 API는 호출을 제거하거나 조건부 컴파일을 통해 격리해야 합니다.
예시:
권장 마이그레이션 절차¶
- 먼저 종속성 이름을 업데이트하세요. CocoaPods / SPM / Framework 제품을
GuanceSDK로 전환하세요. - import를 업데이트하세요. Objective-C는 새 진입 헤더 파일을 우선 사용하고, Swift는 해당 제품 모듈의
import진입점을 사용합니다. - 새 코드에서
FTMobileConfig를FTSDKConfig로 교체하세요. samplerate를sampleRate로 교체하세요.- iOS Target에
GuanceSessionReplay가 필요한지 별도로 확인하세요. - Widget Extension Target에
GuanceWidgetExtension가 필요한지 별도로 확인하세요. - macOS Target에서 사용할 수 없는 API를 확인하고 가용성에 따라 코드를 조정하세요.
호환성 안내¶
마이그레이션 비용을 줄이기 위해 SDK 1.6.6은 다음 기존 진입점에 대한 호환 지원을 유지합니다.
FTMobileSDK.hFTMobileAgent.hFTMobileConfigsamplerateFTSessionReplay.h
이러한 호환 진입점은 향후 메이저 버전에서 제거될 수 있습니다. 새 코드에서는 새로운 통합 제품, 진입 헤더 파일 및 표준 이름을 사용할 것을 권장합니다.