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 용량 제한 활성화 여부, 기본 비활성화. 활성화 시 logCacheLimitCount와 rumCacheLimitCount가 적용되지 않음 |
| 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 이상에서 초기화 후 전송 주소를 동적으로 설정할 수 있습니다. setDatakitURL과 setDatawayURL 중 하나를 선택하여 사용합니다. DataWay로 전환할 때는 clientToken을 함께 전달해야 합니다.
초기화 시 datakitUrl과 datawayUrl을 모두 생략할 수 있습니다. 유효한 전송 주소가 설정되기 전까지 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 종료¶
API - shutDown¶
SDK를 종료합니다.
SDK 캐시 데이터 정리¶
API - clearAllData¶
아직 서버에 업로드되지 않은 모든 데이터를 삭제합니다.
데이터 수동 동기화¶
API - flushSyncData¶
sdkConfig.autoSync를 true로 설정한 경우 추가 작업 없이 SDK가 자동으로 동기화합니다.
sdkConfig.autoSync를 false로 설정한 경우 이 메서드를 직접 호출하여 데이터 동기화를 트리거해야 합니다.