Skip to content

Dynamic Configuration and Dynamic Endpoint Updates

Proactively Synchronize Dynamic Configuration

Usage

Use FTMobileAgent to proactively synchronize dynamic configuration. When automatic updates do not meet requirements, adjust the update timing through proactive method calls.

The proactive synchronization method for dynamic configuration only takes effect when FTMobileConfig.remoteConfiguration = YES.

/// Proactively update remote configuration. The call frequency is affected by FTMobileConfig.remoteConfigMiniUpdateInterval.
+ (void)updateRemoteConfig;

/// Proactively update remote configuration. This method ignores the FTMobileConfig.remoteConfigMiniUpdateInterval setting.
/// - Parameters:
///   - miniUpdateInterval: Remote configuration update interval in seconds [0,)
///   - completion: Callback after the request completes, supports custom adjustment of the Model in the callback.
+ (void)updateRemoteConfigWithMiniUpdateInterval:(NSInteger)miniUpdateInterval
                                     completion:(nullable FTRemoteConfigFetchCompletionBlock)completion;

/// Proactively update remote configuration. The call frequency is affected by FTMobileConfig.remoteConfigMiniUpdateInterval.
 open class func updateRemoteConfig()

/// Proactively update remote configuration. This method ignores the FTMobileConfig.remoteConfigMiniUpdateInterval setting.
/// - Parameters:
///   - miniUpdateInterval: Remote configuration update interval in seconds [0,)
///   - completion: Callback after the request completes, supports custom adjustment of the Model in the callback.
 open class func updateRemoteConfig(withMiniUpdateInterval miniUpdateInterval: Int, completion: FTRemoteConfigFetchCompletionBlock? = nil)

Remote Configuration Fetch Callback and Custom Configuration

SDK >= 1.5.19 supports custom modification of the final configuration via the return value of FTRemoteConfigFetchCompletionBlock.

/**
 *  @brief  Remote configuration fetch completion callback Block type.
 *  @details This Block is used to receive the fetch/parse result of remote configuration and returns the configuration model ultimately used by the SDK. The SDK adjusts corresponding features based on the returned result.
 *
 *  @param  success   Boolean value indicating whether the fetch/parse was successful.
 *                    - YES: Operation successful, does not guarantee configuration data is non-nil.
 *                    - NO: Operation failed (feature not enabled/minimum interval not reached/network exception/data parsing failed, etc.).
 *  @param  error     Error information object. Returns valid error details only when success=NO; always nil when success=YES.
 *  @param  model     Structured configuration model. Returns a valid instance only when success=YES and configuration data is non-nil; returns nil in all other scenarios.
 *  @param  content   Raw configuration dictionary, the original data before structured parsing. Returns a valid dictionary only when success=YES and configuration data is non-nil; returns nil in all other scenarios.
 *
 *  @return FTRemoteConfigModel optional instance, the configuration model ultimately used by the SDK.
 *          - Success scenario (success=YES):
 *            1. Returns a non-nil instance: The SDK uses this modified model to adjust features.
 *            2. Returns nil: The SDK uses the originally parsed model (if it exists).
 *          - Failure scenario (success=NO):
 *            Must return nil, the SDK ignores the callback result.
 */
typedef FTRemoteConfigModel*_Nullable(^FTRemoteConfigFetchCompletionBlock)(BOOL success,
                                              NSError * _Nullable error,
                                              FTRemoteConfigModel * _Nullable model,
                                              NSDictionary<NSString *, id> * _Nullable content);

Callback Priority: +updateRemoteConfigWithMiniUpdateInterval:completion: (exclusive callback for proactive method) > FTMobileConfig.remoteConfigFetchCompletionBlock (global unified callback)

Usage Example

Currently, only the callback example for the proactive synchronization method is shown. The usage logic for the global remoteConfigFetchCompletionBlock is consistent with this example.

  [FTMobileAgent updateRemoteConfigWithMiniUpdateInterval:0 completion:^FTRemoteConfigModel * _Nullable(BOOL success, NSError * _Nullablererror, FTRemoteConfigModel * _Nullable model, NSDictionary<NSString *,id> * _Nullable content) {
            if (error) {
                NSLog(@"remoteConfigFetch error:%@",error.description);
            }
            // Process configuration data when the operation is successful
            if (success) {
                // Get the custom environment variable value from remote configuration
                // Example: Need to adjust for a specified user, the specified user is uid = @"user_1"
                NSString *userId = content[@"custom_userid"];
                if ([userId isEqualToString:@"user_1"]) {
                    model.rumSampleRate = @(1);
                    model.logSampleRate = @(1);
                    model.traceSampleRate = @(1);
                }
            }
           // Return the modified model (returning model is equivalent to returning nil when unmodified, both use the original model)
            return model;
        }];

FTMobileAgent.updateRemoteConfig(withMiniUpdateInterval: 0) { (success: Bool, error: Error?, model: FTRemoteConfigModel?, content: [String: Any]?) -> FTRemoteConfigModel? in
                if let error = errofr {
                    print("remoteConfigFetch error:\(error.localizedDescription)")
                }

                // Process configuration data when the operation is successful
                if success {
                    // Get the custom environment variable value from remote configuration
                    // Example: Need to adjust for a specified user, the specified user is uid = @"user_1"
                    let userId = content?["custom_userid"] as? String
                    if userId == "user_1" {
                        model?.rumSampleRate = 1
                        model?.logSampleRate = 1
                        model?.traceSampleRate = 1
                    }
                }

                // Return the modified model (returning model is equivalent to returning nil when unmodified, both use the original model)
                return model
            }

Dynamically Update Endpoint

Use FTMobileAgent to dynamically switch the data reporting endpoint during SDK runtime. After successful setting, subsequent data will continue to be uploaded to the new address.

SDK >= 1.5.21 supports setDatakitURL and setDatawayURL:clientToken:. Use either setDatakitURL or setDatawayURL:clientToken:. When using setDatawayURL:clientToken:, the new clientToken must be passed simultaneously.

Use Case Description

FTMobileConfig supports initialization without passing datakitUrl or datawayUrl. In this scenario, the SDK will first perform data collection but will not upload.

When [FTMobileAgent setDatakitURL:] or [FTMobileAgent setDatawayURL:clientToken:] is subsequently called to dynamically set the reporting endpoint, the SDK will start consuming the local cache and perform data reporting.

It is important to note that data collected during the period when no upload address is set is still subject to local cache limits. The cache limit is primarily affected by the following configurations:

  • FTLoggerConfig.logCacheLimitCount
  • FTRumConfig.rumCacheLimitCount
  • The database cache limit corresponding to FTMobileConfig.enableLimitWithDbSize

If the cache reaches its limit, data beyond the limit may be discarded. Therefore, it is recommended to promptly supplement the upload address in this mode or reasonably set cache limits based on business scenarios.

[FTMobileAgent setDatakitURL:@"http://10.0.0.1:9529"];
[FTMobileAgent setDatawayURL:@"https://openway.guance.com" clientToken:@"your-client-token"];

FTMobileAgent.setDatakitURL("http://10.0.0.1:9529")
FTMobileAgent.setDatawayURL("https://openway.guance.com", clientToken: "your-client-token")
Method Name Type Required Meaning
setDatakitURL NSString Yes Dynamically set the Datakit reporting endpoint. After successful setting, the SDK will continue uploading data to the new Datakit address.
setDatawayURL:clientToken: NSString, NSString Yes Dynamically set the Dataway reporting endpoint and clientToken. After successful setting, the SDK will continue uploading data to the new Dataway address.