콘텐츠로 이동

SDK 초기화

이 문서에서는 React Native SDK 초기화 및 런타임 기능 관련 내용을 설명합니다.

SDK 가져오기

이제 코드에서 다음을 사용할 수 있습니다:

import {
  FTMobileReactNative,
  FTReactNativeLog,
  FTReactNativeTrace,
  FTReactNativeRUM,
  FTMobileConfig,
  FTLogConfig,
  FTTraceConfig,
  FTRUMConfig,
  ErrorMonitorType,
  DeviceMetricsMonitorType,
  DetectFrequency,
  TraceType,
  FTLogStatus,
  EnvType,
} from '@cloudcare/react-native-mobile';

기본 구성

// 로컬 환경 배포, Datakit 배포
let config: FTMobileConfig = {
  datakitUrl: datakitUrl,
};

// 공용 DataWay 사용
let config: FTMobileConfig = {
  datawayUrl: datawayUrl,
  clientToken: clientToken,
};

await FTMobileReactNative.sdkConfig(config);
필드 유형 필수 설명
datakitUrl string 예 로컬 환경 배포(Datakit) 업로드 URL 주소입니다. 예: http://10.0.0.1:9529, 포트 기본값 9529, SDK가 설치된 기기는 해당 주소에 액세스할 수 있어야 합니다. 참고: datakitUrl과 datawayUrl 구성은 둘 중 하나만 선택해야 합니다. SDK 0.4.3부터 초기화 후 setDatakitURL()을 통해 지연 구성할 수 있으며, 구성 전에는 데이터를 업로드하지 않습니다. 자세한 내용은 동적 업로드 주소 업데이트를 참고하세요.
datawayUrl string 예 공용 Dataway 업로드 URL 주소로, [RUM] 앱에서 가져옵니다. 예: https://open.dataway.url, SDK가 설치된 기기는 이 주소에 액세스할 수 있어야 합니다. 참고: datakitUrl과 datawayUrl 구성은 둘 중 하나만 선택해야 합니다. SDK 0.4.3부터 초기화 후 setDatawayURL()을 통해 지연 구성할 수 있으며, 구성 전에는 데이터를 업로드하지 않습니다. 자세한 내용은 동적 업로드 주소 업데이트를 참고하세요.
clientToken string 예 인증 token으로, datawayUrl과 함께 사용해야 합니다. SDK 0.4.3부터 초기화 후 setDatawayURL(datawayUrl, clientToken)을 통해 업로드 주소와 함께 지연 구성할 수 있습니다. 자세한 내용은 동적 업로드 주소 업데이트를 참고하세요.
debug boolean 아니요 로그 출력 허용 여부를 설정합니다. 기본값 false
env string 아니요 환경 구성, 기본값 prod, 임의 문자, 단일 단어 사용 권장, 예: test 등
envType enum EnvType 아니요 환경 구성, 기본값 EnvType.prod. 참고: env와 envType 중 하나만 구성하면 됩니다
service string 아니요 소속 비즈니스 또는 서비스 이름을 설정하며, Log 및 RUM의 service 필드 데이터에 영향을 줍니다. 기본값: df_rum_ios, df_rum_android
autoSync boolean 아니요 데이터 수집 후 서버에 자동 동기화할지 여부, 기본값 true. false인 경우 FTMobileReactNative.flushSyncData()를 사용하여 데이터 동기화를 직접 관리합니다
syncPageSize number 아니요 동기화 요청 항목 수를 설정합니다. 범위 [5,), 참고: 요청 항목 수가 클수록 데이터 동기화에 더 많은 컴퓨팅 리소스가 사용됩니다
syncSleepTime number 아니요 동기화 간격 시간을 설정합니다. 범위 [0,5000], 기본값은 설정하지 않음
enableDataIntegerCompatible boolean 아니요 web 데이터와 공존해야 하는 경우 활성화하는 것을 권장합니다. 이 구성은 web 데이터 유형 저장 호환성 문제를 처리하는 데 사용됩니다. 0.3.12 이후 버전에서 기본 활성화됩니다
globalContext object 아니요 사용자 정의 태그를 추가합니다. 추가 규칙은 여기를 참고하세요
compressIntakeRequests boolean 아니요 업로드 동기화 데이터에 deflate 압축을 수행합니다. 기본 비활성화
enableLimitWithDbSize boolean 아니요 DB를 사용한 데이터 크기 제한을 활성화합니다. 기본값 100MB, 단위 Byte, 데이터베이스가 클수록 디스크 부담이 커집니다. 기본 비활성화. 참고: 활성화하면 Log 구성 logCacheLimitCount 및 RUM 구성 rumCacheLimitCount가 무효화됩니다. SDK 0.3.10 이상 버전에서 이 파라미터를 지원합니다
dbCacheLimit number 아니요 DB 캐시 제한 크기입니다. 범위 [30MB,), 기본값 100MB, 단위 byte, SDK 0.3.10 이상 버전에서 이 파라미터를 지원합니다
dbDiscardStrategy string 아니요 데이터베이스에서 데이터 폐기 규칙을 설정합니다. 폐기 정책: FTDBCacheDiscard.discard 새 데이터 폐기(기본), FTDBCacheDiscard.discardOldest 오래된 데이터 폐기. SDK 0.3.10 이상 버전에서 이 파라미터를 지원합니다
dataModifier object 아니요 개별 필드를 변경합니다. SDK 0.3.14 이상에서 지원하며, 사용 예시는 데이터 수집 마스킹을 참고하세요
lineDataModifier object 아니요 단일 데이터 항목을 변경합니다. SDK 0.3.14 이상에서 지원하며, 사용 예시는 데이터 수집 마스킹을 참고하세요
enableDataFilter boolean 아니요 SDK 측 블랙리스트 필터링 활성화 여부, 기본값 true. Log 및 RUM 데이터 필터링을 지원하며, SDK 0.4.2 이상 버전에서 지원합니다. 사용 예시는 블랙리스트 필터링을 참고하세요
dataFilters Record> 아니요 앱 내 블랙리스트 규칙을 구성하며, logging 및 rum 두 가지 데이터 유형을 지원합니다. SDK 0.4.2 이상 버전에서 지원하며, 규칙 구문은 규칙 구문을 참고하세요
allowWebViewHost Array / null 아니요 WebView RUM 및 로그에서 공유하는 host 허용 목록을 구성합니다. null은 모든 host 허용, []는 모든 host 금지입니다. 설정하지 않으면 기존 RUM 구성을 따르며, 그렇지 않으면 기존 구성보다 우선합니다. 원격 구성이 우선합니다. 자세한 내용은 WebView host 구성을 참고하세요. SDK 0.4.3부터 지원합니다.
remoteConfiguration boolean 아니요 데이터 수집의 원격 구성 기능 활성화 여부, 기본 비활성화. 활성화하면 SDK 초기화 또는 앱 핫 스타트 시 데이터 업데이트가 트리거됩니다. SDK 0.3.16 이상에서 지원합니다. 구성 가능한 파라미터
remoteConfigMiniUpdateInterval number 아니요 원격 동적 구성 최소 업데이트 간격을 설정합니다. 단위 초, 기본값 12시간. SDK 0.3.16 이상에서 지원합니다
remoteConfigOverrideRules Array 아니요 원격 구성 재정의 규칙을 설정하며, 앱 원격 구성 전에 사용자 정의 조정을 수행할 수 있습니다. SDK 0.3.16 이상에서 지원하며, 사용 예시는 여기를 참고하세요

