iOS/tvOS/macOS 1.6.6 마이그레이션 가이드¶

이 문서는 구버전 iOS SDK / macOS SDK에서 SDK 1.6.6 이상 버전으로 마이그레이션하는 프로젝트를 대상으로 합니다. 1.6.6부터 Apple 플랫폼 메인 SDK가 GuanceSDK로 통합되어 iOS, tvOS, macOS가 동일한 메인 SDK를 사용합니다.

변경 사항 개요¶

• 메인 SDK 라이브러리가 GuanceSDK로 통합되었습니다.
• datakit-macos는 더 이상 별도로 유지보수되지 않으며, macOS 기능이 현재 SDK 저장소에 통합되었습니다.
• Session Replay는 독립 제품 GuanceSessionReplay으로 제공되며, iOS만 지원합니다.
• Widget Extension은 독립 제품 GuanceWidgetExtension으로 제공되며, iOS Widget Extension Target 전용입니다.
• iOS, tvOS, macOS는 메인 SDK를 공유합니다. 특정 플랫폼에서 지원되지 않는 API는 가용성 마크를 통해 선언됩니다.

최소 시스템 버전은 릴리스 패키지 구성에 정의됩니다:

• 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 제품명이 새로운 브랜드 제품명으로 변경되었습니다:

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 제품명이 변경되었습니다:

Objective-C는 새로운 진입 헤더 파일 사용을 권장합니다:

#import <GuanceSDK/GuanceSDK.h>

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

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

Session Replay 권장 진입은 통합 방식에 따라 선택하세요:

// 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는 현재 계속 사용할 수 있지만 더 이상 사용되지 않습니다(deprecated).
• 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>

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

@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 주의사항¶

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를 확인하고 가용성에 따라 코드를 조정합니다.

호환성 설명¶

마이그레이션 비용을 줄이기 위해 다음 기존 진입점은 현재 계속 호환되어 사용할 수 있습니다:

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

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