SDK 초기화¶
이 문서는 HarmonyOS SDK 초기화 및 런타임 기능 관련 내용을 다룹니다.
기본 설정¶
EntryAbility.ets에서 SDK를 초기화합니다:
import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { FTSDK, FTSDKConfig, EnvType, SDKLogLevel, SyncPageSize} from '@guancecloud/ft_sdk/Index';
const DOMAIN = 0x0000;
export default class EntryAbility extends UIAbility {
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
this.initFTSDK();
}
private initFTSDK(): void {
try {
// 로컬 환경 배포(Datakit)
// const sdkConfig = FTSDKConfig.builder(datakitUrl);
// 퍼블릭 DataWay
const sdkConfig = FTSDKConfig.builder(datawayUrl, clientToken)
.setDebug(true)
.setSdkLogLevel(SDKLogLevel.D)
.setServiceName('Your-App-Name')
.setEnv(EnvType.PROD) // 또는 문자열 사용: .setEnv('prod')
.addGlobalContext('app_channel', new String('appgallery'))
.setAutoSync(true)
.setSyncPageSize(SyncPageSize.MEDIUM)
.setDataSyncRetryCount(5)
.setSyncSleepTime(0)
.setCompressIntakeRequests(true);
FTSDK.install(sdkConfig, this.context);
hilog.info(DOMAIN, 'FTSDK', 'FT SDK initialized successfully');
} catch (error) {
const errorObj: object = error as object;
hilog.error(DOMAIN, 'FTSDK', `Failed to initialize FT SDK: ${JSON.stringify(errorObj)}`);
}
}
}
| 메서드 이름 | 타입 | 필수 | 설명 |
|---|---|---|---|
datakitUrl |
string |
업로드 전 구성 필요 또는 DataWay 선택 | 로컬 환경 배포(DataKit) 업로드 URL 주소입니다. 예: http://10.0.0.1:9529. 기기가 해당 주소에 액세스할 수 있어야 합니다. 런타임에 보완할 수 있으며, 자세한 내용은 동적 주소 업데이트를 참고하세요. |
datawayUrl |
string |
업로드 전 구성 필요 또는 DataKit 선택 | 퍼블릭 DataWay 업로드 URL 주소입니다. [실제 사용자 모니터링(RUM)] 애플리케이션에서 가져옵니다. 예: https://open.dataway.url. 런타임에 보완할 수 있으며, datakitUrl과 둘 중 하나를 선택합니다. |
clientToken |
string |
DataWay 모드에서 필수 | 인증 Token이며, datawayUrl과 함께 구성해야 합니다. |
setDebug |
boolean |
아니요 | SDK 내부 진단 로그 활성화 여부, 기본값 false |
setSdkLogLevel |
SDKLogLevel |
아니요 | SDK 내부 로그 출력 레벨을 설정합니다. 자세한 내용은 문제 해결을 참고하세요. |
setEnableInnerLogFile |
enable: boolean, config?: FTInnerLogFileConfig |
아니요 | SDK 내부 로그를 로컬 파일에 기록할지 여부, 기본값 false. 자세한 내용은 문제 해결을 참고하세요. |
setEnv |
string \| EnvType |
아니요 | 환경, 기본값 prod. EnvType 열거형 또는 문자열을 전달할 수 있습니다. |
setServiceName |
string |
아니요 | 소속 비즈니스 또는 서비스 이름, 기본값 df_rum_harmonyos |
addGlobalContext |
key: string, value: object |
아니요 | SDK 전역 속성을 추가합니다. 추가 규칙은 여기를 참고하세요. |
setAutoSync |
boolean |
아니요 | 데이터 수집 후 서버로 자동 동기화할지 여부, 기본값 true. false로 설정하면 FTSDK.flushSyncData()를 사용하여 데이터 동기화를 직접 관리할 수 있습니다. |
setSyncPageSize |
SyncPageSize |
아니요 | 사전 정의된 동기화 요청 항목 수를 설정합니다. MINI는 5개, MEDIUM은 10개, LARGE는 50개이며, 기본값은 SyncPageSize.MEDIUM입니다. |
setCustomSyncPageSize |
number |
아니요 | 동기화 요청 항목 수를 사용자 지정합니다. 범위는 [5, 500]이며 소수점은 내림 처리됩니다. 기본값은 10입니다. setSyncPageSize와 둘 중 하나만 구성합니다. |
setDataSyncRetryCount |
number |
아니요 | 단일 데이터 동기화의 최대 재시도 횟수를 설정합니다. 범위는 [0, 5]이며 소수점은 내림 처리됩니다. 기본값은 5입니다. |
setSyncSleepTime |
number |
아니요 | 연속 동기화 요청 사이의 대기 시간을 설정합니다. 범위는 [0, 5000]이며 단위는 밀리초입니다. 기본값은 0입니다. |
setCompressIntakeRequests |
boolean |
아니요 | 업로드 데이터에 zlib으로 래핑된 deflate 압축을 사용할지 여부, 기본값 true. 압축을 사용할 수 없으면 평문 업로드로 대체됩니다. |
setProxy |
FTProxyConfig \| null |
아니요 | SDK 데이터 업로드 요청에 사용할 HTTP 프록시를 설정합니다. null을 전달하면 프록시 구성을 지울 수 있습니다. |
setProxyAuthenticator |
FTProxyAuthenticator \| null |
아니요 | 업로드 프록시의 인증 정보를 설정합니다. null을 전달하면 독립 인증 구성을 지울 수 있습니다. |
setDns |
FTDnsConfig \| null |
아니요 | SDK 데이터 업로드 요청에 사용할 DNS 서버 또는 DNS over HTTPS 주소를 설정합니다. null을 전달하면 DNS 구성을 지울 수 있습니다. |
setDataModifier |
DataModifier \| null |
아니요 | 단일 필드를 수정하거나 마스킹합니다. null을 반환하면 원래 값을 유지합니다. 자세한 내용은 데이터 수집 마스킹을 참고하세요. |
setLineDataModifier |
LineDataModifier \| null |
아니요 | 단일 데이터의 기존 필드를 일괄 수정하거나 마스킹합니다. 자세한 내용은 데이터 수집 마스킹을 참고하세요. |
setEnableDataFilter |
boolean |
아니요 | DataKit과 호환되는 로컬 및 원격 블랙리스트 필터링 기능을 활성화할지 여부, 기본값 true. Logging 및 RUM 데이터 필터링을 지원합니다. 자세한 내용은 블랙리스트 필터링을 참고하세요. |
setDataFilters |
FTDataFilters \| null |
아니요 | 로컬 블랙리스트 필터링 규칙을 설정합니다. logging, rum 두 가지 규칙을 지원합니다. null을 전달하면 로컬 규칙을 비울 수 있습니다. 자세한 내용은 블랙리스트 필터링을 참고하세요. |
setAllowWebViewHost |
Array<string> \| null |
아니요 | WebView RUM 및 Replay에서 Bridge를 사용하는 Host 범위를 일괄 설정합니다. null은 모든 Host를 허용하고, 빈 배열은 Bridge 수집을 비활성화하며, 비어 있지 않은 배열은 지정된 Host 및 해당 하위 도메인과 일치합니다. 이 구성은 Bridge 선택에 사용되며 페이지 출처 보안 검증 메커니즘으로 사용되지 않습니다. |
setEnableAccessDeviceID |
boolean |
아니요 | 시스템 기기 식별자를 device_uuid로 사용할지 여부, 기본값 false. 비활성화하면 SDK가 영구 저장한 프라이버시 UUID를 사용합니다. 런타임 전환 방법은 기기 식별자 동적 활성화 및 비활성화를 참고하세요. |
setOnlySupportMainProcess |
boolean |
아니요 | 주 프로세스에서만 초기화할지 여부, 기본값 true. 하위 프로세스를 모니터링해야 하는 경우 설치 전에 false로 설정합니다. |
setRemoteConfiguration |
boolean |
아니요 | 데이터 수집의 원격 구성 기능을 활성화할지 여부, 기본값 false. 활성화하면 SDK는 RUM 구성 설치가 완료되고 유효한 업로드 주소가 있을 때 구성을 가져옵니다. |
setRemoteConfigMiniUpdateInterval |
number |
아니요 | 데이터 업데이트 최소 간격을 설정합니다. 단위는 초이며, 기본값은 12시간입니다. |
setRemoteConfigurationCallBack |
FTRemoteConfigFetchResult \| null |
아니요 | 원격 구성 결과 콜백입니다. 코드 예제를 참고하세요. |
setNeedTransformOldCache |
boolean |
아니요 | 이전 캐시 데이터를 마이그레이션할지 여부, 기본값 false. 처음 FileStore로 전환하면서 기존 SQLite 캐시를 보존해야 할 때 활성화합니다. ft-sdk 0.1.17 이상 버전에서 지원됩니다. |
enableFileDataStore |
Void |
아니요 | 파일 캐시를 활성화하며, 동기화 캐시 및 RUM 집계 데이터에 사용됩니다. 기본적으로 여전히 SQLite 캐시를 사용합니다. ft-sdk 0.1.17 이상 버전에서 지원됩니다. |
setUseFileDataStore |
boolean |
아니요 | 파일 캐시 사용 여부를 설정합니다. true를 전달하면 FileStore를 사용하고, false를 전달하면 기본 SQLite 캐시를 사용합니다. ft-sdk 0.1.17 이상 버전에서 지원됩니다. |
setFileDataStoreShadow |
boolean |
아니요 | 파일 캐시 섀도 쓰기를 활성화합니다. 활성화하면 읽기 및 업로드는 여전히 SQLite를 사용하며, 동시에 쓰기를 FileStore에 미러링하여 마이그레이션 전 검증에 사용합니다. ft-sdk 0.1.17 이상 버전에서 지원됩니다. |
enableLimitWithCacheSize |
cacheSize?: number |
아니요 | 전체 캐시 크기 제한을 활성화합니다. 기본값은 100MB이며 단위는 Byte입니다. 전달 값의 최소값은 30MB입니다. 활성화하면 Log 및 RUM의 항목 수 제한이 무효화됩니다. ft-sdk 0.1.17 이상 버전에서 지원됩니다. |
setCacheDiscard |
CacheDiscard |
아니요 | 캐시가 크기 상한에 도달한 후의 삭제 정책을 설정합니다. 기본값은 CacheDiscard.DISCARD입니다. DISCARD는 새로 추가된 데이터를 삭제하고, DISCARD_OLDEST는 가장 오래된 캐시 데이터를 삭제합니다. ft-sdk 0.1.17 이상 버전에서 지원됩니다. |
enableLimitWithDbSize |
cacheSize?: number |
아니요 | 사용 중단되었으며 이전 버전 호환성을 위해 유지됩니다. enableLimitWithCacheSize 사용을 권장합니다. |
setDbCacheDiscard |
DBCacheDiscard |
아니요 | 사용 중단되었으며 이전 버전 호환성을 위해 유지됩니다. setCacheDiscard 사용을 권장합니다. |
동적 구성 및 런타임 업로드 주소 업데이트 사용 방법은 동적 구성 및 동적 주소 업데이트를 참고하세요.
파일 캐시¶
ft-sdk 0.1.17 이상 버전은 동기화 캐시 및 RUM 집계 데이터를 파일 캐시에 기록하는 것을 지원합니다. 원활한 업그레이드를 위해 SDK는 기본적으로 여전히 SQLite 캐시를 사용합니다. 파일 캐시를 활성화하려면 FTSDKConfig에서 명시적으로 활성화할 수 있습니다.
파일 캐시 쓰기 상황을 먼저 검증하려면 섀도 쓰기를 활성화할 수 있습니다. 활성화하면 SDK는 여전히 SQLite에서 데이터를 읽고 업로드하며, 동시에 쓰기를 FileStore에 미러링합니다. 검증이 완료되면 enableFileDataStore()로 전환합니다.
캐시 크기 제한¶
ft-sdk 0.1.17 이상 버전에서는 enableLimitWithCacheSize를 사용하여 SDK 전체 캐시 크기 제한을 구성하는 것을 권장합니다. 활성화하면 개별 로그 항목 수 상한 FTLoggerConfig.setLogCacheLimitCount 및 RUM 항목 수 상한 FTRUMConfig.setRumCacheLimitCount가 무효화됩니다.
import { CacheDiscard, FTSDKConfig } from '@guancecloud/ft_sdk/Index';
const sdkConfig = FTSDKConfig.builder(datawayUrl, clientToken)
// 전체 캐시 크기 제한을 활성화합니다. 예시는 100MB입니다.
.enableLimitWithCacheSize(100 * 1024 * 1024)
// 캐시가 상한에 도달하면 가장 오래된 캐시 데이터를 삭제합니다.
.setCacheDiscard(CacheDiscard.DISCARD_OLDEST);
업로드 네트워크 구성¶
setProxy(...), setProxyAuthenticator(...), setDns(...)는 SDK가 DataKit 또는 DataWay로 데이터를 업로드하는 요청에만 적용되며, 애플리케이션 비즈니스 요청의 네트워크 구성을 변경하지 않습니다.
import {
FTSDK,
FTSDKConfig,
FTProxyConfig,
FTProxyAuthenticator,
FTDnsConfig
} from '@guancecloud/ft_sdk/Index';
const proxyConfig: FTProxyConfig = {
host: 'proxy.example.com',
port: 8080,
exclusionList: ['localhost', '127.0.0.1']
};
const proxyAuthenticator: FTProxyAuthenticator = {
username: 'proxy-user',
password: 'proxy-password'
};
const dnsConfig: FTDnsConfig = {
servers: ['1.1.1.1', '8.8.8.8'],
overHttpsUrl: 'https://dns.example.com/dns-query'
};
const sdkConfig = FTSDKConfig.builder(datawayUrl, clientToken)
.setProxy(proxyConfig)
.setProxyAuthenticator(proxyAuthenticator)
.setDns(dnsConfig);
FTSDK.install(sdkConfig, this.context);
FTProxyConfig¶
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
host |
string |
예 | 프록시 서버 주소 |
port |
number |
예 | 프록시 서버 포트 |
exclusionList |
Array<string> |
아니요 | 프록시를 사용하지 않을 호스트 목록입니다. NetworkKit의 프록시 제외 규칙을 따릅니다. |
username |
string |
아니요 | 프록시 사용자 이름입니다. setProxyAuthenticator(...)를 통해 별도로 구성할 수도 있습니다. |
password |
string |
아니요 | 프록시 비밀번호입니다. setProxyAuthenticator(...)를 통해 별도로 구성할 수도 있습니다. |
FTProxyAuthenticator¶
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
username |
string |
예 | 프록시 인증 사용자 이름 |
password |
string |
예 | 프록시 인증 비밀번호 |
FTProxyConfig와 FTProxyAuthenticator에 동시에 인증 정보를 설정하면 FTProxyAuthenticator의 구성이 우선 적용됩니다.
FTDnsConfig¶
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
servers |
Array<string> |
아니요 | 사용자 지정 DNS 서버 주소입니다. 빈 문자열은 무시되며, 최대 처음 세 개의 유효한 주소를 사용합니다. |
overHttpsUrl |
string |
아니요 | DNS over HTTPS 서비스 주소 |
블랙리스트 필터링¶
ft-sdk 0.1.15는 DataKit과 호환되는 블랙리스트 필터링을 지원하며, 데이터가 로컬 캐시에 기록되기 전에 Logging, RUM 데이터를 필터링하는 데 사용됩니다. 이 기능은 기본적으로 활성화되어 있으며 setEnableDataFilter(false)로 비활성화할 수 있습니다.
블랙리스트 규칙은 로컬 규칙과 원격 규칙으로 나뉩니다:
- 로컬 규칙은
setDataFilters로 구성하며logging,rum두 가지 규칙을 지원합니다. - 데이터 필터링이 활성화되어 있고 유효한 업로드 주소가 있으면 SDK는 DataKit 또는 DataWay에서 원격
logging,rum규칙을 가져옵니다. - 로컬 및 원격 규칙은 동시에 새 데이터를 필터링합니다. 규칙에 매칭된 데이터는 로컬 캐시에 기록되지 않습니다.
- 데이터는 먼저
LineDataModifier를 거쳐 수정된 후, 수정된 내용을 기준으로 블랙리스트 필터링이 수행됩니다. - 원격 규칙은 업로드 전에 매칭된 캐시 데이터를 정리합니다. 로컬 규칙은 새 데이터만 필터링합니다.
- SDK는 각 업로드 작업이 시작될 때 원격 규칙의 만료 여부를 확인하고, 만료된 경우에만 가져옵니다.
- 서버의
pull_interval이 숫자 값일 때 단위는 나노초입니다. 예를 들어10000000000은 10초를 의미합니다. 문자열 숫자"10"은 10초를 의미하며,"10s","2m","1h"등 단위가 포함된 형식도 지원합니다. 누락되었거나 유효하지 않으면 10초로 처리합니다. - 서버 반환 내용이 변경되지 않은 경우 SDK는 동일한 규칙을 다시 파싱하거나 적용하지 않습니다.
규칙 표현식은 {} 안에 작성해야 하며, in, not in, match, not match 연산자를 지원합니다. 여러 조건은 and / or로 조합할 수 있습니다. 필드 소스에는 데이터 태그와 필드가 포함되며, source, measurement, class 등 데이터 유형 식별 필드도 지원합니다. match는 정규식을 사용합니다.
import {
FTSDK,
FTSDKConfig,
FTDataFilters
} from '@guancecloud/ft_sdk/Index';
const dataFilters: FTDataFilters = new Map<string, Array<string>>();
dataFilters.set('logging', [
"{ source in ['df_rum_harmonyos_log'] and message match ['.*password.*'] }"
]);
dataFilters.set('rum', [
"{ source in [resource] and resource_status in ['404', '503'] }"
]);
const sdkConfig = FTSDKConfig.builder(datawayUrl, clientToken)
.setEnableDataFilter(true)
.setDataFilters(dataFilters);
FTSDK.install(sdkConfig, this.context);
FTDataFilters에는 Map<string, Array<string>> 또는 동일한 구조의 객체를 전달할 수 있습니다. 분류 이름은 대소문자를 구분하지 않으며, logging, rum 외의 분류는 무시됩니다.
// 로컬 및 원격 블랙리스트 필터링을 비활성화하지만, 구성된 로컬 규칙은 유지합니다.
sdkConfig.setEnableDataFilter(false);
// 구성된 로컬 규칙을 비우며, 서버의 원격 규칙에는 영향을 주지 않습니다.
sdkConfig.setDataFilters(null);
런타임에 유효한 업로드 주소로 전환하면 SDK는 이전 주소의 원격 규칙을 지우고 새 주소에서 다시 가져옵니다. 로컬 규칙은 계속 유지됩니다.
사용자 바인딩 및 바인딩 해제¶
사용 방법¶
/**
* 사용자 정보 바인딩(사용자 ID만)
* @param id 사용자 ID
*/
static bindRumUserDataById(id: string): void
/**
* 사용자 정보 바인딩(전체 사용자 데이터)
* @param userData 사용자 데이터 객체
*/
static bindRumUserData(userData: UserData): void
/**
* 사용자 정보 바인딩 해제
*/
static unbindRumUserData(): void
UserData¶
| 메서드 이름 | 설명 | 필수 | 참고 |
|---|---|---|---|
setId |
사용자 ID를 설정합니다 | 아니요 | |
setName |
사용자 이름을 설정합니다 | 아니요 | |
setEmail |
이메일을 설정합니다 | 아니요 | |
setExts |
사용자 확장을 설정합니다 | 아니요 | 추가 규칙은 사용자 지정 태그와 전역 컨텍스트를 참고하세요. |
코드 예제¶
import { FTSDK, UserData } from '@guancecloud/ft_sdk/Index';
// 방식 1: 사용자 ID만 바인딩(빠른 바인딩에 권장)
FTSDK.bindRumUserDataById('user_001');
const userData = new UserData();
userData.setId('user_001');
userData.setName('test.user');
userData.setEmail('test@mail.com');
userData.setExts({
'user_type': 'vip'
});
FTSDK.bindRumUserData(userData);
FTSDK.unbindRumUserData();
런타임 기능¶
자동 데이터 동기화 설정¶
SDK 초기화 후 FTSDK.setAutoSync(...)를 통해 캐시 데이터 자동 동기화를 동적으로 활성화하거나 비활성화할 수 있습니다. 비활성화하면 SDK는 수집된 데이터를 여전히 로컬 캐시에 기록하지만, 수집 후 자동으로 업로드를 트리거하지 않습니다. FTSDK.flushSyncData()와 함께 사용하여 데이터 동기화를 직접 관리할 수 있습니다.
import { FTSDK } from '@guancecloud/ft_sdk/Index';
// 자동 동기화 비활성화
FTSDK.setAutoSync(false);
// 자동 동기화 활성화
FTSDK.setAutoSync(true);
FTSDKConfig.setAutoSync(...)는 SDK 초기화 시의 동기화 상태를 설정하는 데 사용되고,FTSDK.setAutoSync(...)는 SDK 초기화 후 동기화 상태를 동적으로 변경하는 데 사용됩니다.
데이터 능동 동기화¶
자동 동기화가 비활성화된 경우 데이터 동기화를 능동적으로 트리거할 수 있습니다:
자동 동기화가 활성화되면 SDK는 10초 집계 윈도우를 사용하여 짧은 시간 내에 연속으로 생성된 데이터를 병합한 후 업로드합니다. flushSyncData()는 해당 집계 윈도우를 기다리지 않습니다. 먼저 현재 처리 대기 중인 RUM 및 Log worker 큐를 최대한 로컬 동기화 캐시로 플러시한 다음 즉시 업로드 작업을 스케줄링합니다. 큐 플러시에 실패하더라도 계속해서 업로드 트리거를 시도합니다.
SDK 캐시 데이터 정리¶
clearAllData()는 업로드되지 않은 모든 캐시 데이터를 삭제하며, 다음을 포함합니다:
- 동기화 데이터 테이블(
sync_data_flat)의 모든 데이터 - RUM 뷰 데이터 테이블(
rum_view)의 모든 데이터 - RUM 액션 데이터 테이블(
rum_action)의 모든 데이터