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 アドレス。RUM アプリケーションから取得します。例: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、単位は byte。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 側のブラックリストフィルタリングを有効にするかどうか。デフォルトは YES。Log と RUM データのフィルタリングをサポートします。SDK 1.6.4 以降でサポート。使用例はブラックリストフィルタリングを参照してください |
| dataFilters | NSDictionary | いいえ | アプリ内のブラックリストルールを設定します。logging と rum の 2 種類のデータをサポートします。SDK 1.6.4 以降でサポート。ルール構文はブラックリストルールを参照してください |
| allowWebViewHost | NSArray<NSString *> | いいえ | SDK 1.6.8+:自動 WebView Bridge の統一 host ホワイトリスト。RUM、Log、Visitor ID のアクセスを同時に制御します。nil はすべて許可、空配列はすべて禁止します。SDK 初期化前に設定してください。ルールと優先順位は WebView データモニタリングを参照してください |
| remoteConfiguration | BOOL | いいえ | リモート設定を有効にするかどうか。デフォルトでは無効です。SDK 初期化前に設定し、有効な送信アドレスと RUM App ID を構成する必要があります。RUM の初期化時またはアプリがフォアグラウンドに戻ったときに、最小間隔で更新を試行します。SDK 1.5.17 以降でサポート。DataKit >= 1.60 またはパブリック Dataway。詳細はリモート設定を参照してください |
| remoteConfigMiniUpdateInterval | int | いいえ | リモート設定の最小更新間隔。単位は秒、デフォルトは 12 時間。この値はリクエスト頻度を制限するものであり、定時リフレッシュ周期ではありません。SDK 1.5.17 以降でサポート |
| remoteConfigFetchCompletionBlock | FTRemoteConfigFetchCompletionBlock | いいえ | SDK 初期化前にグローバルコールバックを登録し、取得結果を受け取って、戻り値のモデルにより設定をカスタマイズ調整します。明示的な更新では、今回のコールバックを渡してグローバルコールバックを上書きできます。初期化と明示的更新の例を参照してください。SDK 1.5.19 以降でサポート |
ブラックリストフィルタリング¶
SDK 1.6.4 以降では、データをローカルキャッシュに書き込む前に RUM と Log データをフィルタリングできます。この機能はデフォルトで有効で、FTSDKConfig.enableDataFilter = NO により SDK 側のフィルタリングを無効にできます。
ブラックリストルールは Guance ワークスペースのブラックリストで一元的に設定でき、SDK が DataKit または DataWay から自動的に取得します。また、FTSDKConfig.dataFilters を通じてアプリ内で設定することもできます。2 つの方法は同一のブラックリストフィルタリング機能に対応し、同時に使用できます。いずれかのルールに一致すると、そのデータは破棄されます。
ブラックリストフィルタリングは lineDataModifier の後、ローカルキャッシュへの書き込み前に実行されます。lineDataModifier とブラックリストフィルタリングを同時に設定した場合、フィルタリングルールは変更後のデータに基づいて判定されます。
enableDataFilterは SDK 側のルール取得とフィルタリングのみを制御します。NOに設定すると、SDK はdataFiltersを適用せず、ワークスペースルールも取得しません。DataKit を使用して送信する場合、ワークスペースのブラックリストは DataKit 側で引き続き実行される可能性があります。Data Filter は SDK のデータ書き込み経路に作用します。ルールが多すぎる場合や正規表現が複雑すぎる場合、データ書き込み性能に影響する可能性があるため、必要なルールのみを設定することを推奨します。
SDK の初期化時にワークスペースのブラックリストルールを直ちに取得し、以降の取得間隔はサーバーが返す pull_interval に従います。サーバーが有効な値を返さない場合、SDK はフォールバック間隔として 10 秒を使用します。pull_interval は秒数または単位付き文字列をサポートします。例:10、30s、2m、1h。
ルール構文¶
Data Filter のルール構文はブラックリストフィルタリングルールとほぼ同じです。完全な構文説明はブラックリストフィルタリングルールを参照してください。
dataFilters の key はデータ分類を表します。現在 SDK がサポートする分類は次のとおりです:
| 分類 | 説明 |
|---|---|
logging |
Log データ |
rum |
RUM データ |
各ルールは { 条件 } で表し、いずれかのルールに一致すると、その分類のデータがフィルタリングされます。ルール内では、データの tag、field フィールド、および source、measurement のデータ型識別フィールドを使用できます。
フィールド値の形式と演算子の意味については、ブラックリストフィルタリングルールのフィールド値形式の説明および演算子の説明を参照してください。
SDK のルール文字列では、フィールド値に配列形式を使用することを推奨します。否定演算子は not in、not match をサポートし、サーバー配信ルールで使用される notin、notmatch、not_in にも互換性があります。
ユーザーのバインドとアンバインド¶
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 のキャッシュデータをクリア¶
FTMobileAgent を使用して未送信のキャッシュデータをクリアします。
データを明示的に同期¶
FTMobileAgent を使用してデータを明示的に同期します。
FTSDKConfig.autoSync = NOの場合にのみ、自身でデータ同期を行う必要があります。旧バージョンのFTMobileConfig.autoSyncも引き続き互換性があります。
動的設定を明示的に同期¶
動的設定に関する機能は動的設定に分割されました。