콘텐츠로 이동

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 구성은 둘 중 하나만 선택
datawayUrl string 공용 Dataway 전송 URL 주소, [실제 사용자 모니터링(RUM)] 애플리케이션에서 획득, 예시: https://open.dataway.url, SDK를 설치한 기기에서 해당 주소에 접근 가능해야 합니다. 참고: datakitUrl과 datawayUrl 구성은 둘 중 하나만 선택
clientToken string 인증 토큰, datawayUrl과 함께 사용해야 함
debug boolean 아니요 로그 출력 허용 여부 설정, 기본값 false
env string 아니요 환경 구성, 기본값 prod, 임의 문자, 단일 단어 사용 권장(예: test 등)
envType enum EnvType 아니요 환경 구성, 기본값 EnvType.prod. 참고: envenvType 중 하나만 구성하면 됨
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 아니요 웹 데이터와 공존해야 하는 경우 활성화하는 것이 좋습니다. 이 구성은 웹 데이터 타입 저장 호환성 문제를 처리합니다. 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, SDK 0.4.2 이상 버전 지원, 사용 예시는 블랙리스트 필터링 참고
dataFilters Record> 아니요 App 로컬에서 관리하는 데이터 필터링 규칙. 지원되는 분류: logging, rum. SDK 0.4.2 이상 버전 지원, 규칙 구문은 규칙 구문 참고
remoteConfiguration boolean 아니요 데이터 수집의 원격 구성 기능 활성화 여부, 기본적으로 비활성화. 활성화하면 SDK 초기화 또는 애플리케이션 핫 스타트 시 데이터 업데이트가 트리거됩니다. SDK 0.3.16 이상 지원. 구성 가능한 매개변수
remoteConfigMiniUpdateInterval number 아니요 원격 동적 구성 최소 업데이트 간격 설정, 단위 초, 기본값 12시간. SDK 0.3.16 이상 지원
remoteConfigOverrideRules Array 아니요 원격 구성 재정의 규칙 설정, 애플리케이션 원격 구성 전에 사용자 정의 조정 가능. SDK 0.3.16 이상 지원, 사용 예시는 여기 참고

블랙리스트 필터링

Data Filter는 SDK가 로컬 캐시에 쓰기 전에 규칙에 따라 RUM 및 Log 데이터를 필터링하는 데 사용됩니다. 필터링 규칙에 해당하는 데이터는 로컬 캐시에 저장되지 않으며 업로드되지 않습니다.

  • 로컬 규칙: FTMobileConfig.dataFilters를 통해 구성, App이 SDK 초기화 시 전달합니다.
  • 원격 규칙: FTMobileConfig.enableDataFilter를 활성화하면 SDK가 Studio 측에서 추가한 블랙리스트 규칙을 가져옵니다.

  • 로컬 규칙과 원격 규칙이 동시에 적용되며, 하나의 규칙이라도 해당되면 해당 데이터는 폐기됩니다.

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

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

규칙 구문

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

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

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

각 규칙은 { 조건 }으로 표시되며, 하나의 규칙이라도 해당되면 해당 분류의 데이터가 필터링됩니다. 규칙에서는 데이터의 tag, field 필드를 사용할 수 있습니다.

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

SDK 규칙 문자열의 모든 필드 값은 배열 형식을 사용해야 하며, 역방향 연산자는 고정으로 notin, notmatch로 작성합니다.

{ `status` in [ 'debug' ] and `env` notin [ 'prod' ] and `message` notmatch [ '.*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.autoSynctrue로 구성한 경우 추가 작업이 필요 없으며 SDK가 자동으로 동기화합니다.

FTMobileConfig.autoSyncfalse로 구성한 경우 데이터 동기화를 수동으로 트리거해야 합니다.

/**
 * 데이터를 수동으로 동기화합니다. `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);

동적 구성

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

문서 평가

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