동적 구성 및 동적 업데이트 주소¶
이 문서의 예시에서는 FTSDKAgent와 FTSDKConfig를 사용합니다. 기존 프로젝트에서 사용하는 FTMobileAgent와 FTMobileConfig는 해당 호환 인터페이스를 통해 계속 연동할 수 있습니다.
원격 구성¶
원격 구성을 통해 플랫폼에서 배포한 환경 변수를 가져와 SDK 수집 구성을 조정합니다. SDK 초기화 시 통합 콜백을 등록하거나, 비즈니스에서 필요할 때 능동적으로 가져와 구성 적용 전에 사용자 정의 처리를 수행할 수 있습니다.
사용 전제 조건¶
메인 스레드에서 SDK를 시작하기 전에 FTSDKConfig.remoteConfiguration = YES를 설정하고 유효한 데이터 전송 주소를 구성합니다. 그런 다음 RUM을 초기화하고, FTRumConfig의 App ID로 구성을 가져올 앱을 지정합니다. 전체 연동 단계는 SDK 초기화와 RUM 구성을 참조하세요.
원격 샘플링 구성은 이미 연동된 모듈에 적용됩니다. 로그와 트레이스 수집은 각각의 초기화를 완료해야 합니다.
업데이트 방식¶
| 업데이트 방식 | 최소 업데이트 간격 | 콜백 |
|---|---|---|
| RUM 초기화, 앱이 포그라운드로 돌아올 때 자동 업데이트 시도 | remoteConfigMiniUpdateInterval, 기본값 12시간 |
초기화 시 등록한 전역 콜백 |
매개변수 없는 updateRemoteConfig |
초기화 시 설정한 간격 사용 | 전역 콜백 |
updateRemoteConfigWithMiniUpdateInterval:completion:(Swift: updateRemoteConfig(withMiniUpdateInterval:completion:)) |
이번에 전달된 간격 사용(단위: 초, 음수가 아닌 정수, 0은 간격 검사 건너뜀) |
이번 completion 지정 가능 |
최소 업데이트 간격은 요청 빈도를 제한하기 위한 것이며, SDK가 12시간마다 정기적으로 새로 고침하는 것은 아닙니다. 앱을 재시작해도 저장된 요청 시간은 재설정되지 않습니다. 직접 업데이트는 비동기 요청입니다. 0을 전달해도 초기화 조건을 충족해야 하며, 기존 요청이 실행 중이면 이번 호출을 건너뛰고 이번에 전달된 콜백에 실패 결과를 반환합니다.
콜백 및 사용자 정의 구성¶
SDK >= 1.5.19는
FTRemoteConfigFetchCompletionBlock의 반환값을 통해 최종 구성을 사용자 정의하여 수정하는 것을 지원합니다.
콜백은 구성 적용 전에 실행되며, 각 매개변수의 의미는 다음과 같습니다.
| 매개변수 | 의미 |
|---|---|
success |
이번 가져오기 작업의 결과입니다. YES라고 해서 model, content가 비어 있지 않음을 보장하지는 않습니다. NO는 요청이 실행되지 않았거나 가져오기에 실패했음을 의미합니다. |
error |
실패 상세 정보이며, 성공 시 nil입니다. |
model |
수정 가능한 구성 모델이며, 사용 전에 비어 있지 않은지 확인해야 합니다. |
content |
이번 콜백과 연결된 구성 딕셔너리로, 사용자 정의 필드를 읽을 수 있습니다. 원격 콘텐츠가 변경되지 않은 경우 캐시된 구성에서 가져온 것일 수 있습니다. |
성공하고 model이 비어 있지 않으면 수정된 모델을 반환하며, SDK가 이를 적용하고 캐시합니다. nil을 반환하면 SDK가 콜백에 전달하기 전의 모델을 사용합니다. 실패 시 nil을 반환합니다. 콜백은 메인 스레드에서 실행됨을 보장하지 않으므로, UI를 업데이트할 때는 메인 스레드로 전환해야 합니다.
이번에 전달된 비어 있지 않은 completion은 FTSDKConfig.remoteConfigFetchCompletionBlock보다 우선하며, 둘은 동시에 실행되지 않습니다. 매개변수 없는 updateRemoteConfig는 전역 콜백을 사용합니다. 명시적으로 nil을 전달한 경우 실제 요청을 시작한 뒤에는 전역 콜백을 사용하지만, 요청 전 검사에 통과하지 못한 결과는 전역 콜백에 통지되지 않을 수 있습니다.
실제 요청이 성공했고 원격 콘텐츠가 변경되지 않은 경우에도 콜백은 실행되며 기존 모델이 전달됩니다. success = YES는 서버 구성이 변경되었음을 의미하지 않습니다.
코드 예시
SDK 1.6.8부터 다음 소수 백분율 샘플링 필드를 지원하며, 값 범위는
[0,100]입니다. 기존 샘플링 속성은 호환성을 위해 유지되며, 필드와 우선순위는 환경 변수를 참조하세요.
예시에서는 config, rumConfig 생성은 생략하고, 콜백을 초기화와 비즈니스 갱신 모두에서 접근할 수 있는 위치에 저장합니다. 두 시나리오는 시점을 달리하여 실행합니다. 시작 시 콜백을 등록하고, 이후 비즈니스 트리거 지점에서 능동적으로 업데이트합니다.
custom_userid는 원격에서 전달되는 사용자 정의 필드입니다. 예시에서는 이 필드가 일치할 때 세 가지 샘플링 비율을 100%로 설정합니다. 현재 로그인한 사용자에 맞게 조정하려면 비즈니스 측 사용자 ID를 함께 사용해야 하며, 사용자 전환 후 구성 복구도 처리해야 합니다.
// 핵심: 재사용 가능한 원격 구성 콜백을 정의합니다.
FTRemoteConfigFetchCompletionBlock handler =
^FTRemoteConfigModel * _Nullable(
BOOL success,
NSError * _Nullable error,
FTRemoteConfigModel * _Nullable model,
NSDictionary<NSString *, id> * _Nullable content) {
if (!success || !model) {
return nil;
}
id userId = content[@"custom_userid"];
if ([userId isKindOfClass:NSString.class] &&
[userId isEqualToString:@"user_1"]) {
model.sessionSamplingRate = @100; // RUM: 100%
model.logSamplingRate = @100; // Log: 100%
model.traceSamplingRate = @100; // Trace: 100%
}
return model; // SDK가 수정된 구성을 사용합니다.
};
// 시나리오 1: SDK / RUM 초기화 시 설정합니다(config, rumConfig 생성은 생략).
config.remoteConfiguration = YES;
config.remoteConfigFetchCompletionBlock = handler;
[FTSDKAgent startWithConfigOptions:config];
[[FTSDKAgent sharedInstance] startRumWithConfigOptions:rumConfig];
// 시나리오 2: 이후 비즈니스에서 필요 시 능동적으로 새로 고침하며 동일한 콜백을 재사용합니다.
// 0은 최소 업데이트 간격을 무시함을 의미합니다.
[FTSDKAgent updateRemoteConfigWithMiniUpdateInterval:0
completion:handler];
// 핵심: 재사용 가능한 원격 구성 콜백을 정의합니다.
let handler: FTRemoteConfigFetchCompletionBlock = { success, error, model, content in
guard success, let model = model else {
return nil
}
let userId = content?["custom_userid"] as? String
if userId == "user_1" {
model.sessionSamplingRate = 100 // RUM: 100%
model.logSamplingRate = 100 // Log: 100%
model.traceSamplingRate = 100 // Trace: 100%
}
return model // SDK가 수정된 구성을 사용합니다.
}
// 시나리오 1: SDK / RUM 초기화 시 설정합니다(config, rumConfig 생성은 생략).
config.remoteConfiguration = true
config.remoteConfigFetchCompletionBlock = handler
FTSDKAgent.start(withConfigOptions: config)
FTSDKAgent.sharedInstance().startRum(withConfigOptions: rumConfig)
// 시나리오 2: 이후 비즈니스에서 필요 시 능동적으로 새로 고침하며 동일한 콜백을 재사용합니다.
// 0은 최소 업데이트 간격을 무시함을 의미합니다.
FTSDKAgent.updateRemoteConfig(withMiniUpdateInterval: 0, completion: handler)
데이터 전송 주소 동적 업데이트¶
FTSDKAgent를 사용하여 SDK 실행 중에 데이터 전송 주소를 동적으로 전환합니다. 설정에 성공하면 이후 데이터는 새 주소로 계속 업로드됩니다.
SDK >= 1.5.21은
setDatakitURL및setDatawayURL:clientToken:을 지원합니다.setDatakitURL과setDatawayURL:clientToken:중 하나를 선택하여 사용합니다.setDatawayURL:clientToken:을 사용할 때는 새로운clientToken도 함께 전달해야 합니다.
사용 사례 설명¶
FTSDKConfig는 초기화 시 datakitUrl 또는 datawayUrl을 전달하지 않는 방식을 지원합니다. 이 시나리오에서 SDK는 먼저 데이터 수집을 수행하지만 업로드는 하지 않습니다.
이후 [FTSDKAgent setDatakitURL:] 또는 [FTSDKAgent setDatawayURL:clientToken:]을 호출하여 데이터 전송 주소를 동적으로 설정하면, SDK는 로컬 캐시 소비를 시작하고 데이터 전송을 수행합니다.
유의할 점은 업로드 주소를 설정하지 않은 동안에도 수집된 데이터는 로컬 캐시 상한의 제한을 받는다는 것입니다. 캐시 상한은 주로 다음 구성의 영향을 함께 받습니다.
FTLoggerConfig.logCacheLimitCountFTRumConfig.rumCacheLimitCountFTSDKConfig.enableLimitWithDbSize에 해당하는 데이터베이스 캐시 상한
캐시가 상한에 도달하면 초과된 데이터가 폐기될 수 있으므로, 이 모드에서는 가능한 한 빨리 업로드 주소를 보완하거나 비즈니스 시나리오에 맞게 캐시 제한을 적절히 설정할 것을 권장합니다.
| 메서드 이름 | 유형 | 필수 | 의미 |
|---|---|---|---|
| setDatakitURL | NSString | 예 | Datakit 데이터 전송 주소를 동적으로 설정하며, 설정에 성공하면 SDK가 새 Datakit 주소로 데이터를 계속 업로드합니다. |
| setDatawayURL:clientToken: | NSString, NSString | 예 | Dataway 데이터 전송 주소와 clientToken을 동적으로 설정하며, 설정에 성공하면 SDK가 새 Dataway 주소로 데이터를 계속 업로드합니다. |