SDK Initialization¶

This document covers the content related to Android SDK initialization.

Application Configuration¶

The optimal location for SDK initialization is within the onCreate method of the Application. If your application has not yet created an Application, you need to create one and declare it in AndroidManifest.xml. For an example, please refer to here.

<application
       android:name="YourApplication">
</application>

Basic Configuration¶

public class DemoApplication extends Application {

    @Override
    public void onCreate() {
        // Local environment deployment, Datakit deployment
        FTSDKConfig config = FTSDKConfig.builder(datakitUrl);
        // Using public network DataWay
        FTSDKConfig config = FTSDKConfig.builder(datawayUrl, clientToken);
        // ...
        // config.setDebug(true);              // debug mode
        FTSdk.install(config);
    }
}

class DemoApplication : Application() {
    override fun onCreate() {
        // Local environment deployment, Datakit deployment
        val config = FTSDKConfig.builder(datakitUrl)
        // Using public network DataWay
        val config = FTSDKConfig.builder(datawayUrl, clientToken)
        // ...
        // config.setDebug(true)              // debug mode
        FTSdk.install(config)
    }
}

File Cache¶

ft-sdk version 1.7.2 and above supports writing synchronization cache and RUM aggregated data to file cache. To ensure a smooth upgrade from older versions, the SDK still uses SQLite cache by default; if you wish to enable file cache, you can explicitly enable it in FTSDKConfig.

FTSDKConfig config = FTSDKConfig.builder(datawayUrl, clientToken)
        .enableFileDataStore();

FTSdk.install(config);

val config = FTSDKConfig.builder(datawayUrl, clientToken)
    .enableFileDataStore()

FTSdk.install(config)

If you need to verify file cache writing first, you can enable shadow writing. After enabling, the SDK still reads data from SQLite while mirroring writes to the file cache; switch to enableFileDataStore after verification passes.

FTSDKConfig config = FTSDKConfig.builder(datawayUrl, clientToken)
        .setFileDataStoreShadow(true);

val config = FTSDKConfig.builder(datawayUrl, clientToken)
    .setFileDataStoreShadow(true)

Cache Size Limit¶

ft-sdk version 1.7.2 and above recommends using the enableLimitWithCacheSize configuration to set the SDK's total cache size limit. After enabling, the individual log entry limit FTLoggerConfig.setLogCacheLimitCount and the RUM entry limit FTRUMConfig.setRumCacheLimitCount will become invalid.

FTSDKConfig config = FTSDKConfig.builder(datawayUrl, clientToken)
        // Enable total cache size limit, example is 100MB
        .enableLimitWithCacheSize(100 * 1024 * 1024L)
        // Delete the oldest cached data when cache reaches the limit
        .setCacheDiscard(CacheDiscard.DISCARD_OLDEST);

FTSdk.install(config);

val config = FTSDKConfig.builder(datawayUrl, clientToken)
    // Enable total cache size limit, example is 100MB
    .enableLimitWithCacheSize(100 * 1024 * 1024L)
    // Delete the oldest cached data when cache reaches the limit
    .setCacheDiscard(CacheDiscard.DISCARD_OLDEST)

FTSdk.install(config)

Blacklist Filtering¶

ft-sdk version 1.7.2 and above supports DataKit-compatible blacklist filtering, used to filter Logging and RUM data before writing to local cache. This capability is enabled by default and can be turned off via setEnableDataFilter(false).

Blacklist rules are divided into local rules and remote rules:

• Local rules are configured via setDataFilters, supporting logging and rum categories.
• Remote rules are pulled by the SDK from DataKit or Dataway via /v1/datakit/pull?filters=true.
• Local rules and remote rules take effect simultaneously. Data will be discarded if any rule is matched.
• Blacklist filtering is executed after LineDataModifier and before local cache write. If both setLineDataModifier and blacklist filtering are configured, the filtering rules will be judged based on the modified data.

Rule expressions must be written within {}, supporting in, not in, match, not match operators. Multiple conditions can be combined using and / or. Field sources include data tags and fields, and also support data type identifier fields such as source, measurement, class.

HashMap<String, String[]> filters = new HashMap<>();
filters.put("logging", new String[]{
        "{ source in ['custom_log'] and message match ['password'] }"
});
filters.put("rum", new String[]{
        "{ source in ['resource'] and status in [404, 503] }"
});

FTSDKConfig config = FTSDKConfig.builder(datawayUrl, clientToken)
        .setEnableDataFilter(true)
        .setDataFilters(filters);

FTSdk.install(config);

val filters = hashMapOf(
    "logging" to arrayOf(
        "{ source in ['custom_log'] and message match ['password'] }"
    ),
    "rum" to arrayOf(
        "{ source in ['resource'] and status in [404, 503] }"
    )
)

val config = FTSDKConfig.builder(datawayUrl, clientToken)
    .setEnableDataFilter(true)
    .setDataFilters(filters)

FTSdk.install(config)

To disable both local and remote data filtering, set explicitly:

FTSDKConfig.builder(datawayUrl, clientToken)
        .setEnableDataFilter(false);

The pull interval for remote blacklists is based on the pull_interval returned by the server; if the server does not return a valid value, the SDK uses 10 seconds as the fallback interval. pull_interval supports seconds or strings with units, e.g., 10, 30s, 2m, 1h.

Runtime Capabilities¶

Shutting Down the SDK¶

If dynamically changing SDK configuration, it needs to be shut down first to avoid generating erroneous data.

FTSdk.shutDown();

FTSdk.shutDown()

Clearing SDK Cache Data¶

Use FTSdk to clear unreported cache data.

FTSdk.clearAllData();

FTSdk.clearAllData()

Actively Synchronizing Data¶

Use FTSdk to actively synchronize data.

Only required when FTSdk.setAutoSync(false) is set, to perform data synchronization manually.

FTSdk.flushSyncData();

FTSdk.flushSyncData()