콘텐츠로 이동

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에서 명시적으로 활성화할 수 있습니다.

const sdkConfig = FTSDKConfig.builder(datawayUrl, clientToken)
  .enableFileDataStore();

파일 캐시 쓰기 상황을 먼저 검증하려면 섀도 쓰기를 활성화할 수 있습니다. 활성화하면 SDK는 여전히 SQLite에서 데이터를 읽고 업로드하며, 동시에 쓰기를 FileStore에 미러링합니다. 검증이 완료되면 enableFileDataStore()로 전환합니다.

const shadowConfig = FTSDKConfig.builder(datawayUrl, clientToken)
  .setFileDataStoreShadow(true);

캐시 크기 제한

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 초기화 후 동기화 상태를 동적으로 변경하는 데 사용됩니다.

데이터 능동 동기화

자동 동기화가 비활성화된 경우 데이터 동기화를 능동적으로 트리거할 수 있습니다:

import { FTSDK } from '@guancecloud/ft_sdk/Index';

FTSDK.flushSyncData();

자동 동기화가 활성화되면 SDK는 10초 집계 윈도우를 사용하여 짧은 시간 내에 연속으로 생성된 데이터를 병합한 후 업로드합니다. flushSyncData()는 해당 집계 윈도우를 기다리지 않습니다. 먼저 현재 처리 대기 중인 RUM 및 Log worker 큐를 최대한 로컬 동기화 캐시로 플러시한 다음 즉시 업로드 작업을 스케줄링합니다. 큐 플러시에 실패하더라도 계속해서 업로드 트리거를 시도합니다.

SDK 캐시 데이터 정리

import { FTSDK } from '@guancecloud/ft_sdk/Index';

await FTSDK.clearAllData();

clearAllData()는 업로드되지 않은 모든 캐시 데이터를 삭제하며, 다음을 포함합니다:

  • 동기화 데이터 테이블(sync_data_flat)의 모든 데이터
  • RUM 뷰 데이터 테이블(rum_view)의 모든 데이터
  • RUM 액션 데이터 테이블(rum_action)의 모든 데이터

문서 평가

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