SDK Initialization¶

This article 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 sync cache and RUM aggregated data to file cache. To ensure smooth upgrades 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 simultaneously 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 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 oldest cached data when cache reaches 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 oldest cached data when cache reaches 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 matches.
• Blacklist filtering executes after LineDataModifier and before local cache write. If both setLineDataModifier and blacklist filtering are configured, 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, also supporting 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)

If you need to disable both local and remote data filtering, you can explicitly set:

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()

Setting Automatic Data Sync¶

ft-sdk version 1.7.3 and above supports dynamically enabling or disabling automatic cache data synchronization after SDK initialization. After disabling, the SDK will still write collected data to local cache but will not automatically trigger synchronization after data collection; can be used with FTSdk.flushSyncData() to manage data synchronization manually.

// Disable automatic sync
FTSdk.setAutoSync(false);

// Enable automatic sync
FTSdk.setAutoSync(true);

// Disable automatic sync
FTSdk.setAutoSync(false)

// Enable automatic sync
FTSdk.setAutoSync(true)

Manual Data Sync¶

Use FTSdk to manually sync data.

Only needed when FTSdk.setAutoSync(false) to manage data synchronization yourself.

FTSdk.flushSyncData();

FTSdk.flushSyncData()