콘텐츠로 이동

SDK 초기화

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

Application 설정

최적의 SDK 초기화 위치는 Application의 onCreate 메서드입니다. 애플리케이션에 아직 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);              // 디버그 모드
        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)              // 디버그 모드
        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 아니요 web 데이터와 공존해야 하는 경우 활성화하는 것이 좋습니다. 이 구성은 web 데이터 유형 저장 호환성 문제를 처리하는 데 사용됩니다. 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 초기화 전에 설정해야 하며, 유효한 전송 주소와 RUM App ID를 구성해야 합니다. RUM 초기화 시 또는 앱이 포그라운드로 돌아올 때 최소 간격에 따라 업데이트를 시도합니다. ft-sdk 1.6.12 이상에서 지원되며, DataKit >= 1.60 또는 퍼블릭 Dataway가 필요합니다. 자세한 내용은 원격 구성을 참조하세요.
setRemoteConfigMiniUpdateInterval Int 아니요 원격 구성 최소 업데이트 간격입니다. 단위는 초이며 기본값은 12시간입니다. 이 값은 요청 빈도를 제한하는 값이며 정기 새로 고침 주기가 아닙니다. ft-sdk 1.6.12 이상에서 지원됩니다.
setRemoteConfigurationCallBack FTRemoteConfigManager.FetchResult 아니요 SDK 초기화 전에 전역 콜백을 등록하여 업데이트 결과를 수신하고, 구성을 적용하기 전에 사용자 정의로 조정합니다. 수동 업데이트 시 이번 콜백을 전달하여 전역 콜백을 재정의할 수 있습니다. 초기화 및 수동 업데이트 예시를 참조하세요. 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 이상 버전은 데이터를 로컬 캐시에 쓰기 전에 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)

로컬 및 원격 데이터 필터링을 비활성화하려면 명시적으로 설정하세요:

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

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

사용자 정보 바인딩 및 바인딩 해제

FTSdk를 사용하여 사용자 바인딩 및 바인딩 해제를 수행합니다.

사용 방법

/**
 * 사용자 정보 바인딩
 *
 * @param id 사용자 ID
 */
public static void bindRumUserData(@NonNull String id)

/**
 * 사용자 정보 바인딩
 */
public static void bindRumUserData(@NonNull UserData data)

/**
 * 사용자 정보 바인딩 해제
 */
public static void unbindRumUserData()
/**
 * 사용자 정보 바인딩
 *
 * @param id 사용자 ID
 */
fun bindRumUserData(id: String)

/**
 * 사용자 정보 바인딩
 *
 * @param data 사용자 정보
 */
fun bindRumUserData(data: UserData)

/**
 * 사용자 정보 바인딩 해제
 */
fun unbindRumUserData()

UserData

메서드 이름 설명 필수 주의
setId 사용자 ID 설정 아니요
setName 사용자 이름 설정 아니요
setEmail 이메일 설정 아니요
setExts 사용자 확장 설정 아니요 추가 규칙은 애플리케이션 연결을 참조하세요

코드 예시

// 사용자 로그인 성공 후 이 메서드를 호출하여 사용자 정보를 바인딩할 수 있습니다
FTSdk.bindRumUserData("001");

UserData userData = new UserData();
userData.setName("test.user");
userData.setId("test.id");
userData.setEmail("test@mail.com");
Map<String, String> extMap = new HashMap<>();
extMap.put("ft_key", "ft_value");
userData.setExts(extMap);
FTSdk.bindRumUserData(userData);

// 사용자 로그아웃 후 이 메서드를 호출하여 사용자 정보 바인딩을 해제할 수 있습니다
FTSdk.unbindRumUserData();
// 사용자 로그인 성공 후 이 메서드를 호출하여 사용자 정보를 바인딩할 수 있습니다
FTSdk.bindRumUserData("001")

// 사용자 추가 데이터 바인딩
val userData = UserData()
userData.name = "test.user"
userData.id = "test.id"
userData.email = "test@mail.com"
val extMap = HashMap<String, String>()
extMap["ft_key"] = "ft_value"
userData.setExts(extMap)
FTSdk.bindRumUserData(userData)

// 사용자 로그아웃 후 이 메서드를 호출하여 사용자 정보 바인딩을 해제할 수 있습니다
FTSdk.unbindRumUserData()

런타임 기능

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()

문서 평가

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