콘텐츠로 이동

SDK 초기화

이 문서는 UniApp SDK 초기화 및 런타임 기본 기능에 대한 내용을 담고 있습니다.

기본 설정

<script>
var ftModule = uni.requireNativePlugin("GCUniPlugin-MobileAgent");

export default {
    onLaunch: function() {
        ftModule.sdkConfig({
            datakitUrl: 'your datakitUrl',
            debug: true,
            env: 'common',
            globalContext: {
                custom_key: 'custom value'
            }
        });
    }
}
</script>
파라미터 이름 파라미터 유형 필수 파라미터 설명
datakitUrl string 아니요 로컬 환경(Datakit) 전송 URL 주소. 예: http://10.0.0.1:9529. datawayUrl과 둘 중 하나를 선택; 0.2.7 이상에서는 초기화 시 설정하지 않고 이후 setDatakitURL로 동적 설정 가능
datawayUrl string 아니요 공용 네트워크 DataWay 전송 URL 주소. datakitUrl과 둘 중 하나를 선택; 0.2.7 이상에서는 초기화 시 설정하지 않고 이후 setDatawayURL로 동적 설정 가능
clientToken string datawayUrl 사용 시 필수 인증 토큰, datawayUrl과 함께 사용해야 함
debug boolean 아니요 Debug 로그 출력 여부, 기본값 false
env string 아니요 환경 이름, 기본값 prod, 단일 단어 권장. 예: test
service string 아니요 소속 비즈니스 또는 서비스 이름, 기본값: df_rum_ios, df_rum_android
globalContext object 아니요 초기화 시 추가되는 전역 태그
offlinePackage boolean 아니요 Android만 지원, 오프라인 패키징 또는 uni 미니 프로그램 사용 여부, 기본값 false, 자세한 내용은 애플리케이션 연동 FAQ 참조
autoSync boolean 아니요 데이터 수집 후 서버에 자동 동기화 여부, 기본값 YES. NO인 경우 flushSyncData를 사용하여 동기화 직접 관리
syncPageSize number 아니요 동기화 요청 항목 수 설정, 범위 [5,), 기본값 10
syncSleepTime number 아니요 동기화 간격 시간 설정, 범위 [0,5000], 기본값 미설정
enableDataIntegerCompatible boolean 아니요 Web 데이터와 공존 시 활성화 권장; 0.2.1 이후 기본 활성화
compressIntakeRequests boolean 아니요 동기화 데이터에 deflate 압축 적용 여부, 기본 비활성화, SDK 0.2.0 이상 지원
enableLimitWithDbSize boolean 아니요 DB 용량 제한 활성화 여부, 기본 비활성화. 활성화 시 logCacheLimitCountrumCacheLimitCount가 적용되지 않음
dbCacheLimit number 아니요 DB 캐시 제한 크기, 범위 [30MB,), 기본값 100MB, 단위 byte
dbDiscardStrategy string 아니요 DB 데이터 폐기 전략: discard 새 데이터 폐기(기본값), discardOldest 이전 데이터 폐기
dataModifier object 아니요 단일 필드 마스킹 수정, 자세한 내용은 데이터 수집 마스킹 참조
lineDataModifier object 아니요 단일 데이터 마스킹 수정, 자세한 내용은 데이터 수집 마스킹 참조
remoteConfiguration boolean 아니요 데이터 수집 원격 설정 활성화 여부, 기본값 false. 활성화 시 SDK 초기화 또는 앱 핫 스타트 시 설정 업데이트가 트리거됨; Datakit 버전 >= 1.60 필요 또는 공용 네트워크 DataWay 사용, SDK 0.2.7 이상 지원
remoteConfigMiniUpdateInterval number 아니요 원격 설정 최소 업데이트 간격, 범위 [0,), 단위 초, 기본값 12시간, SDK 0.2.7 이상 지원
enableDataFilter boolean 아니요 DataKit 호환 데이터 필터링 활성화 여부, 기본값 true; 로컬 및 원격 규칙 모두 이 스위치의 제어를 받음, SDK 0.2.7 이상 지원
dataFilters object 아니요 로컬 데이터 필터링 규칙, key는 logging, rum 지원, value는 규칙 문자열 배열, SDK 0.2.7 이상 지원

원격 설정 및 데이터 필터링

