동적 구성 및 동적 업데이트 주소¶
이 문서는 React Native SDK의 원격 구성, 직접 업데이트 및 동적 업데이트 전송 주소 기능을 설명합니다.
동적 구성¶
사전 조건¶
FTMobileConfig.remoteConfiguration = true인 경우에만 동적 구성 관련 기능이 적용됩니다.
원격 구성 업데이트 수신¶
원격 구성을 활성화한 후 SDK가 자동으로 트리거하는 원격 구성 업데이트 결과를 수신할 수 있습니다.
/**
* 네이티브 SDK가 자동으로 트리거하는 원격 구성 업데이트를 수신합니다.
* 동적 구성을 직접 동기화하는 메서드를 호출한 Promise의 반환값은 이 이벤트 콜백을 통해 전달되지 않습니다.
*/
addRemoteConfigListener(
listener: (result: FTRemoteConfigResult) => void,
): EmitterSubscription;
사용 예시¶
동적 구성 직접 동기화¶
FTMobileReactNative를 사용하여 동적 구성을 직접 동기화합니다. 자동 업데이트가 요구 사항을 충족하지 못할 때 직접 호출하는 방식으로 업데이트 시점을 조정할 수 있습니다.
/**
* 원격 구성을 직접 업데이트하며, 호출 빈도는 FTMobileConfig.remoteConfigMiniUpdateInterval의 영향을 받습니다.
*/
updateRemoteConfig(): Promise<FTRemoteConfigResult>;
/**
* 원격 구성을 직접 업데이트하며, 전역 최소 업데이트 간격 구성을 무시할 수 있습니다.
* 마지막 업데이트로부터 경과한 시간이 지정된 간격보다 짧으면 업데이트 작업을 수행하지 않습니다.
* @param interval 최소 업데이트 간격, 단위: 초
* @param rules 원격 구성 재정의 규칙
*/
updateRemoteConfigWithMiniUpdateInterval(
interval: number,
rules?: Array<FTRemoteConfigOverrideRule>,
): Promise<FTRemoteConfigResult>;
사용 예시¶
// 기본 직접 동기화 업데이트(전역 최소 간격 제한 적용)
FTMobileReactNative.updateRemoteConfig();
const rule: FTRemoteConfigOverrideRule = {
id: 'test_rule',
match: {
customKeys: {
custom_key: 'custom_value',
vip_user_id: {
contains: 'test_user_1001',
},
},
},
override: {
sessionSamplingRate: 100,
traceSamplingRate: 100,
logSamplingRate: 100,
logLevelFilters: ['info', 'warn'],
},
};
const result = await FTMobileReactNative.updateRemoteConfigWithMiniUpdateInterval(0, [rule]);
console.log('updateRemoteConfigWithMiniUpdateInterval result ', result);
FTMobileReactNative.updateRemoteConfigWithMiniUpdateInterval(0, null);
customKeys의 값이 일반 값이면 완전 일치로 처리하고, 값이 { contains: value }이면 포함 일치로 처리합니다.
contains는 주로 vip_user_id와 같이 고정 key를 기준으로 특정 사용자를 매칭하는 사용 사례에 사용됩니다. 서버 측 해당 필드가 다음 형식 중 하나로 반환되면 모두 매칭할 수 있습니다:
- 단일 문자열, 예:
"test_user_1001" - JSON 배열, 예:
["test_user_1001", "test_user_1002"] - JSON 문자열 배열, 예:
"[\"test_user_1001\",\"test_user_1002\"]"
샘플링 재정의 필드¶
SDK 0.4.3부터 지원합니다.
FTRemoteConfigOverrideRule.override는 다음 백분율 필드를 지원하며, 범위는 모두 [0,100]이고 소수를 허용합니다. 생략된 필드는 해당 규칙에 의해 수정되지 않습니다.
| 백분율 필드 | 의미 | 사용 중단된 이전 확률 필드([0,1]) |
|---|---|---|
| sessionSamplingRate | RUM 세션 샘플링 | rumSampleRate |
| sessionOnErrorSamplingRate | 오류 세션 샘플링 | rumSessionOnErrorSampleRate |
| traceSamplingRate | Trace 샘플링 | traceSampleRate |
| logSamplingRate | Log 샘플링 | logSampleRate |
| sessionReplaySamplingRate | Session Replay 샘플링 | — |
| sessionReplayOnErrorSamplingRate | 오류 상황 Session Replay 샘플링 | — |
예를 들어 sessionSamplingRate: 12.5는 12.5%를, 1은 1%를, 100은 전체 수집을 의미합니다. 동일 항목에 새 필드와 이전 필드를 동시에 설정하면 0을 포함하여 새 필드가 우선합니다. 위 예시는 SDK 0.4.3부터 지원되는 필드를 사용합니다. 이전 버전에서는 해당 확률 필드를 계속 사용하세요. 이전 확률 필드는 SDK 0.4.3부터 지원 중단되었지만 호환성을 위해 유지됩니다. 서버에서 제공할 수 있는 샘플링 필드는 원격 구성 필드를 참조하세요. 위 표의 —는 재정의 규칙이 해당 이전 필드를 제공하지 않음을 의미합니다.
동적 업데이트 전송 주소¶
FTMobileReactNative를 사용하여 SDK 실행 중에 데이터 전송 주소를 동적으로 전환합니다. 설정에 성공하면 이후 데이터는 새 주소로 계속 업로드됩니다.
SDK 0.4.1부터 동적 업데이트 전송 주소를 지원합니다.
setDatakitURL과setDatawayURL중 하나를 선택하여 사용합니다.setDatawayURL을 사용할 때는 새clientToken을 함께 전달해야 합니다.
사용 사례 설명¶
런타임 중 전송 주소 전환¶
초기화 시 전송 주소가 이미 구성되어 있고 애플리케이션 실행 과정에서 데이터 수신 엔드포인트를 변경해야 하는 경우, setDatakitURL() 또는 setDatawayURL()을 호출하여 주소를 업데이트할 수 있습니다. DataWay를 사용할 때는 새 주소에 해당하는 clientToken도 함께 전달해야 합니다.
전송 주소 지연 설정¶
SDK 0.4.3부터 지원합니다.
FTMobileConfig에서는 초기화 시 datakitUrl, datawayUrl, clientToken을 비워 둔 후 이후 setDatakitURL() 또는 setDatawayURL()을 통해 구성을 보완할 수 있습니다. DataWay를 사용할 때는 clientToken도 함께 제공해야 합니다. 이 사용 사례에서는 SDK가 먼저 데이터 수집을 수행하지만 업로드는 수행하지 않습니다.
이후 FTMobileReactNative.setDatakitURL(...) 또는 FTMobileReactNative.setDatawayURL(..., ...)을 호출하여 전송 주소를 동적으로 설정하면 SDK가 로컬 캐시를 처리하기 시작하고 데이터 전송을 수행합니다.
유의할 점은 업로드 주소가 설정되지 않은 동안 수집된 데이터는 여전히 로컬 캐시 상한의 제한을 받는다는 것입니다. 캐시 상한은 주로 다음 구성의 영향을 함께 받습니다:
FTLogConfig.logCacheLimitCountFTRUMConfig.rumCacheLimitCountFTMobileConfig.enableLimitWithDbSize에 해당하는 데이터베이스 캐시 상한
캐시가 상한에 도달하면 초과된 데이터가 유실될 수 있으므로, 이 모드에서는 가능한 한 빨리 업로드 주소를 보완하거나 비즈니스 사용 사례에 맞게 캐시 제한을 적절히 설정할 것을 권장합니다.
사용 방법¶
/**
* Datakit 전송 주소를 동적으로 설정하며, 설정에 성공하면 SDK가 새 Datakit 주소로 데이터를 계속 업로드합니다.
*/
setDatakitURL(datakitUrl: string): Promise<void>;
/**
* Dataway 전송 주소와 clientToken을 동적으로 설정하며, 설정에 성공하면 SDK가 새 Dataway 주소로 데이터를 계속 업로드합니다.
*/
setDatawayURL(datawayUrl: string, clientToken: string): Promise<void>;
사용 예시¶
await FTMobileReactNative.setDatakitURL('http://10.0.0.1:9529');
await FTMobileReactNative.setDatawayURL(
'https://open.dataway.url',
'your-client-token',
);
| 메서드 이름 | 유형 | 필수 | 의미 |
|---|---|---|---|
| setDatakitURL | string | 예 | Datakit 전송 주소를 동적으로 설정하며, 설정에 성공하면 SDK가 새 Datakit 주소로 데이터를 계속 업로드합니다. |
| setDatawayURL | string, string | 예 | Dataway 전송 주소와 clientToken을 동적으로 설정하며, 설정에 성공하면 SDK가 새 Dataway 주소로 데이터를 계속 업로드합니다. |