콘텐츠로 이동

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는 정수 부분만 반환합니다.

rumConfig.sessionSamplingRate = 12.5f; // 12.5%, 기본값 100
rumConfig.sessionOnErrorSamplingRate = 100; // 기본값 0
loggerConfig.logSamplingRate = 0.1f; // 0.1%, 10%가 아님
traceConfig.traceSamplingRate = 100;
srConfig.sessionReplaySamplingRate = 20;
srConfig.sessionReplayOnErrorSamplingRate = 100;
rumConfig.sessionSamplingRate = 12.5
rumConfig.sessionOnErrorSamplingRate = 100
loggerConfig.logSamplingRate = 0.1 // 0.1%
traceConfig.traceSamplingRate = 100
srConfig.sessionReplaySamplingRate = 20
srConfig.sessionReplayOnErrorSamplingRate = 100

기존 원격 필드는 [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:

pod 'FTMobileSDK'

다음으로 변경:

pod 'GuanceSDK'

Session Replay가 필요하면:

pod 'GuanceSDK/SessionReplay'

Widget Extension 데이터 수집이 필요하면 Widget Extension Target에서만 통합하세요. 신규 연동에는 WidgetExtension subspec 사용을 권장합니다.

target 'YourWidgetExtension' do
  pod 'GuanceSDK/WidgetExtension'
end

기존 프로젝트에서 원래 pod 'FTMobileSDK', :subspecs => ['Extension']를 사용했다면 GuanceSDK로 업그레이드한 후에도 호환 subspec을 계속 사용할 수 있습니다.

target 'YourWidgetExtension' do
  pod 'GuanceSDK', :subspecs => ['Extension']
end

호환성 안내:

  • 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 또는 WidgetExtension subspec을 통합하지 마세요.

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:

import GuanceSDK

Session Replay가 필요하면:

import GuanceSessionReplay

Framework / XCFramework

Framework 제품명이 변경되었습니다.

이전 제품 새 제품
FTMobileSDK.xcframework GuanceSDK.xcframework
FTSessionReplay.xcframework GuanceSessionReplay.xcframework
FTMobileExtension.xcframework GuanceWidgetExtension.xcframework

Objective-C에서는 새 진입 헤더 파일 사용을 권장합니다.

#import <GuanceSDK/GuanceSDK.h>

호환 진입점도 계속 사용할 수 있습니다.

#import <GuanceSDK/FTMobileSDK.h>
#import <GuanceSDK/FTMobileAgent.h>

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로 변경되었습니다.

영향을 받는 설정:

  • FTRumConfig
  • FTTraceConfig
  • FTLoggerConfig

기존 작성 방식:

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 접두사를 사용합니다. 예:

FTSessionReplayConfig *config = [[FTSessionReplayConfig alloc] init];
config.sampleRate = 100;

기존 작성 방식은 통합 방식에 따라 다른 경로를 사용할 수 있습니다.

#import <FTMobileSDK/FTRumSessionReplay.h>
// 또는
#import <FTSessionReplay/FTRumSessionReplay.h>

새 작성 방식은 통합 방식에 따라 진입 헤더 파일을 선택합니다.

통합 방식 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 통합에서는 위 표의 해당 경로를 사용하세요.
@import GuanceSessionReplay;

Widget Extension

Widget Extension 구성 요소는 Widget Extension Target에서만 별도로 통합해야 합니다.

CocoaPods 예시입니다. 신규 연동에는 WidgetExtension subspec 사용을 권장합니다.

target 'YourWidgetExtension' do
  pod 'GuanceSDK/WidgetExtension'
end

기존 프로젝트 업그레이드 시 원래 pod 'FTMobileSDK', :subspecs => ['Extension']를 사용했다면 subspec 형식을 계속 유지할 수도 있습니다.

target 'YourWidgetExtension' do
  pod 'GuanceSDK', :subspecs => ['Extension']
end

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 예시:

#import <GuanceWidgetExtension/GuanceWidgetExtension.h>

macOS 주의 사항

SDK 1.6.6은 macOS를 메인 SDK로 통합하고 Alpha 버전으로 제공합니다. macOS 프로젝트를 마이그레이션할 때:

  • GuanceSessionReplay를 통합하지 마세요.
  • GuanceWidgetExtension를 통합하지 마세요.
  • 모든 iOS 기능이 지원된다고 보장하지 않습니다.
  • API_UNAVAILABLE(macos)로 표시된 API는 호출을 제거하거나 조건부 컴파일을 통해 격리해야 합니다.

예시:

#if !TARGET_OS_OSX
rumConfig.viewTrackingHandler = handler;
#endif

권장 마이그레이션 절차

  1. 먼저 종속성 이름을 업데이트하세요. CocoaPods / SPM / Framework 제품을 GuanceSDK로 전환하세요.
  2. import를 업데이트하세요. Objective-C는 새 진입 헤더 파일을 우선 사용하고, Swift는 해당 제품 모듈의 import 진입점을 사용합니다.
  3. 새 코드에서 FTMobileConfig를 FTSDKConfig로 교체하세요.
  4. samplerate를 sampleRate로 교체하세요.
  5. iOS Target에 GuanceSessionReplay가 필요한지 별도로 확인하세요.
  6. Widget Extension Target에 GuanceWidgetExtension가 필요한지 별도로 확인하세요.
  7. macOS Target에서 사용할 수 없는 API를 확인하고 가용성에 따라 코드를 조정하세요.

호환성 안내

마이그레이션 비용을 줄이기 위해 SDK 1.6.6은 다음 기존 진입점에 대한 호환 지원을 유지합니다.

  • FTMobileSDK.h
  • FTMobileAgent.h
  • FTMobileConfig
  • samplerate
  • FTSessionReplay.h

이러한 호환 진입점은 향후 메이저 버전에서 제거될 수 있습니다. 새 코드에서는 새로운 통합 제품, 진입 헤더 파일 및 표준 이름을 사용할 것을 권장합니다.

문서 평가

이 페이지가 도움이 되었나요?