SDK 0.4.3부터는 초기화 시 업로드 주소를 일시적으로 제공하지 않을 수 있습니다:

await FTMobileReactNative.sdkConfig({});
// RUM, Log 등 필요한 수집 모듈 초기화를 계속합니다.
// 업로드 주소를 얻은 후 설정합니다:
await FTMobileReactNative.setDatawayURL('https://open.dataway.url', 'client_token');

주소가 구성되지 않은 경우 활성화된 수집 모듈은 여전히 데이터를 수집하고 캐시할 수 있지만 업로드하지 않습니다. DataWay 주소를 설정할 때는 반드시 clientToken을 함께 제공해야 하며, DataKit을 사용하는 경우 setDatakitURL()을 호출합니다. 캐시는 여전히 용량 제한의 적용을 받습니다. 자세한 내용은 동적 업로드 주소 업데이트를 참고하세요.

블랙리스트 필터링

React Native SDK 0.4.2 이상 버전은 데이터가 로컬 캐시에 기록되기 전에 RUM 및 Log 데이터를 필터링하는 기능을 지원합니다. 이 기능은 기본적으로 활성화되며, enableDataFilter: false를 통해 SDK 측 필터링을 비활성화할 수 있습니다.

블랙리스트 규칙은 Guance 워크스페이스의 블랙리스트에서 통합 구성할 수 있으며, SDK가 DataKit 또는 DataWay에서 자동으로 가져옵니다. FTMobileConfig.dataFilters를 통해 앱 내에서 구성할 수도 있습니다. 두 방식은 동일한 블랙리스트 필터링 기능에 대응하며 동시에 사용할 수 있습니다. 어느 규칙이든 매칭되면 해당 데이터는 폐기됩니다.

블랙리스트 필터링은 lineDataModifier 이후, 로컬 캐시 기록 전에 실행됩니다. lineDataModifier와 블랙리스트 필터링을 동시에 구성한 경우 필터링 규칙은 수정된 데이터를 기준으로 판단합니다.

