동적 설정 및 동적 업데이트 주소¶
동적 설정 활성화¶
동적 설정은 기본적으로 비활성화되어 있습니다. 활성화하면 SDK는 설치 시 로컬 캐시를 읽습니다. RUM 설정이 설치되어 있고 유효한 데이터 전송 주소가 있으면 SDK는 RUM 앱 ID를 사용해 서버 설정을 가져옵니다. 데이터 전송 주소를 런타임에 설정한 경우 SDK는 주소가 유효해진 후 동적 설정을 계속 가져옵니다.
import {
FTSDK,
FTSDKConfig,
FTRUMConfig,
FTRemoteConfigFetchResult,
RemoteConfigBean
} from '@guancecloud/ft_sdk/Index';
const remoteConfigResult: FTRemoteConfigFetchResult = {
// 서버가 유효하고 변경된 설정을 반환할 때 호출됩니다.
onConfigSuccessFetched(configBean: RemoteConfigBean, jsonConfig: string): RemoteConfigBean | null {
// jsonConfig를 기반으로 사용자 정의 환경 변수를 파싱하고 수정된 설정을 반환할 수 있습니다.
return configBean;
},
// 가져오기에 성공했거나 서버 설정이 변경되지 않은 경우 true이고, 요청에 실패했거나 새로 고침 간격을 충족하지 못한 경우 false입니다.
onResult(success: boolean): void {
// 필요에 따라 가져오기 결과를 기록합니다.
}
};
const sdkConfig = FTSDKConfig.builder()
.setRemoteConfiguration(true)
.setRemoteConfigMiniUpdateInterval(43200)
.setRemoteConfigurationCallBack(remoteConfigResult);
FTSDK.install(sdkConfig, this.context);
FTSDK.installRUMConfig(new FTRUMConfig().setRumAppId('your-rum-app-id'));
| 메서드 | 유형 | 기본값 | 설명 |
|---|---|---|---|
setRemoteConfiguration |
boolean |
false |
동적 설정 활성화 여부 |
setRemoteConfigMiniUpdateInterval |
number |
43200 |
최소 가져오기 간격(초)입니다. 소수는 내림 처리하고 음수는 0으로 처리합니다. 0을 전달하면 즉시 새로 고침할 수 있습니다. |
setRemoteConfigurationCallBack |
FTRemoteConfigFetchResult \| null |
null |
가져오기 결과 콜백을 설정합니다. onConfigSuccessFetched는 수정된 RemoteConfigBean을 반환할 수 있으며, onResult는 결과를 수신하는 데 사용됩니다. |
로컬 캐시는 각 설정이 설치되기 전에 병합됩니다. 기본 SDK는 환경, 서비스 이름, 업로드 관련 설정 및 WebView Host 허용 목록을 지원합니다. RUM은 샘플링 레이트와 자동 수집 스위치를 지원합니다. Log는 샘플링 레이트, 레벨 및 스위치를 지원합니다. Trace는 샘플링 레이트, 자동 추적 및 유형을 지원합니다. 온라인에서 새 설정을 가져오면 업로드 스위치와 파라미터, Log 설정, Trace 샘플링 레이트, RUM 샘플링 레이트 및 오류 샘플링 레이트가 즉시 적용됩니다. WebView Host 허용 목록은 이후 새 바인딩에 적용되며, 기타 설정은 다음 초기화 시 적용됩니다.
WebView Host 허용 목록의 우선순위는 원격 rumAllowWebViewHost > 명시적으로 설정한 FTSDKConfig.setAllowWebViewHost(...) > 더 이상 사용되지 않는 FTRUMConfig.setAllowWebViewHost(...)입니다. 원격 필드가 누락되면 로컬 설정으로 복원하고, 유효하지 않은 값은 마지막으로 유효했던 원격 설정을 유지하며, 유효한 원격 설정이 없으면 로컬로 대체합니다. 캐시는 필드 누락, null, []를 구분합니다. 기존 바인딩은 설정 업데이트를 따르지 않으므로 Web 컴포넌트와 controller를 다시 생성하고 바인딩해야 합니다. Host 값은 SDK 초기화 설정을 참조하십시오.
동적 설정 직접 동기화¶
FTSDK를 사용해 동적 설정을 직접 동기화합니다. 자동 업데이트가 요구 사항을 충족하지 못할 때 직접 호출하여 업데이트 시점을 조정할 수 있습니다.
ft_sdk0.1.18 이상 버전에서는onConfigSuccessFetched(configBean, jsonConfig)를 통해 환경 변수를 직접 파싱하고 수집 설정을 조정할 수 있습니다.
/**
* 원격 설정을 직접 업데이트합니다. 호출 빈도는 FTSDKConfig.setRemoteConfigMiniUpdateInterval의 영향을 받습니다.
*/
FTSDK.updateRemoteConfig();
/**
* 원격 설정을 직접 업데이트하며, 지정된 최소 업데이트 간격을 사용합니다.
* 0을 전달하면 즉시 요청합니다.
*
* @param intervalSeconds 최소 업데이트 간격(초)입니다. 음수는 0으로 처리합니다.
* @param result 가져오기 결과 콜백으로, 초기화 시의 콜백을 재정의할 수 있습니다.
*/
FTSDK.updateRemoteConfig(intervalSeconds, result);
코드 예시¶
다음 예시는 사용자 정의 환경 변수 custom_userid를 파싱하여 custom_user_test6을 VIP 사용자로 식별하고, 해당 사용자의 RUM, Log, Trace 샘플링 레이트를 100(전체 수집)으로 설정합니다. 백분율 샘플링 API의 값 범위는 [0,100]입니다.
import {
FTSDK,
FTRemoteConfigFetchResult,
RemoteConfigBean
} from '@guancecloud/ft_sdk/Index';
interface CustomRemoteConfig {
custom_userid?: string;
}
const result: FTRemoteConfigFetchResult = {
onResult(success: boolean): void {
// 가져오기에 성공했거나 서버 설정이 변경되지 않은 경우 true입니다.
},
onConfigSuccessFetched(configBean: RemoteConfigBean, jsonConfig: string): RemoteConfigBean | null {
// 선택적 확장으로, 사용자 정의 파싱을 수행하고 로컬 설정을 변경합니다.
let isVip = false;
try {
const customConfig = JSON.parse(jsonConfig) as CustomRemoteConfig;
isVip = customConfig.custom_userid === 'custom_user_test6';
} catch (error) {
// 파싱에 실패하면 기존 설정을 유지합니다.
}
if (isVip) {
configBean.setSessionSamplingRate(100);
configBean.setLogSamplingRate(100);
configBean.setTraceSamplingRate(100);
}
return configBean;
}
};
// 0을 전달하면 즉시 요청하며, 이번 콜백으로 초기화 시의 콜백을 재정의합니다.
FTSDK.updateRemoteConfig(0, result);
기기 식별자 동적 활성화 및 비활성화¶
FTSDK를 사용해 SDK에서 시스템 기기 식별자를 가져올지 여부를 설정합니다. 기본적으로 SDK에 영구 저장된 프라이버시 UUID를 device_uuid로 사용합니다. 활성화하면 SDK는 ODID를 우선 가져오고, ODID를 사용할 수 없으면 UDID로 대체하며, UDID도 사용할 수 없으면 프라이버시 UUID를 사용합니다.
// 시스템 기기 식별자 접근 활성화
FTSDK.setEnableAccessDeviceID(true);
// SDK 프라이버시 UUID로 전환
FTSDK.setEnableAccessDeviceID(false);
데이터 전송 주소 동적 업데이트¶
FTSDK를 사용해 SDK 런타임에 데이터 전송 주소를 동적으로 전환합니다. FTSDK.install(...) 완료 후 호출하십시오. 설정에 성공하면 이후 데이터는 새 주소로 계속 업로드됩니다.
setDatakitUrl과setDatawayUrl중 하나를 선택해 사용합니다.setDatawayUrl을 사용할 때는 새clientToken도 함께 전달해야 합니다.
사용 사례 설명¶
FTSDKConfig.builder()는 초기화 시 datakitUrl 또는 datawayUrl을 전달하지 않는 것을 지원합니다. 이 시나리오에서는 SDK가 먼저 데이터 수집을 수행하지만 데이터를 업로드하지 않습니다.
이후 FTSDK.setDatakitUrl(...) 또는 FTSDK.setDatawayUrl(..., ...)를 호출해 완전하고 유효한 HTTP(S) 전송 주소를 설정하면 SDK는 로컬 캐시 소비를 시작하고 자동 업로드를 재개합니다. DataWay 모드에는 유효한 클라이언트 토큰도 필요합니다. 상대 경로, HTTP(S)가 아닌 프로토콜 또는 형식이 잘못된 주소는 자동 업로드를 재개하지 않습니다. 즉시 업로드를 요청하려면 FTSDK.flushSyncData()를 호출하십시오.
동적 설정이 활성화된 경우 유효한 전송 주소로 전환하면 SDK는 새 주소에서 원격 설정을 즉시 새로 고칩니다. 이전 주소의 진행 중인 요청 결과는 무시됩니다. 블랙리스트 필터링이 활성화된 경우 SDK는 이전 주소의 원격 규칙을 지우고 새 주소에서 즉시 다시 가져옵니다. 로컬 규칙은 계속 유지됩니다.
런타임에 설정한 주소는 메모리에만 저장되므로 앱을 다시 시작한 후에는 다시 설정해야 합니다. SDK 설치 전에 전송 주소를 설정하려면 FTSDKConfig.builder()가 반환한 설정 객체에서 setDatakitUrl(...) 또는 setDatawayUrl(...)을 호출하십시오. 자세한 내용은 SDK 초기화를 참조하십시오.
업로드 주소가 설정되지 않은 동안 수집된 데이터는 여전히 로컬 캐시 상한의 제한을 받습니다. 캐시가 상한에 도달하면 초과된 데이터가 폐기될 수 있으므로, 가능한 한 빨리 전송 주소를 추가하고 비즈니스 시나리오에 맞게 캐시 제한을 적절히 설정할 것을 권장합니다.
import { FTSDK } from '@guancecloud/ft_sdk/Index';
// DataKit을 사용해 전송
FTSDK.setDatakitUrl('http://10.0.0.1:9529');
// 또는 DataWay를 사용해 전송
FTSDK.setDatawayUrl('https://open.dataway.url', 'your-client-token');
| 메서드 이름 | 유형 | 필수 | 의미 |
|---|---|---|---|
setDatakitUrl |
string |
예 | FTSDK.install(...) 후 DataKit 전송 주소를 동적으로 설정합니다. 설정에 성공하면 SDK는 새 DataKit 주소로 데이터를 계속 업로드합니다. |
setDatawayUrl |
string, string |
예 | FTSDK.install(...) 후 DataWay 전송 주소와 clientToken을 동적으로 설정합니다. 설정에 성공하면 SDK는 새 DataWay 주소로 데이터를 계속 업로드합니다. |