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
}
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 두 가지 데이터 유형을 지원합니다. 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를 통해 앱 내에서 구성할 수도 있습니다. 두 방식은 동일한 블랙리스트 필터링 기능에 대응하며 동시에 사용할 수 있습니다. 어느 규칙이든 일치하면 해당 데이터는 폐기됩니다.
블랙리스트 필터링은 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도 여전히 호환됩니다.
동적 구성 직접 동기화¶
동적 구성 관련 기능은 동적 구성으로 분리되었습니다.