콘텐츠로 이동

SDK 초기화

이 문서는 Flutter SDK 초기화 및 런타임 기능과 관련된 내용을 다룹니다.

기본 구성

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // 로컬 환경 배포, Datakit 배포
  await FTMobileFlutter.sdkConfig(
    datakitUrl: datakitUrl,
  );

  // 퍼블릭 DataWay 사용
  await FTMobileFlutter.sdkConfig(
    datawayUrl: datawayUrl,
    cliToken: cliToken,
  );
}
필드 유형 필수 설명
datakitUrl String 아니요 로컬 환경 배포(Datakit) 보고 URL 주소입니다. 예: http://10.0.0.1:9529, 기본 포트는 9529이며, SDK가 설치된 기기는 해당 주소에 접근할 수 있어야 합니다. 주의: 보고 주소를 설정할 때 datakitUrl과 datawayUrl 중 하나만 선택해야 합니다. SDK 0.5.8부터는 일시적으로 설정하지 않고 이후 런타임 메서드로 설정할 수 있습니다.
datawayUrl String 아니요 퍼블릭 DataWay 보고 URL 주소로, [실제 사용자 모니터링(RUM)] 앱에서 가져옵니다. 예: https://open.dataway.url, SDK가 설치된 기기는 해당 주소에 접근할 수 있어야 합니다. 주의: 보고 주소를 설정할 때 datakitUrl과 datawayUrl 중 하나만 선택해야 합니다. SDK 0.5.8부터는 일시적으로 설정하지 않고 이후 런타임 메서드로 설정할 수 있습니다.
cliToken String DataWay 사용 시 필수 인증 토큰으로, datawayUrl과 함께 구성해야 합니다. 주소를 지연 설정하는 경우 setDatawayURL(datawayUrl, cliToken)를 통해 함께 설정합니다.
debug bool 아니요 로그 출력 허용 여부를 설정합니다. 기본값은 false입니다.
env String 아니요 환경 구성이며 기본값은 prod입니다. 임의의 문자를 사용할 수 있고, test와 같이 한 단어를 사용하는 것을 권장합니다.
envType enum EnvType 아니요 환경 구성이며 기본값은 EnvType.prod입니다. 주의: env와 envType 중 하나만 구성하면 됩니다.
autoSync bool 아니요 데이터 수집 후 서버로 자동 동기화할지 여부입니다. 기본값은 true입니다. false일 때는 FTMobileFlutter.flushSyncData()를 사용하여 데이터 동기화를 직접 관리합니다.
syncPageSize enum 아니요 동기화 요청 항목 수를 설정합니다. SyncPageSize.mini는 5개, SyncPageSize.medium은 10개, SyncPageSize.large는 50개이며 기본값은 SyncPageSize.medium입니다.
customSyncPageSize number 아니요 동기화 요청 항목 수를 설정합니다. 범위는 [5, )입니다. 요청 항목 수가 클수록 데이터 동기화에 더 많은 컴퓨팅 리소스가 사용됩니다.
syncSleepTime number 아니요 동기화 간격 시간을 설정합니다. 범위는 [0,5000]이며 기본적으로 설정하지 않습니다.
globalContext object 아니요 사용자 정의 태그를 추가합니다. 추가 규칙은 충돌 필드 설명을 참고하세요.
serviceName String 아니요 서비스 이름
customHttpOverrides HttpOverrides 아니요 사용자 정의 HTTP Overrides입니다. HTTP 자동 수집을 활성화한 경우 프로젝트에서 이미 HttpOverrides.global을 사용자 정의했다면 이 파라미터를 통해 사용자 정의 구현을 전달할 수 있으며, SDK는 수집 경로에서 해당 구현을 재사용합니다.
enableLimitWithDbSize boolean 아니요 DB를 사용한 데이터 크기 제한을 활성화합니다. 기본값은 100MB(단위: Byte)이며 기본적으로 활성화하지 않습니다. 활성화하면 logCacheLimitCount 및 rumCacheLimitCount가 적용되지 않습니다. SDK 0.5.3-pre.2 이상에서 지원됩니다.
dbCacheLimit number 아니요 DB 캐시 제한 크기입니다. 범위는 [30MB, )이며 기본값은 100MB(단위: byte)입니다. SDK 0.5.3-pre.2 이상에서 지원됩니다.
dbCacheDiscard string 아니요 데이터베이스에서 데이터 폐기 규칙을 설정합니다. FTDBCacheDiscard.discard는 새 데이터를 폐기하며(기본값), FTDBCacheDiscard.discardOldest는 오래된 데이터를 폐기합니다. SDK 0.5.3-pre.2 이상에서 지원됩니다.
enableLimitWithCacheSize boolean 아니요 캐시 크기를 사용한 데이터 크기 제한을 활성화합니다. Android는 전체 캐시 크기 제한을 사용하며, iOS는 DB 캐시 크기 제한으로 매핑됩니다. 활성화하면 cacheLimit을 우선 사용하고, 설정되지 않은 경우 dbCacheLimit을 호환 사용합니다.
cacheLimit number 아니요 캐시 제한 크기(단위: byte)입니다. Android는 전체 캐시 크기에 해당하며, iOS는 DB 캐시 제한에 해당합니다.
cacheDiscard enum FTCacheDiscard 아니요 캐시 데이터 폐기 규칙을 설정합니다. Android는 캐시 폐기 정책을 사용하며, iOS는 DB 데이터 폐기 규칙으로 매핑됩니다. FTCacheDiscard.discard는 새 데이터를 폐기하며(기본값), FTCacheDiscard.discardOldest는 오래된 데이터를 폐기합니다.
enableFileDataStore boolean 아니요 Android: FileStore 파일 캐시 사용 여부
needTransformOldCache boolean 아니요 Android: FileStore 사용 시 이전 SQLite 캐시 데이터를 마이그레이션할지 여부
fileDataStoreShadow boolean 아니요 Android: SQLite 읽기 경로 사용 시 FileStore에 동시 기록할지 여부
compressIntakeRequests boolean 아니요 업로드 동기화 데이터를 deflate 압축합니다. SDK 0.5.3-pre.2 이상에서 지원되며, SDK 0.5.7부터 기본적으로 활성화되고 이전에는 기본적으로 비활성화되었습니다. false로 설정하여 비활성화할 수 있습니다.
enableDataIntegerCompatible boolean 아니요 Web 데이터와 공존해야 하는 경우 활성화를 권장하며, Web 데이터 유형 저장 호환성 문제를 처리하는 데 사용됩니다. 0.5.4-pre.1 이상에서 기본적으로 활성화됩니다.
dataModifier Map<String,Object> 아니요 단일 필드를 변경합니다. 사용 예시는 데이터 수집 마스킹을 참고하세요.
lineDataModifier Map<String,Map<String,Object>> 아니요 단일 데이터 항목을 변경합니다. 사용 예시는 데이터 수집 마스킹을 참고하세요.
enableDataFilter bool 아니요 SDK 측 블랙리스트 필터링을 활성화할지 여부입니다. 기본값은 true입니다. Log 및 RUM 데이터 필터링을 지원하며 SDK 0.5.7 이상 버전에서 지원됩니다. 사용 예시는 블랙리스트 필터링을 참고하세요.
dataFilters Map<String,List<String>> 아니요 앱 내 블랙리스트 규칙을 구성합니다. logging 및 rum 두 가지 데이터 유형을 지원합니다. SDK 0.5.7 이상 버전에서 지원되며, 규칙 구문은 규칙 구문을 참고하세요.
enableRemoteConfiguration bool 아니요 원격 구성을 활성화할지 여부입니다. 활성화하면 SDK는 자동 업데이트 또는 직접 호출 시 구성을 가져오려고 시도하며, 호출 빈도는 최소 업데이트 간격의 제한을 받습니다. 자세한 내용은 동적 구성을 참고하세요.
remoteConfigMiniUpdateInterval int 아니요 원격 구성 최소 업데이트 간격(단위: 초)이며 기본값은 12시간입니다. enableRemoteConfiguration을 활성화해야 합니다. 자세한 내용은 동적 구성 직접 동기화를 참고하세요.
allowWebViewHost List<String> 아니요 WebView 데이터 수집에 허용되는 Host 목록으로, RUM과 Log에서 공용으로 사용합니다. 설정하지 않으면 기본적으로 모든 Host를 허용하며, 빈 목록은 어떤 Host도 허용하지 않음을 의미합니다. 우선순위는 원격 구성 > 여기의 기본 구성 > 기존 RUM 구성 항목입니다. SDK 0.5.8부터 지원되며, 자세한 내용은 WebView 데이터 모니터링을 참고하세요.
remoteConfigOverrideRules List<Map<String, Object?>> 아니요 원격 구성 로컬 재정의 규칙으로, 서버에서 반환된 사용자 정의 환경 변수에 따라 최종 구성을 조정합니다.
iOSGroupIdentifiers List<String> 아니요 iOS App Group 식별자 목록으로, Extension과 메인 앱 간 캐시 데이터 공유에 사용됩니다.

