SDK 初期化¶
本ドキュメントでは、iOS/tvOS/macOS SDK の初期化とランタイム機能に関する内容を説明します。
基本設定¶
iOS/tvOS では通常、AppDelegate で初期化します。macOS では、最初に表示される NSViewController の viewDidLoad メソッドや NSWindowController の windowDidLoad メソッドが AppDelegate の applicationDidFinishLaunching よりも先に呼び出されるため、最初のビューのライフサイクル収集における異常を避けるため、main.m または main.swift で SDK を初期化することを推奨します。
-(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions{
// SDK FTSDKConfig 設定
// ローカル環境、Datakit 環境でのデプロイ
//FTSDKConfig *config = [[FTSDKConfig alloc]initWithDatakitUrl:datakitUrl];
// パブリック DataWay を使用したデプロイ
FTSDKConfig *config = [[FTSDKConfig alloc]initWithDatawayUrl:datawayUrl clientToken:clientToken];
//config.enableSDKDebugLog = YES; //デバッグモード
config.compressIntakeRequests = YES;
//SDK 起動
[FTMobileAgent startWithConfigOptions:config];
//...
return YES;
}
// main.m ファイル
#import <Cocoa/Cocoa.h>
#import <GuanceSDK/GuanceSDK.h>
int main(int argc, const char * argv[]) {
@autoreleasepool {
// ローカル環境、Datakit 環境でのデプロイ
FTSDKConfig *config = [[FTSDKConfig alloc] initWithDatakitUrl:datakitUrl];
// パブリック DataWay を使用したデプロイ
// FTSDKConfig *config = [[FTSDKConfig alloc] initWithDatawayUrl:datawayUrl clientToken:clientToken];
config.enableSDKDebugLog = YES;
[FTSDKAgent startWithConfigOptions:config];
}
return NSApplicationMain(argc, argv);
}
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
// SDK FTSDKConfig 設定
// ローカル環境、Datakit 環境でのデプロイ
//let config = FTSDKConfig(datakitUrl: url)
// パブリック DataWay を使用したデプロイ
let config = FTSDKConfig(datawayUrl: datawayUrl, clientToken: clientToken)
//config.enableSDKDebugLog = true //デバッグモード
config.compressIntakeRequests = true //データ圧縮アップロード
FTMobileAgent.start(withConfigOptions: config)
//...
return true
}
main.swift ファイルを作成し、AppDelegate.swift から @main または @NSApplicationMain を削除します。
import Cocoa
import GuanceSDK
let delegate = AppDelegate()
NSApplication.shared.delegate = delegate
let config = FTSDKConfig(datakitUrl: datakitUrl)
// パブリック DataWay を使用したデプロイ
// let config = FTSDKConfig(datawayUrl: datawayUrl, clientToken: clientToken)
config.enableSDKDebugLog = true
FTSDKAgent.start(withConfigOptions: config)
_ = NSApplicationMain(CommandLine.argc, CommandLine.unsafeArgv)
初期化設定の名称
SDK 1.6.6 以降では、新しいコードでは FTSDKConfig を使用することを推奨します。FTMobileConfig は引き続き互換性を保って使用でき、FTSDKConfig を継承しています。1.6.6 未満のバージョンでは引き続き FTMobileConfig を使用してください。
| 属性 | 型 | 必須 | 説明 |
|---|---|---|---|
| datakitUrl | NSString | はい | ローカル環境(Datakit)のアップロード URL アドレス。例:http://10.0.0.1:9529、ポートはデフォルトで 9529。SDK をインストールするデバイスからこのアドレスにアクセスできる必要があります。注意:datakitUrl と datawayUrl はどちらか一方のみを設定してください |
| datawayUrl | NSString | はい | パブリック DataWay のアップロード URL アドレス。[ユーザーアクセス監視] アプリから取得します。例:https://open.dataway.url。SDK をインストールするデバイスからこのアドレスにアクセスできる必要があります。注意:datakitUrl と datawayUrl はどちらか一方のみを設定してください |
| clientToken | NSString | はい | 認証トークン。datawayUrl と併用する必要があります |
| enableSDKDebugLog | BOOL | いいえ | ログ出力を許可するかどうかを設定します。デフォルトは NO |
| env | NSString | いいえ | 収集環境を設定します。デフォルトは prod。カスタム設定も可能で、提供されている FTEnv 列挙型を使用して -setEnvWithType: メソッドで設定することもできます |
| service | NSString | いいえ | 所属するサービスまたは業務の名前を設定します。Log と RUM の service フィールドデータに影響します。デフォルトは iOS が df_rum_ios、tvOS が df_rum_tvos、macOS が df_rum_macos です |
| globalContext | NSDictionary | いいえ | カスタムタグを追加します。追加ルールは こちら を参照してください |
| groupIdentifiers | NSArray | いいえ | 収集対象の iOS Widget Extensions に対応する AppGroups Identifier の配列。Widget Extensions のデータ収集を有効にする場合は、App Groups を設定し、Identifier をこのプロパティに設定する必要があります。macOS は Widget Extension をサポートしていません |
| autoSync | BOOL | いいえ | データ収集後に自動的にサーバーに同期するかどうか。デフォルトは YES。NO の場合、iOS/tvOS では [[FTMobileAgent sharedInstance] flushSyncData]、macOS では [[FTSDKAgent sharedInstance] flushSyncData] を使用してデータ同期を管理します |
| syncPageSize | int | いいえ | 同期リクエストのエントリ数を設定します。範囲 [5,)。注意:リクエストエントリ数が大きいほど、データ同期に多くの計算リソースを消費します。デフォルトは 10 |
| syncSleepTime | int | いいえ | 同期の間隔を設定します。範囲 [0,5000]。デフォルトは設定なし |
| enableDataIntegerCompatible | BOOL | いいえ | Web データと共存する必要がある場合は、有効にすることを推奨します。この設定は Web データ型の保存互換性問題を処理するために使用します |
| compressIntakeRequests | BOOL | いいえ | アップロードデータを deflate 圧縮します。SDK 1.5.6 以降でサポート。デフォルトはオフ |
| enableLimitWithDbSize | BOOL | いいえ | DB を使用して総キャッシュサイズを制限する機能を有効にします。注意: 有効にすると FTLoggerConfig.logCacheLimitCount および FTRUMConfig.rumCacheLimitCount は無効になります。SDK 1.5.8 以降でサポート |
| dbCacheLimit | long | いいえ | DB キャッシュの制限サイズ。範囲 [30MB,)。デフォルトは 100MB、単位はバイト。SDK 1.5.8 以降でサポート |
| dbDiscardType | FTDBCacheDiscard | いいえ | データベース内のデータ破棄ルールを設定します。デフォルトは FTDBDiscard。FTDBDiscard はデータ数が最大値を超えた場合、追加データを破棄します。FTDBDiscardOldest はデータ数が最大値を超えた場合、古いデータを破棄します。SDK 1.5.8 以降でサポート |
| dataModifier | FTDataModifier | いいえ | 単一フィールドを変更します。SDK 1.5.16 以降でサポート。使用例は データ収集マスキング を参照してください |
| lineDataModifier | FTLineDataModifier | いいえ | 単一データ行を変更します。SDK 1.5.16 以降でサポート。使用例は データ収集マスキング を参照してください |
| enableDataFilter | BOOL | いいえ | SDK 側の DataKit 互換データフィルタリングを有効にするかどうか。ローカルフィルタリングルールとリモートフィルタリングルールを含みます。デフォルトは YES。SDK 1.6.4 以降でサポート。使用例は データフィルタリング を参照してください |
| dataFilters | NSDictionary | いいえ | App ローカルで管理するデータフィルタリングルール。サポートされるカテゴリ:logging、rum。SDK 1.6.4 以降でサポート。ルールの構文は ブラックリストルール を参照してください |
| remoteConfiguration | BOOL | いいえ | データ収集のリモート設定機能を有効にするかどうか。デフォルトでは有効になりません。有効にすると、SDK 初期化時またはアプリのホットスタート時にデータ更新がトリガーされます。SDK 1.5.17 以降でサポート。Datakit バージョン要件 >=1.60 またはパブリック DataWay を使用 |
| remoteConfigMiniUpdateInterval | int | いいえ | リモート動的設定の最小更新間隔を設定します。単位は秒。デフォルトは 12 時間。SDK 1.5.17 以降でサポート |
| remoteConfigFetchCompletionBlock | FTRemoteConfigFetchCompletionBlock | いいえ | リモート設定結果のコールバック。プル結果を受け取り、設定モデルをカスタム調整するために使用します。SDK 1.5.19 以降でサポート。使用例は こちら を参照してください |
ブラックリストフィルタリング¶
Data Filter は、SDK がローカルキャッシュに書き込む前に、ルールに基づいて RUM と Log データをフィルタリングするために使用されます。フィルタリングルールに一致したデータはローカルキャッシュに入らず、アップロードもされません。
- ローカルルール:
FTSDKConfig.dataFiltersで設定され、App が SDK 初期化時に配信します。 -
リモートルール:
FTSDKConfig.enableDataFilterを有効にすると、SDK は Studio 側で追加されたブラックリストルールをプルします。 -
ローカルルールとリモートルールは同時に有効になり、いずれかのルールに一致した場合、そのデータは破棄されます。
- ブラックリストフィルタリングは
lineDataModifierの後、ローカルキャッシュ書き込みの前に実行されます。lineDataModifierとブラックリストフィルタリングの両方を設定している場合、フィルタリングルールは変更後のデータに基づいて判断されます。
Data Filter は SDK データ書き込みパスに作用します。ルールが多すぎたり、正規表現が複雑すぎると、データ書き込みパフォーマンスに影響を与える可能性があるため、必要なルールのみを設定することを推奨します。
ルール構文¶
Data Filter のルール構文は、ブラックリストフィルタリングルールと基本的に同じです。完全な構文の説明は ブラックリストフィルタリングルール を参照してください。
dataFilters のキーはデータカテゴリを示します。現在 SDK がサポートするカテゴリは次のとおりです:
| カテゴリ | 説明 |
|---|---|
logging |
Log データ |
rum |
RUM データ |
各ルールは { 条件 } で表され、いずれかのルールに一致すると、そのカテゴリのデータがフィルタリングされます。ルールではデータの tag、field フィールドを使用できます。
フィールド値の形式と演算子のセマンティクスについては、ブラックリストフィルタリングルールの フィールド値形式の説明 と 演算子の説明 を参照してください。
SDK のルール文字列内のすべてのフィールド値は 配列形式 を使用し、否定演算子は常に notin、notmatch と記述します。
ユーザーのバインドとログアウト¶
FTMobileAgent を使用してユーザー情報をバインドし、現在のユーザーをログアウトします。
/// ユーザー情報をバインドします。ユーザーがログイン成功した後にこのメソッドを呼び出してユーザー情報をバインドできます。
///
/// - Parameters:
/// - Id: ユーザーID
/// - userName: ユーザー名(オプション)
/// - userEmail: ユーザーメールアドレス(オプション)
/// - extra: ユーザーの追加情報(オプション)
- (void)bindUserWithUserID:(NSString *)Id userName:(nullable NSString *)userName userEmail:(nullable NSString *)userEmail extra:(nullable NSDictionary *)extra;
/// 現在のユーザーをログアウトします。ユーザーがログアウトした後にこのメソッドを呼び出してユーザー情報をバインド解除できます。
- (void)unbindUser;
/// ユーザー情報をバインドします。ユーザーがログイン成功した後にこのメソッドを呼び出してユーザー情報をバインドできます。
///
/// - Parameters:
/// - Id: ユーザーID
/// - userName: ユーザー名(オプション)
/// - userEmail: ユーザーメールアドレス(オプション)
/// - extra: ユーザーの追加情報(オプション)
open func bindUser(withUserID Id: String, userName: String?, userEmail: String?, extra: [AnyHashable : Any]?)
/// 現在のユーザーをログアウトします。ユーザーがログアウトした後にこのメソッドを呼び出してユーザー情報をバインド解除できます。
open func unbindUser()
extra の追加ルールに関する注意事項は こちら を参照してください。
ランタイム機能¶
SDK の停止¶
FTMobileAgent を使用して SDK を停止する場合は、必ずメインスレッドで呼び出してください。そうしないと、スレッドセーフの問題が発生する可能性があります。SDK の設定を動的に変更する場合は、誤ったデータの発生を防ぐために、まず SDK を停止する必要があります。
SDK キャッシュデータのクリア¶
FTMobileAgent を使用して、未アップロードのキャッシュデータをクリアします。
データの手動同期¶
FTMobileAgent を使用してデータを手動で同期します。
FTSDKConfig.autoSync = NOの場合にのみ、手動でデータ同期を実行する必要があります。旧バージョンのFTMobileConfig.autoSyncも引き続き互換性があります。
動的設定の手動同期¶
動的設定に関する機能は 動的設定 に分割されています。