SDK 초기화¶
이 문서는 Android SDK 초기화 관련 내용을 설명합니다.
Application 설정¶
SDK를 초기화하기 가장 좋은 위치는 Application의 onCreate 메서드입니다. 애플리케이션이 아직 Application을 생성하지 않았다면 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 | 아니요 | DataKit 호환 블랙리스트 필터링 기능 활성화 여부, 기본값은 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 이상 버전에서는 DataKit 호환 블랙리스트 필터링을 지원하여 데이터를 로컬 캐시에 쓰기 전에 Logging, RUM 데이터를 필터링합니다. 이 기능은 기본적으로 활성화되어 있으며, setEnableDataFilter(false)를 통해 비활성화할 수 있습니다.
블랙리스트 규칙은 로컬 규칙과 원격 규칙으로 나뉩니다:
- 로컬 규칙은
setDataFilters를 통해 설정하며,logging,rum두 가지 유형의 규칙을 지원합니다. - 원격 규칙은 SDK가
/v1/datakit/pull?filters=true를 통해 DataKit 또는 Dataway에서 가져옵니다. - 로컬 규칙과 원격 규칙이 동시에 적용되며, 하나의 규칙이라도 일치하면 해당 데이터는 폐기됩니다.
- 블랙리스트 필터링은
LineDataModifier이후, 로컬 캐시 쓰기 이전에 실행됩니다.setLineDataModifier와 블랙리스트 필터링을 동시에 설정한 경우, 필터링 규칙은 수정된 데이터를 기준으로 판단합니다.
규칙 표현식은 {} 안에 작성해야 하며, in, not in, match, not match 연산자를 지원합니다. 여러 조건은 and / or로 조합할 수 있습니다. 필드 출처는 데이터 태그와 필드를 포함하며, source, measurement, class 등의 데이터 타입 식별 필드도 지원합니다.
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 캐시 데이터 정리¶
FTSdk를 사용하여 아직 전송되지 않은 캐시 데이터를 정리합니다.
자동 동기화 데이터 설정¶
ft-sdk 1.7.3 이상 버전에서는 SDK 초기화 후 캐시 데이터의 자동 동기화를 동적으로 활성화 또는 비활성화할 수 있습니다. 비활성화하면 SDK는 여전히 수집된 데이터를 로컬 캐시에 기록하지만, 데이터 수집 후 자동 동기화를 트리거하지 않습니다. FTSdk.flushSyncData()와 함께 사용하여 데이터 동기화를 직접 관리할 수 있습니다.
수동 데이터 동기화¶
FTSdk를 사용하여 수동으로 데이터를 동기화합니다.
FTSdk.setAutoSync(false)인 경우에만 직접 데이터 동기화를 수행해야 합니다.