SDK 초기화¶
이 문서는 Android SDK 초기화 관련 내용을 다룹니다.
Application 설정¶
SDK를 초기화하기에 가장 적합한 위치는 Application의 onCreate 메서드입니다. 애플리케이션에 Application이 아직 없다면 직접 생성한 후 AndroidManifest.xml에 선언해야 합니다. 예시는 여기를 참고하세요.
기본 설정¶
public class DemoApplication extends Application {
@Override
public void onCreate() {
// 로컬 환경 배포, Datakit 배포
FTSDKConfig config = FTSDKConfig.builder(datakitUrl);
// 공용 DataWay 사용
FTSDKConfig config = FTSDKConfig.builder(datawayUrl, clientToken);
// ...
// config.setDebug(true); // debug 모드
FTSdk.install(config);
}
}
| 메서드 이름 | 유형 | 필수 여부 | 설명 |
|---|---|---|---|
| datakitUrl | String | 예 | 로컬 환경 배포(Datakit)의 데이터 전송 URL 주소. 예: http://10.0.0.1:9529, 포트는 기본 9529이며 SDK가 설치된 기기에서 해당 주소에 접근할 수 있어야 합니다. 참고: datakitUrl과 datawayUrl은 둘 중 하나만 설정해야 합니다 |
| datawayUrl | String | 예 | 공용 Dataway의 데이터 전송 URL 주소. [RUM] 애플리케이션에서 얻을 수 있으며, 예: https://open.dataway.url, SDK가 설치된 기기에서 해당 주소에 접근할 수 있어야 합니다. 참고: datakitUrl과 datawayUrl은 둘 중 하나만 설정해야 합니다 |
| clientToken | String | 예 | 인증 토큰. datawayUrl과 함께 설정해야 합니다 |
| setDebug | Boolean | 아니요 | 디버그 모드 활성화 여부. 기본값은 false이며, 활성화해야 SDK 실행 로그를 출력할 수 있습니다 |
| setEnv | EnvType | 아니요 | 수집 환경 설정. 기본값은 EnvType.PROD입니다 |
| setEnv | String | 아니요 | 수집 환경 설정. 기본값은 prod입니다. 참고: String 또는 EnvType 유형 중 하나만 설정하면 됩니다 |
| setOnlySupportMainProcess | Boolean | 아니요 | 메인 프로세스에서만 실행할지 여부. 기본값은 true이며, 다른 프로세스에서 실행해야 한다면 이 필드를 false로 설정해야 합니다 |
| setAllowWebViewHost | Array | 아니요 | WebView RUM과 Log가 Bridge를 사용할 수 있는 host 범위를 일괄 설정합니다. null은 모든 host 허용을 의미하고, 빈 배열은 Bridge를 자동으로 사용하지 않음을 의미하며, 설정한 host는 해당 하위 도메인도 함께 매칭됩니다. 기본값은 null이며 ft-sdk 1.7.5 이상에서 지원합니다. 자세한 내용은 WebView 모니터링을 참고하세요 |
| setEnableAccessAndroidID | Boolean | 아니요 | Android ID 수집 활성화 여부. 기본값은 true이며 false로 설정하면 device_uuid 필드 데이터를 수집하지 않습니다. 마켓 개인정보 심사 관련 내용은 여기를 참고하세요 |
| addGlobalContext | Dictionary | 아니요 | SDK 전역 속성을 추가합니다. 추가 규칙은 여기를 참고하세요 |
| setServiceName | String | 아니요 | 서비스 이름을 설정합니다. Log 및 RUM의 service 필드 데이터에 영향을 주며 기본값은 df_rum_android입니다 |
| setAutoSync | Boolean | 아니요 | 데이터 수집 후 서버에 자동 동기화할지 여부. 기본값은 true입니다. false인 경우 FTSdk.flushSyncData()를 사용하여 데이터 동기화를 직접 관리합니다 |
| setSyncPageSize | Int | 아니요 | 동기화 요청 항목 수를 설정합니다. SyncPageSize.MINI는 5건, SyncPageSize.MEDIUM은 10건, SyncPageSize.LARGE는 50건이며 기본값은 SyncPageSize.MEDIUM입니다 |
| setCustomSyncPageSize | Enum | 아니요 | 동기화 요청 항목 수를 설정합니다. 범위는 [5,)이며, 요청 항목 수가 클수록 데이터 동기화에 더 많은 컴퓨팅 리소스가 사용되므로 주의하세요. 기본값은 10입니다. 참고: setSyncPageSize와 setCustomSyncPageSize는 하나만 설정하면 됩니다 |
| setSyncSleepTime | Int | 아니요 | 동기화 간격 시간을 설정합니다. 범위는 [0,5000], 단위는 ms, 기본값은 0입니다 |
| enableDataIntegerCompatible | Void | 아니요 | 웹 데이터와 함께 사용해야 하는 경우 활성화하는 것이 좋습니다. 이 설정은 웹 데이터 유형의 저장 호환성 문제를 처리합니다. ft-sdk 1.6.9 버전에서는 기본적으로 활성화됩니다 |
| setNeedTransformOldCache | Boolean | 아니요 | ft-sdk 1.6.0 미만 버전의 기존 캐시 데이터를 호환 동기화할지 여부. 기본값은 false입니다 |
| enableFileDataStore | Void | 아니요 | 파일 캐시를 활성화하여 동기화 캐시와 RUM 집계 데이터에 사용합니다. 기본적으로는 여전히 SQLite 캐시를 사용하며 ft-sdk 1.7.2 이상 버전에서 지원합니다 |
| setUseFileDataStore | Boolean | 아니요 | 파일 캐시 사용 여부를 설정합니다. true를 전달하면 파일 캐시를 사용하고 false를 전달하면 기본 SQLite 캐시를 사용합니다. ft-sdk 1.7.2 이상 버전에서 지원합니다 |
| setFileDataStoreShadow | Boolean | 아니요 | 파일 캐시 섀도우 쓰기를 활성화합니다. 활성화하면 읽기는 여전히 SQLite를 사용하고 쓰기는 파일 캐시에 미러링됩니다. 마이그레이션 전 검증에 사용하며 ft-sdk 1.7.2 이상 버전에서 지원합니다 |
| setCompressIntakeRequests | Boolean | 아니요 | 업로드 동기화 데이터를 deflate 압축합니다. 기본적으로 활성화되어 있으며 false로 설정하면 비활성화할 수 있습니다. ft-sdk 1.6.3 이상 버전에서 이 메서드를 지원합니다 |
| enableLimitWithCacheSize | Void, Long | 아니요 | 전체 캐시 크기 제한을 활성화합니다. 기본값은 100MB이며 단위는 Byte입니다. cacheSize를 전달하면 허용 범위는 [30MB,)입니다. 활성화하면 FTLoggerConfig.setLogCacheLimitCount 및 FTRUMConfig.setRumCacheLimitCount는 적용되지 않습니다. ft-sdk 1.7.2 이상 버전에서 지원합니다 |
| setCacheDiscard | CacheDiscard | 아니요 | 캐시가 크기 상한에 도달한 후의 폐기 전략을 설정합니다. 기본값은 CacheDiscard.DISCARD입니다. DISCARD는 추가되는 데이터를 폐기하고 DISCARD_OLDEST는 가장 오래된 캐시 데이터를 삭제합니다. ft-sdk 1.7.2 이상 버전에서 지원합니다 |
| enableLimitWithDbSize | Void | 아니요 | 더 이상 사용되지 않으며 이전 버전 호환을 위해 유지됩니다. enableLimitWithCacheSize 사용을 권장합니다 |
| setEnableOkhttpRequestTag | Boolean | 아니요 | OkHttp Request에 고유 ResourceID를 자동으로 추가하여 동일한 요청의 높은 동시성 시나리오에 사용합니다. ft-sdk 1.6.10 이상 및 ft-plugin 1.3.5 이상에서 지원합니다 |
| setProxy | java.net.Proxy | 아니요 | 데이터 네트워크 동기화 요청에 Proxy 프록시를 설정합니다. okhttp3만 지원하며 ft-sdk 1.6.10 이상에서 지원합니다 |
| setProxyAuthenticator | okhttp3.Authenticator | 아니요 | 데이터 동기화 네트워크 요청에 Proxy 프록시를 설정합니다. okhttp3만 지원하며 ft-sdk 1.6.10 이상에서 지원합니다 |
| setDns | okhttp3.Dns | 아니요 | 데이터 동기화 네트워크 요청에서 사용자 정의 DNS를 사용하여 도메인 이름 해석을 직접 처리할 수 있습니다. okhttp3만 지원하며 ft-sdk 1.6.10 이상에서 지원합니다 |
| setDataModifier | DataModifier | 아니요 | 단일 필드를 변경합니다. ft-sdk 1.6.11 이상에서 지원하며 사용 예시는 여기를 참고하세요 |
| setLineDataModifier | LineDataModifier | 아니요 | 단일 데이터 항목을 변경합니다. ft-sdk 1.6.11 이상에서 지원하며 사용 예시는 여기를 참고하세요 |
| setEnableDataFilter | Boolean | 아니요 | 블랙리스트 필터링 활성화 여부. 기본값은 true입니다. Logging 및 RUM 데이터 필터링을 지원하며 ft-sdk 1.7.2 이상 버전에서 지원합니다 |
| setDataFilters | HashMap<String, String[]> |
아니요 | 앱 내 블랙리스트 규칙을 설정합니다. logging 및 rum 두 가지 데이터 유형을 지원합니다. 규칙 문법은 블랙리스트 필터링 규칙을 참고하세요. ft-sdk 1.7.2 이상 버전에서 지원합니다 |
| setRemoteConfiguration | Boolean | 아니요 | 데이터 수집 원격 구성 기능 활성화 여부. 기본값은 false입니다. 활성화하면 SDK 초기화 또는 앱 핫 스타트 시 데이터 업데이트가 트리거됩니다. ft-sdk 1.6.12 이상에서 지원합니다. DataKit 버전은 >= 1.60이거나 공용 Dataway를 사용해야 합니다 |
| setRemoteConfigMiniUpdateInterval | Int | 아니요 | 데이터 업데이트 최소 간격을 설정합니다. 단위는 초이며 기본값은 12시간입니다. ft-sdk 1.6.12 이상에서 지원합니다 |
| setRemoteConfigurationCallBack | FTRemoteConfigManager.FetchResult | 아니요 | 원격 구성 결과를 반환합니다. 코드 예시. ft-sdk 1.6.16 이상에서 지원합니다 |
파일 캐시¶
ft-sdk 1.7.2 이상 버전에서는 동기화 캐시와 RUM 집계 데이터를 파일 캐시에 기록할 수 있습니다. 이전 버전에서 원활하게 업그레이드할 수 있도록 SDK는 기본적으로 여전히 SQLite 캐시를 사용합니다. 파일 캐시를 활성화하려면 FTSDKConfig에서 명시적으로 설정하면 됩니다.
파일 캐시 기록을 먼저 검증해야 한다면 섀도우 쓰기를 활성화할 수 있습니다. 활성화하면 SDK는 여전히 SQLite에서 데이터를 읽으면서 쓰기는 파일 캐시에 미러링하며, 검증이 완료된 후 enableFileDataStore로 전환하면 됩니다.
캐시 크기 제한¶
ft-sdk 1.7.2 이상 버전에서는 enableLimitWithCacheSize를 사용하여 SDK 전체 캐시 크기 제한을 설정할 것을 권장합니다. 활성화하면 개별 로그 항목 수 상한인 FTLoggerConfig.setLogCacheLimitCount와 RUM 항목 수 상한인 FTRUMConfig.setRumCacheLimitCount는 적용되지 않습니다.
블랙리스트 필터링¶
ft-sdk 1.7.2 이상 버전에서는 데이터가 로컬 캐시에 기록되기 전에 Logging, RUM 데이터를 필터링할 수 있습니다. 이 기능은 기본적으로 활성화되어 있으며 setEnableDataFilter(false)로 비활성화할 수 있습니다.
블랙리스트 규칙은 Guance 워크스페이스의 블랙리스트에서 일괄 구성할 수 있으며, SDK가 DataKit 또는 Dataway에서 자동으로 가져옵니다. setDataFilters를 통해서도 앱 내에서 구성할 수 있습니다. 두 방식은 동일한 블랙리스트 필터링 기능을 제공하며 동시에 사용할 수 있습니다. 어느 규칙에든 매칭되면 해당 데이터는 폐기됩니다.
setDataFilters는 logging, rum 두 가지 유형의 규칙을 지원합니다. 각 규칙은 { 조건 } 형식으로 표현하며 데이터의 태그, 필드 및 source, measurement, class 등 데이터 유형 식별 필드를 매칭할 수 있습니다. 전체 문법은 블랙리스트 필터링 규칙을 참고하세요.
블랙리스트 필터링은 LineDataModifier 이후, 로컬 캐시 쓰기 이전에 수행됩니다. setLineDataModifier와 블랙리스트 필터링을 함께 구성한 경우 필터링 규칙은 수정된 데이터를 기준으로 판단합니다.
HashMap<String, String[]> filters = new HashMap<>();
filters.put("logging", new String[]{
"{ source in ['custom_log'] and message match ['password'] }"
});
filters.put("rum", new String[]{
"{ source in ['resource'] and status in [404, 503] }"
});
FTSDKConfig config = FTSDKConfig.builder(datawayUrl, clientToken)
.setEnableDataFilter(true)
.setDataFilters(filters);
FTSdk.install(config);
val filters = hashMapOf(
"logging" to arrayOf(
"{ source in ['custom_log'] and message match ['password'] }"
),
"rum" to arrayOf(
"{ source in ['resource'] and status in [404, 503] }"
)
)
val config = FTSDKConfig.builder(datawayUrl, clientToken)
.setEnableDataFilter(true)
.setDataFilters(filters)
FTSdk.install(config)
로컬 및 원격 데이터 필터링을 비활성화하려면 다음과 같이 명시적으로 설정할 수 있습니다.
워크스페이스 블랙리스트 규칙의 가져오기 간격은 서버가 반환하는 pull_interval을 기준으로 합니다. 서버가 유효한 값을 반환하지 않으면 SDK는 10초를 폴백 간격으로 사용합니다. pull_interval은 초 단위 숫자 또는 단위가 포함된 문자열을 지원합니다. 예: 10, 30s, 2m, 1h.
런타임 기능¶
SDK 종료¶
SDK 구성을 동적으로 변경해야 한다면 먼저 SDK를 종료하여 잘못된 데이터가 생성되지 않도록 해야 합니다.
SDK 캐시 데이터 정리¶
FTSdk를 사용하여 전송되지 않은 캐시 데이터를 정리합니다.
자동 데이터 동기화 설정¶
ft-sdk 1.7.3 이상 버전에서는 SDK 초기화 후 캐시 데이터 자동 동기화를 동적으로 활성화하거나 비활성화할 수 있습니다. 비활성화하면 SDK는 여전히 수집 데이터를 로컬 캐시에 기록하지만 수집 후 자동으로 동기화를 트리거하지 않습니다. FTSdk.flushSyncData()와 함께 사용하여 데이터 동기화를 직접 관리할 수 있습니다.
데이터 수동 동기화¶
FTSdk를 사용하여 데이터를 수동으로 동기화합니다.
FTSdk.setAutoSync(false)인 경우에만 데이터 동기화를 직접 수행해야 합니다.