보고 주소의 지연 설정 및 동적 전환은 보고 주소 동적 업데이트를 참고하세요.

활성화 및 업데이트 방법은 원격 구성을 참고하고, 지원되는 필드는 Flutter 원격 구성 필드를 참고하세요.

블랙리스트 필터링

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

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

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

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

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

await FTMobileFlutter.sdkConfig(
  datawayUrl: datawayUrl,
  cliToken: cliToken,
  enableDataFilter: true,
  dataFilters: {
    'logging': [
      "{ source in [ 'df_rum_ios_log', 'df_rum_android_log' ] and message match [ 'timeout' ] }",
    ],
    'rum': [
      "{ resource_status match [ '5..' ] }",
    ],
  },
);

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.*' ] }

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

사용 방법

/// 사용자 바인딩
///
/// [userid] 사용자 ID
/// [userName] 사용자 이름
/// [userEmail] 사용자 이메일
/// [userExt] 확장 데이터
static Future<void> bindRUMUserData(String userId,
    {String? userName, String? userEmail, Map<String, String>? ext})

/// 사용자 바인딩 해제
static Future<void> unbindRUMUserData()

코드 예시

FTMobileFlutter.bindRUMUserData("flutterUser");

FTMobileFlutter.unbindRUMUserData();

ext 추가 규칙은 충돌 필드 설명을 참고하세요.

런타임 기능

데이터 직접 동기화

FTMobileFlutter.flushSyncData();

autoSync: false인 경우에만 데이터를 직접 동기화해야 합니다.

종료 및 재초기화

Core SDK 0.5.8, Session Replay SDK 0.1.1부터 기본 SDK를 종료할 때 연동된 Flutter Session Replay의 정리가 완료될 때까지 대기합니다.

await FTMobileFlutter.shutDown();

SDK는 FTMobileFlutter.shutDown()을 통해 일괄적으로 종료하며, Session Replay가 설치되지 않은 경우에도 사용할 수 있습니다. 반환된 Future<void>가 완료된 후 후속 재초기화 작업을 수행하세요.

종료 후에도 계속 수집하려면 FTMobileFlutter.sdkConfig(...)와 필요한 RUM, Log, Trace 구성을 다시 호출하세요. Session Replay를 사용하는 경우 FTSessionReplayManager().setConfig(...)도 다시 호출해야 하며, 녹화할 뷰가 SessionReplayCapture로 감싸져 있는지 확인해야 합니다. Session Replay API는 독립 패키지 ft_session_replay_flutter에서 import합니다.

문서 평가

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