SDK Initialization¶

This article covers the content related to Android SDK initialization.

Application Configuration¶

The optimal location for SDK initialization is in the onCreate method of 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 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 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 total cache size limit. After enabling, the separate 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 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 blacklist filtering compatible with DataKit, 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 is executed after LineDataModifier and before local cache writing. If both setLineDataModifier and blacklist filtering are configured, the filtering rules will be judged based on the modified data.

Rule expressions need to 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)

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

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

The pull interval for remote blacklists is based on the pull_interval returned by the server; when 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, such as 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; it can be combined 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)

Active Data Sync¶

Use FTSdk to actively sync data.

Only when FTSdk.setAutoSync(false) is set, manual data synchronization is required.

FTSdk.flushSyncData();

FTSdk.flushSyncData()