Advanced guide

Last updated 09/03/2026

1. Initialization parameters

HarmonyOS RemoteConfig is initialized through TDRemoteConfigSettings (independent of the initialization configuration of the Analytics SDK). The fields are described below:

1.1 TDRemoteConfigSettings

Property name / method	Type	Description
appId	string	The app id of the project created in the AE backend (required)
serverUrl	string	The server url of the project created in the AE backend (required)
templateCode	string	Template code; if it isn't passed, the SDK uses the default template internally
mode	TDRemoteConfigMode	Enum of the SDK running mode; defaults to NORMAL
customFetchParams	Record<string, Object>	Custom fetch parameters carried during initialization (equivalent to Fetch parameters)
customBucketId	Record<string, string>	Custom bucket ID (used to force overrides in A/B experiments)
setFetchTask(callbacks)	—	Registers fetch callbacks for the init phase (onLocalCacheReady / onSuccess / onFailure)

The log switch isn't part of Settings. Use the following instead:

TDRemoteConfig.enableLog(true);

Example:

import {
  TDRemoteConfig,
  TDRemoteConfigSettings,
  TDRemoteConfigMode
} from '@thinkingdata/remoteconfig';

const settings = new TDRemoteConfigSettings();
settings.appId = 'YOUR_APP_ID';
settings.serverUrl = 'YOUR_SERVER_URL';
settings.mode = TDRemoteConfigMode.NORMAL;
settings.customFetchParams = { platform: 'harmonyos' };
settings.setFetchTask({
  onLocalCacheReady: () => {},
  onSuccess: () => {},
  onFailure: (code, error) => {}
});
TDRemoteConfig.init(context, settings);

1.2 TDRemoteConfigMode

Enum values	Description
NORMAL	Normal mode. Fetches configurations according to the cache and expiration policies, and stores them locally.
DEBUG	Debug mode. Makes sending tests easier / forces more frequent config fetches. The device must be added to the test device list in the AE console; you can watch the test progress nodes in the Engage backend.

Note: HarmonyOS RemoteConfig provides only NORMAL / DEBUG and doesn't include DEBUG_ONLY from the Analytics side. Configure the Debug mode for data collection separately in the Analytics SDK.

2. Customize fetch timing

2.1 Automatic fetching

The SDK automatically fetches remote configuration data in the following scenarios:

• App cold start (the first fetch is triggered after TDRemoteConfig.init)
• The app switches between foreground and background, and the local configuration has expired (the expiration time is delivered by the server in expirationPeriod and defaults to 12 hours)
• The ThinkingData Analytics account system changes, for example, login, logout, or setDistinctId
• The network becomes available again after being unavailable, and the SDK makes a catch-up fetch
• Timer check: in normal mode, the SDK checks for expiration about every 30s; in Debug mode, it fetches about every 5s

2.2 Manual fetching

Call the SDK method manually to fetch the remote configuration at any time:

TDRemoteConfig.fetch();

Chained callback example:

TDRemoteConfig.fetch()
  .onSuccess(() => {
    // Configuration updated
  })
  .onFailure((code: number, error: string) => {
    // Fetch failed
  });

This API has internal frequency control, so avoid frequent fetches. To force more aggressive fetching, initialize the SDK with TDRemoteConfigMode.DEBUG.

3. Customize Fetch parameters

Fetch parameters are parameters that the client SDK can use when it requests values from the AE server. You can customize Fetch parameters and add them as Environment Parameters of config channels. You can then use the Fetch parameters to customize the target audience environment when you configure strategies.

3.1 Add

TDRemoteConfig.setCustomFetchParams({
  user_level: 'vip',
  region: 'cn'
});

You can also set them through Settings during initialization:

settings.customFetchParams = {
  user_level: 'vip',
  region: 'cn'
};

3.2 Delete

Delete by the specified key:

TDRemoteConfig.removeCustomFetchParam('user_level');

3.3 Custom bucket ID (optional)

Used to force-override group assignment in A/B experiments:

TDRemoteConfig.setCustomBucketId({
  experiment_key: 'bucket_b'
});