enableDataFilter는 SDK 측의 규칙 가져오기 및 필터링만 제어합니다. false로 설정하면 SDK는 더 이상 dataFilters를 적용하거나 워크스페이스 규칙을 가져오지 않습니다. DataKit으로 업로드하는 경우 워크스페이스 블랙리스트는 여전히 DataKit 측에서 실행될 수 있습니다.

Data Filter는 SDK 데이터 기록 경로에 적용됩니다. 규칙이 너무 많거나 정규 표현식이 지나치게 복잡하면 데이터 기록 성능에 영향을 줄 수 있으므로 필요한 규칙만 구성하는 것이 좋습니다.

let config: FTMobileConfig = {
  datawayUrl: datawayUrl,
  clientToken: clientToken,
  enableDataFilter: true,
  dataFilters: {
    logging: [
      "{ `source` in [ 'df_rum_ios_log' , 'df_rum_android_log' ] and `message` match [ 'timeout' ] }",
    ],
    rum: [
      "{ `resource_status` match [ '5..' ] }",
    ],
  },
};

await FTMobileReactNative.sdkConfig(config);

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

규칙 구문

Data Filter 규칙 구문은 블랙리스트 필터링 규칙과 기본적으로 동일하며, 전체 구문 설명은 블랙리스트 필터링 규칙을 참고하세요.

dataFilters의 key는 데이터 분류를 나타내며, 현재 SDK는 다음을 지원합니다:

분류 설명
logging Log 데이터
rum RUM 데이터

각 규칙은 { 条件 }으로 표현하며, 어느 규칙이든 매칭되면 해당 분류의 데이터가 필터링됩니다. 규칙에서는 데이터의 tag, field 필드와 source, measurement 데이터 유형 식별 필드를 사용할 수 있습니다.

필드 값 형식과 연산자 의미는 블랙리스트 필터링 규칙의 필드 값 형식 설명 및 연산자 설명을 참고하세요.

SDK 규칙 문자열의 필드 값에는 배열 형식을 사용하는 것이 좋습니다. 부정 연산자는 not in, not match를 지원하며, 서버에서 전달되는 규칙에서 사용하는 notin, notmatch 및 not_in과도 호환됩니다.

{ `status` in [ 'debug' ] and `env` not in [ 'prod' ] and `message` not match [ '.*error.*' ] }

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

사용 방법

/**
 * 사용자를 바인딩합니다.
 * @param userId 사용자 ID.
 * @param userName 사용자 이름.
 * @param userEmail 사용자 이메일.
 * @param extra 사용자의 추가 정보.
 */
bindRUMUserData(userId: string, userName?: string, userEmail?: string, extra?: object): Promise<void>;

/**
 * 사용자 바인딩을 해제합니다.
 */
unbindRUMUserData(): Promise<void>;

사용 예시

import { FTMobileReactNative } from '@cloudcare/react-native-mobile';
FTMobileReactNative.bindRUMUserData('react-native-user', 'user_name');

FTMobileReactNative.unbindRUMUserData();

런타임 기능

SDK 종료

FTMobileReactNative를 사용하여 SDK를 종료합니다.

/**
 * SDK 내에서 실행 중인 객체를 종료합니다.
 */
shutDown(): Promise<void>;
FTMobileReactNative.shutDown();

SDK 캐시 데이터 정리

FTMobileReactNative를 사용하여 아직 업로드되지 않은 캐시 데이터를 정리합니다.

/**
 * 서버에 아직 업로드되지 않은 모든 데이터를 삭제합니다.
 */
clearAllData(): Promise<void>;
FTMobileReactNative.clearAllData();

데이터 직접 동기화

FTMobileConfig.autoSync가 true로 구성된 경우 추가 작업이 필요하지 않으며 SDK가 자동으로 동기화합니다.

FTMobileConfig.autoSync가 false로 구성된 경우 데이터 동기화를 직접 트리거해야 합니다.

/**
 * 데이터를 직접 동기화합니다. `FTMobileConfig.autoSync = false`로 구성된 경우 직접 트리거해야 합니다.
 */
flushSyncData(): Promise<void>;
FTMobileReactNative.flushSyncData();

초기화 순서

최상위 index.js 파일에서 App을 등록하기 전에 SDK 초기화를 완료하여, SDK의 다른 메서드를 호출하기 전에 SDK가 완전히 준비되도록 하세요.

기본 구성을 완료한 후 RUM, Log, Trace 구성을 진행하세요.

import App from './App';

async function sdkInit() {
  await FTMobileReactNative.sdkConfig(config);
  await FTReactNativeRUM.setConfig(rumConfig);
  // ...
}

sdkInit();
AppRegistry.registerComponent('main', () => App);

동적 구성

동적 구성 관련 기능은 동적 구성으로 분리되었습니다.

문서 평가

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