동적 구성 및 동적 업데이트 주소¶
원격 구성¶
원격 구성을 통해 플랫폼에서 배포하는 환경 변수를 가져와 SDK 수집 구성을 조정할 수 있습니다. SDK 초기화 시 통합 콜백을 등록하거나, 비즈니스 요구 시 능동적으로 가져온 후 구성을 적용하기 전에 사용자 정의 처리를 수행할 수 있습니다.
사전 조건¶
FTSdk.install(sdkConfig) 전에 FTSDKConfig.setRemoteConfiguration(true)를 통해 원격 구성을 활성화하고 유효한 보고 주소를 설정합니다. 그런 다음 RUM을 초기화하고 FTRUMConfig.setRumAppId(...)를 사용하여 구성을 가져올 앱을 지정합니다. 전체 연동 단계는 SDK 초기화 및 RUM 구성을 참고하세요.
원격 샘플링 구성은 이미 연동된 모듈에 적용됩니다. 로그 및 트레이스 수집은 각각의 초기화를 완료해야 합니다.
업데이트 방식¶
| 업데이트 방식 | 최소 업데이트 간격 | 콜백 |
|---|---|---|
| RUM 초기화, 앱이 포그라운드로 복귀할 때 자동 업데이트 시도 | setRemoteConfigMiniUpdateInterval, 기본값 12시간 |
초기화 시 등록한 전역 콜백 |
FTSdk.updateRemoteConfig() |
초기화 시 설정한 간격 사용 | 전역 콜백 |
FTSdk.updateRemoteConfig(interval, result) |
이번 호출에 전달된 interval 사용, 단위는 초이며 값은 음수가 아닌 정수입니다. 0은 간격 검사를 건너뜁니다. |
비어 있지 않은 result가 우선이며, 그렇지 않으면 전역 콜백을 사용합니다. |
최소 업데이트 간격은 요청 빈도를 제한하기 위한 것으로, SDK가 12시간마다 정기적으로 새로고침하지 않으며 앱을 재시작해도 저장된 요청 시간이 초기화되지 않습니다. 능동 업데이트는 비동기 요청입니다. 0을 전달하더라도 초기화 조건을 충족해야 하며, 이미 실행 중인 요청이 있으면 이번 호출은 건너뜁니다.
콜백 및 사용자 정의 구성¶
ft-sdk >= 1.6.16은FetchResult.onConfigSuccessFetched를 통해 원격 구성을 사용자 정의하여 조정하는 것을 지원합니다.
FETCH_RESULT의 두 메서드 역할은 다음과 같습니다.
| 메서드 | 호출 시점 및 용도 |
|---|---|
onConfigSuccessFetched(configBean, jsonConfig) |
유효하고 변경된 원격 구성을 가져온 후 구성을 적용하기 전에 호출됩니다. jsonConfig는 응답의 content에 해당하는 JSON이며, 사용자 정의 필드를 파싱한 뒤 수정된 configBean을 반환할 수 있습니다. null을 반환하면 전달된 객체를 그대로 사용합니다. |
onResult(success) |
이번 업데이트 결과를 반환합니다. true는 구성이 적용되었거나 원격 콘텐츠가 변경되지 않았음을 의미하고, false는 업데이트 실패, RUM App ID 누락 또는 최소 간격 미충족 등을 의미합니다. |
이번 호출에 전달된 비어 있지 않은 콜백은 전역 콜백을 대체하며, 두 콜백은 동시에 실행되지 않습니다. SDK가 초기화되지 않았거나 원격 구성이 활성화되지 않았거나 이미 요청이 실행 중인 경우, 능동 호출은 콜백을 받지 못할 수 있습니다. 콜백은 메인 스레드에서 실행된다고 보장되지 않으므로 UI를 업데이트할 때는 메인 스레드로 전환해야 합니다.
최종 구성은 적용되어 로컬 캐시에 기록됩니다. 원격 콘텐츠가 변경되지 않은 경우 onResult(true)만 실행되며, 능동 업데이트에 0을 전달하더라도 onConfigSuccessFetched가 다시 실행되지는 않습니다. 로컬 사용자 또는 비즈니스 조건의 변경은 구성을 자동으로 다시 계산하도록 트리거하지 않습니다.
코드 예시
다음 샘플링 setter는
ft-sdk >= 1.7.6이 필요하며, 값 범위는[0,100]이고 소수를 지원합니다. 이전 샘플링 메서드는[0,1]단위를 유지합니다. 필드 및 호환성 설명은 환경 변수를 참고하세요.
예시에서는 sdkConfig, rumConfig 생성 부분을 생략하고 콜백을 초기화와 비즈니스 새로고침 양쪽에서 접근할 수 있는 위치에 저장합니다. 두 시나리오는 시간대를 나누어 실행됩니다. 시작 시 콜백을 등록하고, 이후 비즈니스 트리거 지점에서 능동적으로 업데이트합니다.
custom_userid는 원격으로 배포되는 사용자 정의 필드입니다. 예시에서는 이 필드가 일치할 때 세 가지 샘플링 비율을 100%로 설정합니다. 현재 로그인한 사용자에 따라 조정하려면 비즈니스 측 사용자 ID와 결합해야 하며, 사용자 전환 후 구성 복구도 처리해야 합니다.
// 핵심: 사용자 정의 원격 구성 콜백으로, 초기화와 능동 업데이트에서 공용으로 사용합니다.
final FTRemoteConfigManager.FetchResult FETCH_RESULT =
new FTRemoteConfigManager.FetchResult() {
@Override
public RemoteConfigBean onConfigSuccessFetched(
RemoteConfigBean configBean, String jsonConfig) {
// 원격 구성을 적용하기 전에 사용자 정의 필드를 파싱하여 구성을 재정의할 수 있습니다.
try {
JSONObject json = new JSONObject(jsonConfig);
String userId = json.optString("custom_userid", "");
if ("custom_user_test6".equals(userId)) {
// 샘플링 비율 범위: 0~100, 100f는 100%를 의미합니다.
configBean.setSessionSamplingRate(100f);
configBean.setLogSamplingRate(100f);
configBean.setTraceSamplingRate(100f);
}
} catch (JSONException e) {
// 사용자 정의 파싱에 실패하면 원래 구성을 유지합니다.
}
return configBean;
}
@Override
public void onResult(boolean success) {
// true: 업데이트 성공 또는 구성이 변경되지 않음.
// false: 업데이트 실패 또는 최소 업데이트 간격 미충족 등.
}
};
// 시나리오 1: SDK / RUM 초기화 시 원격 구성을 활성화하고 콜백을 등록합니다.
sdkConfig.setRemoteConfiguration(true)
.setRemoteConfigurationCallBack(FETCH_RESULT);
FTSdk.install(sdkConfig);
FTSdk.initRUMWithConfig(rumConfig); // 기존 RUM 구성 사용, RUM App ID 포함.
// 시나리오 2: 이후 비즈니스에서 필요에 따라 능동 업데이트, 0은 최소 업데이트 간격을 무시함을 의미합니다.
// 구성이 변경되지 않은 경우 onResult(true)만 콜백되며, 사용자 정의 파싱은 다시 실행되지 않습니다.
FTSdk.updateRemoteConfig(0, FETCH_RESULT);
// 핵심: 사용자 정의 원격 구성 콜백으로, 초기화와 능동 업데이트에서 공용으로 사용합니다.
val FETCH_RESULT = object : FTRemoteConfigManager.FetchResult() {
override fun onConfigSuccessFetched(
configBean: RemoteConfigBean,
jsonConfig: String
): RemoteConfigBean {
// 원격 구성을 적용하기 전에 사용자 정의 필드를 파싱하여 구성을 재정의할 수 있습니다.
try {
val json = JSONObject(jsonConfig)
val userId = json.optString("custom_userid", "")
if (userId == "custom_user_test6") {
// 샘플링 비율 범위: 0~100, 100f는 100%를 의미합니다.
configBean.setSessionSamplingRate(100f)
configBean.setLogSamplingRate(100f)
configBean.setTraceSamplingRate(100f)
}
} catch (e: JSONException) {
// 사용자 정의 파싱에 실패하면 원래 구성을 유지합니다.
}
return configBean
}
override fun onResult(success: Boolean) {
// true: 업데이트 성공 또는 구성이 변경되지 않음.
// false: 업데이트 실패 또는 최소 업데이트 간격 미충족 등.
}
}
// 시나리오 1: SDK / RUM 초기화 시 원격 구성을 활성화하고 콜백을 등록합니다.
sdkConfig.setRemoteConfiguration(true)
.setRemoteConfigurationCallBack(FETCH_RESULT)
FTSdk.install(sdkConfig)
FTSdk.initRUMWithConfig(rumConfig) // 기존 RUM 구성 사용, RUM App ID 포함.
// 시나리오 2: 이후 비즈니스에서 필요에 따라 능동 업데이트, 0은 최소 업데이트 간격을 무시함을 의미합니다.
// 구성이 변경되지 않은 경우 onResult(true)만 콜백되며, 사용자 정의 파싱은 다시 실행되지 않습니다.
FTSdk.updateRemoteConfig(0, FETCH_RESULT)
AndroidID 가져오기 동적 활성화 및 비활성화¶
FTSdk를 사용하여 SDK에서 Android ID를 가져올지 여부를 설정합니다.
보고 주소 동적 업데이트¶
FTSdk를 사용하여 SDK 실행 중 데이터 보고 주소를 동적으로 전환합니다. 설정에 성공하면 이후 데이터는 새 주소로 계속 업로드됩니다.
ft-sdk >= 1.6.17에서 지원됩니다.
setDatakitUrl과setDatawayUrl중 하나를 선택하여 사용합니다.setDatawayUrl을 사용할 때는 새로운clientToken도 함께 전달해야 합니다.
사용 사례 설명¶
FTSDKConfig.builder()는 초기화 시 datakitUrl 또는 datawayUrl을 전달하지 않는 것을 지원합니다. 이 시나리오에서는 SDK가 먼저 데이터 수집을 수행하지만 업로드는 하지 않습니다.
이후 FTSdk.setDatakitUrl(...) 또는 FTSdk.setDatawayUrl(..., ...)을 호출하여 보고 주소를 동적으로 설정하면, SDK는 로컬 캐시를 소비하고 데이터 보고를 시작합니다.
주의할 점은 업로드 주소가 설정되지 않은 동안 수집된 데이터도 로컬 캐시 상한의 제한을 받는다는 것입니다. 캐시 상한은 주로 다음 구성의 영향을 함께 받습니다.
FTLoggerConfig.setLogCacheLimitCountFTRUMConfig.setRumCacheLimitCountFTSDKConfig.enableLimitWithCacheSize에 해당하는 전체 캐시 크기 상한
캐시가 상한에 도달하면 초과된 데이터가 유실될 수 있으므로, 이 모드에서는 가능한 한 빨리 업로드 주소를 보완하거나 비즈니스 시나리오에 맞게 캐시 제한을 적절히 설정하는 것이 좋습니다.
| 메서드 이름 | 유형 | 필수 | 의미 |
|---|---|---|---|
| setDatakitUrl | String | 예 | Datakit 보고 주소를 동적으로 설정하며, 설정에 성공하면 SDK는 새 Datakit 주소로 데이터를 계속 업로드합니다. |
| setDatawayUrl | String, String | 예 | Dataway 보고 주소와 clientToken을 동적으로 설정하며, 설정에 성공하면 SDK는 새 Dataway 주소로 데이터를 계속 업로드합니다. |