콘텐츠로 이동

SDK 초기화

이 문서는 Android SDK 초기화 관련 내용을 설명합니다.

Application 설정

SDK를 초기화하기 가장 좋은 위치는 ApplicationonCreate 메서드입니다. 애플리케이션이 아직 Application을 생성하지 않았다면 Application을 생성하고 AndroidManifest.xml에 선언해야 합니다. 예제는 여기를 참고하세요.

<application
       android:name="YourApplication">
</application>

기본 설정

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);
    }
}
class DemoApplication : Application() {
    override fun onCreate() {
        // 로컬 환경 배포, Datakit 배포
        val config = FTSDKConfig.builder(datakitUrl)
        // 공용 네트워크 DataWay 사용
        val 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. 참고: setSyncPageSizesetCustomSyncPageSize 중 하나만 설정
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.setLogCacheLimitCountFTRUMConfig.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[]> 아니요 로컬 블랙리스트 필터링 규칙 설정. 지원되는 분류는 loggingrum; 일치하는 규칙의 데이터는 폐기됨. 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에서 명시적으로 설정할 수 있습니다.

FTSDKConfig config = FTSDKConfig.builder(datawayUrl, clientToken)
        .enableFileDataStore();

FTSdk.install(config);
val config = FTSDKConfig.builder(datawayUrl, clientToken)
    .enableFileDataStore()

FTSdk.install(config)

파일 캐시 쓰기 상황을 먼저 검증해야 하는 경우 섀도우 쓰기를 활성화할 수 있습니다. 활성화하면 SDK는 여전히 SQLite에서 데이터를 읽고, 쓰기는 동시에 파일 캐시에 미러링됩니다. 검증이 완료되면 enableFileDataStore로 전환하세요.

FTSDKConfig config = FTSDKConfig.builder(datawayUrl, clientToken)
        .setFileDataStoreShadow(true);
val config = FTSDKConfig.builder(datawayUrl, clientToken)
    .setFileDataStoreShadow(true)

캐시 크기 제한

ft-sdk 1.7.2 이상 버전에서는 enableLimitWithCacheSize를 사용하여 SDK 전체 캐시 크기 제한을 설정하는 것을 권장합니다. 활성화하면 개별 로그 항목 수 제한 FTLoggerConfig.setLogCacheLimitCount 및 RUM 항목 수 제한 FTRUMConfig.setRumCacheLimitCount는 적용되지 않습니다.

FTSDKConfig config = FTSDKConfig.builder(datawayUrl, clientToken)
        // 전체 캐시 크기 제한 활성화, 예시는 100MB
        .enableLimitWithCacheSize(100 * 1024 * 1024L)
        // 캐시가 제한에 도달하면 가장 오래된 캐시 데이터 삭제
        .setCacheDiscard(CacheDiscard.DISCARD_OLDEST);

FTSdk.install(config);
val config = FTSDKConfig.builder(datawayUrl, clientToken)
    // 전체 캐시 크기 제한 활성화, 예시는 100MB
    .enableLimitWithCacheSize(100 * 1024 * 1024L)
    // 캐시가 제한에 도달하면 가장 오래된 캐시 데이터 삭제
    .setCacheDiscard(CacheDiscard.DISCARD_OLDEST)

FTSdk.install(config)

블랙리스트 필터링

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)

로컬 및 원격 데이터 필터링을 비활성화하려면 명시적으로 설정할 수 있습니다:

FTSDKConfig.builder(datawayUrl, clientToken)
        .setEnableDataFilter(false);

원격 블랙리스트 가져오기 간격은 서버가 반환한 pull_interval을 따릅니다. 서버가 유효한 값을 반환하지 않으면 SDK는 10초를 기본 간격으로 사용합니다. pull_interval은 초 단위 숫자 또는 단위가 포함된 문자열(예: 10, 30s, 2m, 1h)을 지원합니다.

런타임 기능

SDK 종료

SDK 구성을 동적으로 변경해야 하는 경우 먼저 종료하여 잘못된 데이터가 생성되지 않도록 해야 합니다.

FTSdk.shutDown();
FTSdk.shutDown()

SDK 캐시 데이터 정리

FTSdk를 사용하여 아직 전송되지 않은 캐시 데이터를 정리합니다.

FTSdk.clearAllData();
FTSdk.clearAllData()

자동 동기화 데이터 설정

ft-sdk 1.7.3 이상 버전에서는 SDK 초기화 후 캐시 데이터의 자동 동기화를 동적으로 활성화 또는 비활성화할 수 있습니다. 비활성화하면 SDK는 여전히 수집된 데이터를 로컬 캐시에 기록하지만, 데이터 수집 후 자동 동기화를 트리거하지 않습니다. FTSdk.flushSyncData()와 함께 사용하여 데이터 동기화를 직접 관리할 수 있습니다.

// 자동 동기화 비활성화
FTSdk.setAutoSync(false);

// 자동 동기화 활성화
FTSdk.setAutoSync(true);
// 자동 동기화 비활성화
FTSdk.setAutoSync(false)

// 자동 동기화 활성화
FTSdk.setAutoSync(true)

수동 데이터 동기화

FTSdk를 사용하여 수동으로 데이터를 동기화합니다.

FTSdk.setAutoSync(false)인 경우에만 직접 데이터 동기화를 수행해야 합니다.

FTSdk.flushSyncData();
FTSdk.flushSyncData()

문서 평가

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