콘텐츠로 이동

SDK 초기화

이 문서는 iOS/tvOS/macOS SDK 초기화 및 런타임 기능 관련 내용을 다룹니다.

기본 구성

iOS/tvOS는 일반적으로 AppDelegate에서 초기화합니다. macOS에서는 첫 번째로 표시되는 NSViewControllerviewDidLoad 메서드와 NSWindowControllerwindowDidLoad 메서드 호출이 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 아니요 웹 데이터와 공존해야 하는 경우 활성화하는 것이 좋습니다. 이 구성은 웹 데이터 유형 저장 호환 문제를 처리하는 데 사용됩니다.
compressIntakeRequests BOOL 아니요 업로드 동기화 데이터를 deflate 압축합니다. SDK 1.5.6 이상 버전에서 이 매개변수를 지원하며, 기본값은 비활성화입니다.
enableLimitWithDbSize BOOL 아니요 DB를 사용하여 총 캐시 크기를 제한하는 기능을 활성화합니다. 참고: 활성화하면 FTLoggerConfig.logCacheLimitCountFTRUMConfig.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 측 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 데이터 쓰기 파이프라인에 적용됩니다. 규칙이 너무 많거나 정규 표현식이 너무 복잡하면 데이터 쓰기 성능에 영향을 줄 수 있으므로 필요한 규칙만 구성하는 것이 좋습니다.

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..' ] }"]
]

규칙 구문

Data Filter 규칙 구문은 블랙리스트 필터링 규칙과 기본적으로 동일합니다. 전체 구문 설명은 블랙리스트 필터링 규칙을 참조하세요.

dataFilters의 키는 데이터 분류를 나타내며, 현재 SDK에서 지원하는 분류는 다음과 같습니다:

분류 설명
logging Log 데이터
rum RUM 데이터

각 규칙은 { 조건 }으로 표현되며, 하나의 규칙이라도 일치하면 해당 분류의 데이터가 필터링됩니다. 규칙에서는 데이터의 tag, field 필드를 사용할 수 있습니다.

필드 값 형식과 연산자 의미는 블랙리스트 필터링 규칙의 필드 값 형식 설명연산자 설명을 참조하세요.

SDK 규칙 문자열에서 모든 필드 값은 배열 형식을 사용해야 하며, 역 연산자는 notin, notmatch로 고정됩니다.

{ status in [ 'debug' ] and env notin [ 'prod' ] and message notmatch [ '.*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()

동적 구성 수동 동기화

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

문서 평가

이 페이지가 도움이 되었나요?