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 リポジトリに統合されました。
• セッションリプレイは、独立した製品 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'

セッションリプレイが必要な場合：

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 セッションリプレイを含む Target：GuanceSessionReplay
• Widget Extension Target：GuanceWidgetExtension

Swift の import：

import GuanceSDK

セッションリプレイが必要な場合：

import GuanceSessionReplay

Framework / XCFramework¶

Framework のプロダクト名が変更されました：

Objective-C では、新しいエントリヘッダーファイルの使用を推奨します：

#import <GuanceSDK/GuanceSDK.h>

互換性のあるエントリも引き続き使用できます：

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

セッションリプレイの推奨エントリは、統合方法に応じて選択してください：

// 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 は非推奨です。新しいコードでは 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 を使用してください。

セッションリプレイ¶

セッションリプレイ関連のパブリックタイプは引き続き 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

これらの互換エントリは、将来のメジャーバージョンで削除される可能性があります。新しいコードでは、新しい統合プロダクト、エントリヘッダーファイル、および標準命名規則の使用を推奨します。