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;              //debug モード
    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              //debug モード
     config.compressIntakeRequests = true           //送信データを圧縮
     FTMobileAgent.start(withConfigOptions: config)
     //...
     return true
}

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.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 のデータ書き込みパイプラインに作用します。ルールが多すぎる場合や正規表現が複雑すぎる場合は、データ書き込みのパフォーマンスに影響する可能性があります。必要なルールのみを設定することを推奨します。

config.enableDataFilter = YES;
config.dataFilters = @{
    @"logging": @[@"{ source in [ 'df_rum_ios_log' ] and message match [ 'timeout' ] }"],
    @"rum": @[@"{ resource_status match [ '5..' ] }"]
};

config.enableDataFilter = true
config.dataFilters = [
    "logging": ["{ source in [ 'df_rum_ios_log' ] and message match [ 'timeout' ] }"],
    "rum": ["{ resource_status match [ '5..' ] }"]
]

SDK は初期化時にワークスペースのブラックリストルールを即座に取得します。以降の取得間隔は、サーバーが返す pull_interval に従います。サーバーが有効な値を返さない場合、SDK は 10 秒をフォールバック間隔として使用します。pull_interval は秒数または単位付きの文字列（例：10、30s、2m、1h）をサポートします。

ルール構文¶

Data Filter のルール構文はブラックリストフィルタのルールと基本的に同じです。完全な構文の説明は ブラックリストフィルタのルール を参照してください。

dataFilters の key はデータ分類を表します。現在 SDK がサポートしている分類は次のとおりです：

各ルールは { 条件 } で表され、いずれかのルールに一致すると、その分類のデータがフィルタされます。ルールでは、データの tag、field フィールド、および source、measurement のデータ型識別フィールドを使用できます。

フィールド値の形式とオペレータの意味については、ブラックリストフィルタのルールの フィールド値の形式説明 と オペレータ説明 を参照してください。

SDK のルール文字列では、フィールド値は配列形式を使用することを推奨します。否定オペレータは not in、not match をサポートし、サーバーから配信されるルールで使用される notin、notmatch、not_in とも互換性があります。

{ status in [ 'debug' ] and env not in [ 'prod' ] and message not match [ '.*error.*' ] }

ユーザーのバインドとログアウト¶

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 の設定を動的に変更する場合は、誤ったデータの発生を避けるため、先にシャットダウンする必要があります。

+ (void)shutDown;

open class func shutDown()

SDK キャッシュデータのクリア¶

FTMobileAgent を使用して、未送信のキャッシュデータをクリアします。

+ (void)clearAllData;

open class func clearAllData()

データの手動同期¶

FTMobileAgent を使用してデータを手動同期します。

FTSDKConfig.autoSync = NO の場合のみ、データ同期を手動で行う必要があります。旧バージョンの FTMobileConfig.autoSync も引き続き互換性があります。

- (void)flushSyncData;

func flushSyncData()

動的設定の手動同期¶

動的設定に関する機能は 動的設定 に分割されています。