var ftModule = uni.requireNativePlugin("GCUniPlugin-MobileAgent");

ftModule.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 이후에 실행되므로 수정된 데이터를 기준으로 판단합니다.
  • 각 규칙은 { 조건 } 형식으로 작성합니다. 지원되는 필드 및 값 형식은 블랙리스트 필터 규칙을 참조하세요. 규칙이 너무 많거나 정규 표현식이 지나치게 복잡하면 데이터 쓰기 성능에 영향을 줄 수 있습니다.

사용자 정보 바인딩 및 해제

var ftModule = uni.requireNativePlugin("GCUniPlugin-MobileAgent");

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

ftModule.unbindRUMUserData();

API - bindRUMUserData

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

API - unbindRUMUserData

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

런타임 기능

전송 URL 동적 업데이트

SDK 0.2.7 이상에서 초기화 후 전송 주소를 동적으로 설정할 수 있습니다. setDatakitURLsetDatawayURL 중 하나를 선택하여 사용합니다. DataWay로 전환할 때는 clientToken을 함께 전달해야 합니다.

초기화 시 datakitUrldatawayUrl을 모두 생략할 수 있습니다. 유효한 전송 주소가 설정되기 전까지 SDK는 초기화 및 데이터 수집 캐싱을 수행할 수 있습니다. 주소를 설정하면 해당 주소로 업로드를 시작합니다.

var ftModule = uni.requireNativePlugin("GCUniPlugin-MobileAgent");

ftModule.setDatakitURL({
    datakitUrl: 'http://10.0.0.1:9529'
});

// DataWay 사용 시 setDatakitURL 대신 다음 메서드를 호출합니다.
ftModule.setDatawayURL({
    datawayUrl: 'https://open.dataway.url',
    clientToken: 'client-token'
});

API - setDatakitURL

필드 유형 필수 설명
datakitUrl string 새 Datakit 전송 주소

API - setDatawayURL

필드 유형 필수 설명
datawayUrl string 새 DataWay 전송 주소
clientToken string DataWay 주소와 일치하는 인증 토큰

원격 설정 수동 업데이트

호출 전에 sdkConfig에서 remoteConfiguration: true를 설정해야 합니다. miniUpdateInterval은 이번 호출에서 지정한 최소 업데이트 간격을 사용하며, 초기화 시의 remoteConfigMiniUpdateInterval은 사용하지 않습니다.

var ftModule = uni.requireNativePlugin("GCUniPlugin-MobileAgent");

ftModule.updateRemoteConfigWithMiniUpdateInterval({
    miniUpdateInterval: 0
}, result => {
    if (result.success) {
        console.log('remote config: ' + result.rawJson);
    } else {
        console.log('remote config failed: ' + result.errorMessage);
    }
});

API - updateRemoteConfigWithMiniUpdateInterval

요청 필드 유형 필수 설명
miniUpdateInterval number 아니요 이번 수동 업데이트의 최소 간격, 범위 [0,), 단위 초, 기본값 0

콜백 파라미터:

반환 필드 유형 설명
success boolean 업데이트 성공 여부
platform string 현재 플랫폼: ios 또는 android
rawJson string 업데이트 성공 시 반환되는 원격 설정 JSON 문자열, 서버에 내용이 없으면 존재하지 않을 수 있음
errorCode number/string 업데이트 실패 시 오류 코드; iOS는 숫자 반환, Android는 문자열 반환
errorMessage string 업데이트 실패 시 오류 메시지

SDK 종료

var ftModule = uni.requireNativePlugin("GCUniPlugin-MobileAgent");
ftModule.shutDown();

API - shutDown

SDK를 종료합니다.

SDK 캐시 데이터 정리

var ftModule = uni.requireNativePlugin("GCUniPlugin-MobileAgent");
ftModule.clearAllData();

API - clearAllData

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

데이터 수동 동기화

var ftModule = uni.requireNativePlugin("GCUniPlugin-MobileAgent");
ftModule.flushSyncData();

API - flushSyncData

sdkConfig.autoSynctrue로 설정한 경우 추가 작업 없이 SDK가 자동으로 동기화합니다.

sdkConfig.autoSyncfalse로 설정한 경우 이 메서드를 직접 호출하여 데이터 동기화를 트리거해야 합니다.

문서 평가

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