SDK Initialization¶

This document describes Android SDK initialization.

Application Configuration¶

The best place to initialize the SDK is in the onCreate method of Application. If your app does not have an Application class yet, 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() {
        // Deploy with local environment, Datakit
        FTSDKConfig config = FTSDKConfig.builder(datakitUrl);
        // Use public Dataway
        FTSDKConfig config = FTSDKConfig.builder(datawayUrl, clientToken);
        // ...
        // config.setDebug(true);              // debug mode
        FTSdk.install(config);
    }
}

class DemoApplication : Application() {
    override fun onCreate() {
        // Deploy with local environment, Datakit
        val config = FTSDKConfig.builder(datakitUrl)
        // Use public Dataway
        val config = FTSDKConfig.builder(datawayUrl, clientToken)
        // ...
        // config.setDebug(true)              // debug mode
        FTSdk.install(config)
    }
}

File Cache¶

Since ft-sdk 1.7.2, you can write sync cache and RUM aggregated data to file-based cache. To ensure a smooth upgrade for older versions, the SDK still uses SQLite cache by default. To enable file cache, explicitly call enableFileDataStore() on FTSDKConfig.

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

FTSdk.install(config);

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

FTSdk.install(config)

If you want to validate file cache writes first, enable shadow writes. When enabled, the SDK still reads from SQLite while mirroring writes to the file cache. After validation, switch to enableFileDataStore().

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

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

Cache Size Limit¶

Since ft-sdk 1.7.2, it is recommended to use enableLimitWithCacheSize to configure the total cache size limit. After enabling, the separate log count limit (FTLoggerConfig.setLogCacheLimitCount) and RUM count limit (FTRUMConfig.setRumCacheLimitCount) become ineffective.

FTSDKConfig config = FTSDKConfig.builder(datawayUrl, clientToken)
        // Enable total cache size limit, example 100MB
        .enableLimitWithCacheSize(100 * 1024 * 1024L)
        // Discard 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 100MB
    .enableLimitWithCacheSize(100 * 1024 * 1024L)
    // Discard oldest cached data when cache reaches the limit
    .setCacheDiscard(CacheDiscard.DISCARD_OLDEST)

FTSdk.install(config)

Blacklist Filtering¶

Since ft-sdk 1.7.2, blacklist filtering compatible with DataKit is supported to filter Logging and RUM data before writing to the local cache. This feature is enabled by default; you can disable it with setEnableDataFilter(false).

Blacklist rules are divided into local rules and remote rules:

• Local rules are configured via setDataFilters and support the logging and rum categories.
• Remote rules are pulled by the SDK from DataKit or Dataway via /v1/datakit/pull?filters=true.
• Local and remote rules apply simultaneously. If any rule matches, the data item is discarded.
• Blacklist filtering runs after LineDataModifier and before writing to the local cache. If both setLineDataModifier and blacklist filtering are configured, the filtering rules are evaluated against the modified data.

Rule expressions must be wrapped in {}. Supported operators: in, not in, match, not match. Multiple conditions can be combined with and / or. Field sources include data tags and fields, and also support data type identifier fields such as source, measurement, and 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, explicitly set:

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

The polling interval for remote blacklist follows 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, for example 10, 30s, 2m, 1h.

Runtime Capabilities¶

Shut Down SDK¶

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

FTSdk.shutDown();

FTSdk.shutDown()

Clear SDK Cache Data¶

Use FTSdk to clear cached data that has not been reported.

FTSdk.clearAllData();

FTSdk.clearAllData()

Set Auto-Sync Data¶

Since ft-sdk 1.7.3, you can dynamically enable or disable automatic sync of cached data after SDK initialization. When disabled, the SDK will still write collected data to the local cache but will not automatically trigger sync after data collection; you can manage data synchronization manually with FTSdk.flushSyncData().

// Disable auto-sync
FTSdk.setAutoSync(false);

// Enable auto-sync
FTSdk.setAutoSync(true);

// Disable auto-sync
FTSdk.setAutoSync(false)

// Enable auto-sync
FTSdk.setAutoSync(true)

Manually Sync Data¶

Use FTSdk to manually sync data.

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

FTSdk.flushSyncData();

FTSdk.flushSyncData()