コンテンツにスキップ

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 は整数部分のみを返します。

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 ログは、すべて明示的な設定が必要です。アップグレードによってこれらのオプション機能が自動的に有効になることはありません。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:

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 は非推奨です。新規コードでは 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

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

フィードバック

このページは役に立ちましたか?