SDK Initialization¶

This document covers Android SDK initialization.

Application Configuration¶

The best place to initialize the SDK is in the onCreate method of the Application. If your application does not already have an Application class, you need to create one and declare it in AndroidManifest.xml. For an example, see 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);
        // Use the public 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)
        // Use the public DataWay
        val config = FTSDKConfig.builder(datawayUrl, clientToken)
        // ...
        // config.setDebug(true)              // debug mode
        FTSdk.install(config)
    }
}

File Cache¶

From ft-sdk 1.7.2 and above, sync cache and RUM aggregation data can be written to a file cache. To ensure smooth upgrades from older versions, the SDK still uses SQLite cache by default. If you want to enable file cache, 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 validate the file cache writes first, you can enable shadow write. When enabled, the SDK still reads data from SQLite while mirroring writes to the file cache; switch to enableFileDataStore after validation.

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

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

Cache Size Limit¶

From ft-sdk 1.7.2 and above, use enableLimitWithCacheSize to configure the SDK total cache size limit. Once enabled, the separate log count limit FTLoggerConfig.setLogCacheLimitCount and RUM count limit FTRUMConfig.setRumCacheLimitCount no longer take effect.

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

FTSdk.install(config);

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

FTSdk.install(config)

Blacklist Filtering¶

From ft-sdk 1.7.2 and above, Logging and RUM data can be filtered before being written to the local cache. This capability is enabled by default and can be disabled with setEnableDataFilter(false).

Blacklist rules can be centrally configured in the blacklist of the Guance workspace and pulled automatically by the SDK from DataKit or Dataway. They can also be configured in-app with setDataFilters. Both approaches correspond to the same blacklist filtering capability and can be used simultaneously. Once any rule is matched, the data is discarded.

setDataFilters supports logging and rum rule types. Each rule is expressed as { condition } and can match data tags, fields, and data type identifier fields such as source, measurement, and class. For the complete syntax, see blacklist filtering rules.

Blacklist filtering runs after LineDataModifier and before writing to the local cache. If both setLineDataModifier and blacklist filtering are configured, the filter rules are evaluated against the modified data.

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 local and remote data filtering, set it explicitly:

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

The pull interval for workspace blacklist rules follows the pull_interval returned by the server. When the server returns no valid value, the SDK uses 10 seconds as the fallback interval. pull_interval supports a number of seconds or a string with a unit, such as 10, 30s, 2m, or 1h.

Runtime Capabilities¶

Shutting Down the SDK¶

If you need to change the SDK configuration dynamically, shut down the SDK first to avoid generating incorrect data.

FTSdk.shutDown();

FTSdk.shutDown()

Clearing SDK Cache Data¶

Use FTSdk to clear unsynced cached data.

FTSdk.clearAllData();

FTSdk.clearAllData()

Configuring Automatic Data Sync¶

From ft-sdk 1.7.3 and above, automatic sync of cached data can be dynamically enabled or disabled after SDK initialization. When disabled, the SDK still writes collected data to the local cache but does not trigger sync automatically after collection; you can manage data sync with FTSdk.flushSyncData().

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

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

// Disable automatic sync
FTSdk.setAutoSync(false)

// Enable automatic sync
FTSdk.setAutoSync(true)

Manually Syncing Data¶

Use FTSdk to manually sync data.

When FTSdk.setAutoSync(false) is set, you need to sync data manually.

FTSdk.flushSyncData();

FTSdk.flushSyncData()