iOS/tvOS/macOS SDK 移行ガイド¶
本書の読み方¶
本書では、各バージョンで導入された移行項目をバージョンの新しい順に説明します。各セクションのシステム要件、互換性の説明、サンプルは、そのバージョンを基準としています。
バージョンをまたいでアップグレードする場合は、バージョンの古い順に、現在のバージョンとターゲットバージョン間の移行項目を確認して適用してください。中間バージョンを 1 つずつインストールする必要はありません。たとえば、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] パーセントです。古いローカル整数プロパティは非推奨としてマークされており、将来のバージョンで削除される可能性があります。また、0.1% などの小数のサンプリングレートを表現できません。新旧プロパティは同じサンプリング設定に書き込まれるため、サンプリングが 2 重に適用されることはありません。古い getter は整数部分のみを返します。
旧リモートフィールドは引き続き [0,1] の比率を使用し、新しいリモートフィールドは [0,100] パーセントに変更されます。両方が同時に有効な場合は新しいフィールドが優先されます。詳細は リモートサンプリング設定 を参照してください。
WebView ホスト設定の移行¶
FTRumConfig.allowWebViewHost を SDK 初期化前の FTSDKConfig.allowWebViewHost に移動します。nil はすべてのホストを許可し、空の配列はすべてを禁止します。新しい設定は RUM、Log、Visitor ID アクセスに共通で使用されます。詳細は WebView データモニタリング を参照してください。
新しく追加された Visitor ID、NSURLConnection、WebView ログは、すべて明示的な設定が必要です。アップグレードによってこれらのオプション機能が自動的に有効になることはありません。2 つの 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は非推奨です。新規コードでは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
これらの互換エントリは将来のメジャーバージョンで削除される可能性があります。新規コードでは、新しい統合製品、エントリヘッダーファイル、標準命名の使用を推奨します。