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
}

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를 사용하여 앱 내에서 구성할 수도 있습니다. 두 방식은 동일한 블랙리스트 필터링 기능에 해당하며 동시에 사용할 수 있고, 어떤 규칙이라도 하나라도 매칭되면 해당 데이터는 폐기됩니다.

블랙리스트 필터링은 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()

동적 구성 수동 동기화¶

동적 구성 관련 기능은 동적 구성 문서로 분리되었습니다.