Dynamic Configuration and Dynamic Address Update¶

Enable Dynamic Configuration¶

Dynamic configuration is disabled by default. When enabled, the SDK reads the local cache during installation; if the RUM configuration is already installed and a valid upload address exists, the SDK uses the RUM application ID to fetch the server configuration. If the upload address is set only at runtime, the SDK continues to fetch the dynamic configuration after the address becomes valid.

import {
  FTSDK,
  FTSDKConfig,
  FTRUMConfig,
  FTRemoteConfigFetchResult,
  RemoteConfigBean
} from '@guancecloud/ft_sdk/Index';

const remoteConfigResult: FTRemoteConfigFetchResult = {
  // Called when the server returns valid and changed configuration.
  onConfigSuccessFetched(configBean: RemoteConfigBean, jsonConfig: string): RemoteConfigBean | null {
    // Can parse custom environment variables from jsonConfig and return the modified configuration.
    return configBean;
  },
  // true if the fetch succeeds or the server configuration is unchanged; false if the request fails or the refresh interval is not met.
  onResult(success: boolean): void {
    // Record the fetch result as needed
  }
};

const sdkConfig = FTSDKConfig.builder()
  .setRemoteConfiguration(true)
  .setRemoteConfigMiniUpdateInterval(43200)
  .setRemoteConfigurationCallBack(remoteConfigResult);

FTSDK.install(sdkConfig, this.context);
FTSDK.installRUMConfig(new FTRUMConfig().setRumAppId('your-rum-app-id'));

The local cache is merged before each configuration installation: the base SDK supports environment, service name, and upload-related configurations; RUM supports sampling rate, automatic collection toggle, and WebView Host whitelist; Log supports sampling rate, level, and toggle; Trace supports sampling rate, automatic tracing, and type. After new configurations are fetched online, only the upload toggle and parameters, Log configuration, Trace sampling rate, and RUM sampling rate and error sampling rate take effect immediately; other configurations take effect on the next initialization.

Actively Synchronize Dynamic Configuration¶

Use FTSDK to actively synchronize the dynamic configuration. When automatic updates do not meet requirements, you can adjust the update timing by actively calling.

/**
 * Actively update the remote configuration, the call frequency is affected by FTSDKConfig.setRemoteConfigMiniUpdateInterval.
 */
FTSDK.updateRemoteConfig();

/**
 * Actively update the remote configuration, using the specified minimum update interval.
 * Pass 0 to request immediately.
 *
 * @param intervalSeconds Minimum update interval, in seconds; negative values are treated as 0.
 * @param result Fetch result callback, can override the callback set during initialization.
 */
FTSDK.updateRemoteConfig(intervalSeconds, result);

Code Example¶

import {
  FTSDK,
  FTRemoteConfigFetchResult,
  RemoteConfigBean
} from '@guancecloud/ft_sdk/Index';

const result: FTRemoteConfigFetchResult = {
  onResult(success: boolean): void {
    // true when the fetch succeeds or the server configuration is unchanged.
  },
  onConfigSuccessFetched(configBean: RemoteConfigBean, jsonConfig: string): RemoteConfigBean | null {
    // Optional extension: parse custom environment variables from jsonConfig and modify configBean.
    return configBean;
  }
};

// Pass 0 to request immediately and use this callback to override the one set during initialization.
FTSDK.updateRemoteConfig(0, result);

Dynamically Enable and Disable Device Identifiers¶

Use FTSDK to set whether to obtain the system device identifier in the SDK. By default, the SDK uses the persistent privacy UUID as device_uuid; after enabling, the SDK prefers ODID, falls back to UDID if ODID is unavailable, and uses the privacy UUID if both are unavailable.

// Enable system device identifier access
FTSDK.setEnableAccessDeviceID(true);

// Switch back to SDK privacy UUID
FTSDK.setEnableAccessDeviceID(false);

Dynamically Update the Upload Address¶

Use FTSDK to dynamically switch the data upload address during SDK runtime. Call this after FTSDK.install(...) is completed; after successful setting, subsequent data will be uploaded to the new address.

Use setDatakitUrl or setDatawayUrl, but not both. When using setDatawayUrl, you need to pass the new clientToken as well.

Use Case Description¶

FTSDKConfig.builder() supports not passing datakitUrl or datawayUrl during initialization. In this scenario, the SDK performs data collection but does not upload data.

After subsequently calling FTSDK.setDatakitUrl(...) or FTSDK.setDatawayUrl(..., ...) to set a complete and valid HTTP(S) upload address, the SDK starts consuming the local cache and resumes automatic upload; the DataWay mode also requires a valid client token. Relative paths, non-HTTP(S) protocols, or malformed addresses will not resume automatic upload; to request an immediate upload, call FTSDK.flushSyncData().

If dynamic configuration is enabled, after switching to a valid upload address, the SDK immediately refreshes the remote configuration from the new address; the results of ongoing requests to the old address are ignored. If blacklist filtering is enabled, the SDK clears the remote rules from the old address and immediately fetches from the new address; local rules are retained.

The address set at runtime is only stored in memory and needs to be set again after the app restarts. To set the upload address before SDK installation, call setDatakitUrl(...) or setDatawayUrl(...) on the configuration object returned by FTSDKConfig.builder(). See SDK Initialization for details.

During the period when no upload address is set, the collected data is still subject to the local cache limit. Once the cache reaches the limit, excess data may be discarded. Therefore, it is recommended to provide the upload address as soon as possible and set appropriate cache limits based on your business scenario.

import { FTSDK } from '@guancecloud/ft_sdk/Index';

// Use DataKit for upload
FTSDK.setDatakitUrl('http://10.0.0.1:9529');

// Or use DataWay for upload
FTSDK.setDatawayUrl('https://open.dataway.url', 'your-client-token');