SDK 초기화¶

이 문서에서는 0.3.0 이상 버전의 Mobile SDK 초기화 및 런타임 기본 API에 대해 설명합니다.

API 객체 가져오기¶

일반 uni-app은 UTS 모듈에서 가져오고, 앱 진입점에서 setup.js를 한 번 로드합니다:

import '@/uni_modules/GC-UniPlugin/setup.js';
import { mobileAgent } from '@/uni_modules/GC-UniPlugin';

uni 미니프로그램은 공용 JS 레이어에서 가져옵니다:

import { mobileAgent } from '@/uni_modules/GC-JSPlugin';

uni 미니프로그램의 SDK는 호스트 앱에서 초기화되며, sdkConfig()를 호출하지 않습니다. 이 페이지의 다른 런타임 API는 호스트 초기화가 완료된 후에 호출할 수 있습니다.

기본 설정¶

mobileAgent.sdkConfig({
    datakitUrl: 'http://10.0.0.1:9529',
    debug: true,
    env: 'common',
    globalContext: {
        custom_key: 'custom value'
    }
});

매개변수 이름	매개변수 유형	필수	설명
datakitUrl	string	아니요	로컬 환경에 배포된 Datakit 업로드 주소, 예: `http://10.0.0.1:9529`. `datawayUrl`과 선택적으로 사용합니다. 초기화 시 설정하지 않을 수 있으며, 이후 `setDatakitURL`을 통해 동적으로 설정할 수 있습니다.
datawayUrl	string	아니요	공용 네트워크 DataWay 업로드 주소. `datakitUrl`과 선택적으로 사용합니다. 초기화 시 설정하지 않을 수 있으며, 이후 `setDatawayURL`을 통해 동적으로 설정할 수 있습니다.
clientToken	string	`datawayUrl` 사용 시 필수	DataWay 주소와 일치하는 인증 토큰
debug	boolean	아니요	Debug 로그 출력 여부, 기본값 `false`
env	string	아니요	환경 이름, 기본값 `prod`, 단일 단어 사용 권장 (예: `test`)
service	string	아니요	속한 비즈니스 또는 서비스 이름, 기본값은 플랫폼 SDK에 의해 결정됩니다.
globalContext	object	아니요	초기화 시 추가되는 글로벌 태그
offlinePackage	boolean	아니요	Android 전용. 일반 uni-app 오프라인 패키징 또는 기존 `0.2.x` uni 미니프로그램 프로젝트가 JS 측에서 SDK를 초기화하는 경우 `true`로 설정합니다. 기본값 `false`. 자세한 내용은 Android 클라우드 패키징과 오프라인 패키징 차이점을 참조하십시오.
autoSync	boolean	아니요	데이터 자동 동기화 여부, 기본값 `true`; 비활성화 시 `flushSyncData`를 사용하여 수동으로 동기화합니다.
syncPageSize	number	아니요	단일 동기화의 데이터 항목 수, 범위 `[5,)`, 기본값 `10`
syncSleepTime	number	아니요	동기화 간격 시간, 범위 `[0,5000]`, 단위 밀리초
enableDataIntegerCompatible	boolean	아니요	데이터 정수 호환 처리 활성화 여부, 기본값 활성화
compressIntakeRequests	boolean	아니요	동기화 데이터에 deflate 압축 적용 여부, 기본값 비활성화
enableLimitWithDbSize	boolean	아니요	DB 용량 제한 활성화 여부; 활성화 시 `logCacheLimitCount`와 `rumCacheLimitCount`가 무시됩니다.
dbCacheLimit	number	아니요	DB 캐시 제한, 범위 `[30MB,)`, 기본값 `100MB`, 단위 byte
dbDiscardStrategy	string	아니요	DB 데이터 폐기 전략: `discard`(기본값) 또는 `discardOldest`
dataModifier	object	아니요	단일 필드 마스킹 수정, 자세한 내용은 데이터 수집 마스킹을 참조하십시오.
lineDataModifier	object	아니요	단일 데이터 마스킹 수정, 자세한 내용은 데이터 수집 마스킹을 참조하십시오.
remoteConfiguration	boolean	아니요	원격 설정 활성화 여부, 기본값 `false`; 활성화 시 SDK 초기화 또는 앱 핫 스타트 시 설정 업데이트가 트리거됩니다.
remoteConfigMiniUpdateInterval	number	아니요	원격 설정 최소 업데이트 간격, 범위 `[0,)`, 단위 초, 기본값 12시간
enableDataFilter	boolean	아니요	DataKit 호환 데이터 필터링 활성화 여부, 기본값 `true`
dataFilters	object	아니요	로컬 데이터 필터 규칙; key는 `logging`, `rum`을 지원하며, value는 규칙 문자열 배열입니다.

원격 설정 및 데이터 필터링¶

mobileAgent.sdkConfig({
    datakitUrl: 'http://10.0.0.1:9529',
    remoteConfiguration: true,
    remoteConfigMiniUpdateInterval: 600,
    enableDataFilter: true,
    dataFilters: {
        logging: [
            "{ message match [ 'password' ] }"
        ],
        rum: [
            "{ resource_status match [ '5..' ] }"
        ]
    }
});

remoteConfiguration은 샘플링 비율 등 SDK 설정의 원격 업데이트를 활성화하는 데 사용됩니다. 업데이트를 수동으로 트리거하려면 updateRemoteConfigWithMiniUpdateInterval을 사용할 수 있습니다.
dataFilters는 앱과 함께 배포되는 로컬 블랙리스트 규칙입니다. 규칙과 일치하는 데이터는 로컬 캐시에 기록되기 전에 폐기됩니다.
로컬 규칙과 원격 규칙이 동시에 적용됩니다. 규칙은 lineDataModifier 이후에 실행되므로 수정된 데이터를 기준으로 판단합니다.
각 규칙은 { 조건 } 형식으로 표현됩니다. 필드 및 값 형식은 블랙리스트 필터 규칙을 참조하십시오.

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

mobileAgent.bindRUMUserData({
    userId: 'Test userId',
    userName: 'Test name',
    userEmail: 'test@example.com',
    extra: {
        age: '20'
    }
});

mobileAgent.unbindRUMUserData();

API - bindRUMUserData¶

필드	유형	필수	설명
userId	string	예	사용자 ID
userName	string	아니요	사용자 이름
userEmail	string	아니요	사용자 이메일
extra	object	아니요	사용자 추가 정보

API - unbindRUMUserData¶

현재 사용자의 바인딩을 해제합니다.

런타임 기능¶

SDK 종료¶

mobileAgent.shutDown();

SDK를 종료한 후 다시 사용하려면 전체 초기화를 다시 수행해야 합니다. uni 미니프로그램은 일반적으로 호스트 앱이 보유한 SDK를 종료해서는 안 됩니다. 단, 양측이 라이프사이클 관리 방식을 협의한 경우는 예외입니다.

SDK 캐시 데이터 정리¶

mobileAgent.clearAllData();

서버에 아직 업로드되지 않은 모든 데이터를 삭제합니다.

데이터 수동 동기화¶

mobileAgent.flushSyncData();

autoSync가 true인 경우 추가 작업이 필요하지 않습니다. autoSync가 false인 경우 이 메서드를 호출하여 데이터 동기화를 트리거합니다.