SDK 初始化¶

本文用于承载 Android SDK 初始化相关内容。

Application 配置¶

最佳的 SDK 初始化位置是在 Application 的 onCreate 方法中，如果您的应用尚未创建 Application，您需要创建一个，并在 AndroidManifest.xml 中声明，示例请参考这里。

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

基础配置¶

JavaKotlin

public class DemoApplication extends Application {

    @Override
    public void onCreate() {
        // 本地环境部署、Datakit 部署
        FTSDKConfig config = FTSDKConfig.builder(datakitUrl);
        // 使用公网 DataWay
        FTSDKConfig config = FTSDKConfig.builder(datawayUrl, clientToken);
        // ...
        // config.setDebug(true);              // debug 模式
        FTSdk.install(config);
    }
}

class DemoApplication : Application() {
    override fun onCreate() {
        // 本地环境部署、Datakit 部署
        val config = FTSDKConfig.builder(datakitUrl)
        // 使用公网 DataWay
        val config = FTSDKConfig.builder(datawayUrl, clientToken)
        // ...
        // config.setDebug(true)              // debug 模式
        FTSdk.install(config)
    }
}

方法名	类型	必须	含义
datakitUrl	String	是	本地环境部署（Datakit）上报 URL 地址，例子：http://10.0.0.1:9529，端口默认 9529，安装 SDK 设备需能访问该地址。注意：datakitUrl 和 datawayUrl 配置两者二选一
datawayUrl	String	是	公网 Dataway 上报 URL 地址，从 [用户访问监测] 应用中获取，例子：https://open.dataway.url，安装 SDK 设备需能访问该地址。注意：datakitUrl 和 datawayUrl 配置两者二选一
clientToken	String	是	认证 token，需要与 datawayUrl 同时配置
setDebug	Boolean	否	是否开启调试模式，默认为 `false`，开启后方可打印 SDK 运行日志
setEnv	EnvType	否	设置采集环境，默认为 `EnvType.PROD`
setEnv	String	否	设置采集环境，默认为 `prod`。注意：String 或 EnvType 类型只需配置一个
setOnlySupportMainProcess	Boolean	否	是否只支持在主进程运行，默认为 `true`，如果需要在其他进程中执行需要将该字段设置为 `false`
setEnableAccessAndroidID	Boolean	否	开启获取 `Android ID`，默认为 `true`，设置为 `false`，则 `device_uuid` 字段数据将不进行采集，市场隐私审核相关查看这里
addGlobalContext	Dictionary	否	添加 SDK 全局属性，添加规则请查阅此处
setServiceName	String	否	设置服务名，影响 Log 和 RUM 中 service 字段数据，默认为 `df_rum_android`
setAutoSync	Boolean	否	是否在采集数据后自动同步到服务器，默认为 `true`。当为 `false` 时使用 `FTSdk.flushSyncData()` 自行管理数据同步
setSyncPageSize	Int	否	设置同步请求条目数，`SyncPageSize.MINI` 5 条，`SyncPageSize.MEDIUM` 10 条，`SyncPageSize.LARGE` 50 条，默认 `SyncPageSize.MEDIUM`
setCustomSyncPageSize	Enum	否	设置同步请求条目数，范围 [5,)，注意请求条目数越大，代表数据同步占用更大的计算资源，默认为 10。注意：`setSyncPageSize` 和 `setCustomSyncPageSize` 只需要配置一个
setSyncSleepTime	Int	否	设置同步间歇时间，范围 [0,5000]，单位 ms，默认为 0
enableDataIntegerCompatible	Void	否	需要与 web 数据共存情况下，建议开启。此配置用于处理 web 数据类型存储兼容问题。`ft-sdk` 1.6.9 版本默认开启
setNeedTransformOldCache	Boolean	否	是否需要兼容同步 ft-sdk 1.6.0 以下的版本的旧缓存数据，默认为 `false`
enableFileDataStore	Void	否	开启文件缓存，用于同步缓存和 RUM 聚合数据。默认仍使用 SQLite 缓存，`ft-sdk` 1.7.2 以上版本支持
setUseFileDataStore	Boolean	否	设置是否使用文件缓存。传入 `true` 时使用文件缓存，传入 `false` 时使用默认 SQLite 缓存，`ft-sdk` 1.7.2 以上版本支持
setFileDataStoreShadow	Boolean	否	开启文件缓存影子写入。开启后读取仍使用 SQLite，同时将写入镜像到文件缓存，用于迁移前验证，`ft-sdk` 1.7.2 以上版本支持
setCompressIntakeRequests	Boolean	否	对上传同步数据进行 deflate 压缩，默认开启，设置为 `false` 可关闭，`ft-sdk` 1.6.3 以上版本支持这个方法
enableLimitWithCacheSize	Void, Long	否	开启总缓存大小限制，默认 100MB，单位 Byte。传入 `cacheSize` 时取值范围 [30MB,)。开启之后 `FTLoggerConfig.setLogCacheLimitCount` 及 `FTRUMConfig.setRumCacheLimitCount` 将失效。`ft-sdk` 1.7.2 以上版本支持
setCacheDiscard	CacheDiscard	否	设置缓存达到大小上限后的丢弃策略，默认为 `CacheDiscard.DISCARD`。`DISCARD` 为丢弃追加数据，`DISCARD_OLDEST` 为删除最早缓存数据。`ft-sdk` 1.7.2 以上版本支持
enableLimitWithDbSize	Void	否	已废弃，保留旧版本兼容。建议使用 `enableLimitWithCacheSize` 替代
setEnableOkhttpRequestTag	Boolean	否	对 Okhttp Request 自动添加唯一 `ResourceID`，用于相同请求高并发的场景。`ft-sdk` 1.6.10 以上支持，`ft-plugin` 1.3.5 以上支持
setProxy	java.net.Proxy	否	对数据网络同步请求进行 Proxy 代理设置，仅支持 `okhttp3`，`ft-sdk` 1.6.10 以上支持
setProxyAuthenticator	okhttp3.Authenticator	否	对数据同步网络请求进行 Proxy 代理设置，仅支持 `okhttp3`，`ft-sdk` 1.6.10 以上支持
setDns	okhttp3.Dns	否	数据同步网络请求支持自定义 Dns 对域名解析进来自定义处理，仅支持 `okhttp3`，`ft-sdk` 1.6.10 以上支持
setDataModifier	DataModifier	否	对单个字段进行更改。`ft-sdk` 1.6.11 以上支持，使用示例请看这里
setLineDataModifier	LineDataModifier	否	对单条数据进行更改。`ft-sdk` 1.6.11 以上支持，使用示例请看这里
setEnableDataFilter	Boolean	否	是否开启与 DataKit 兼容的黑名单过滤能力，默认为 `true`。支持过滤 Logging 和 RUM 数据，`ft-sdk` 1.7.2 以上版本支持
setDataFilters	`HashMap<String, String[]>`	否	设置本地黑名单过滤规则。支持的分类为 `logging` 和 `rum`；匹配规则的数据会被丢弃。`ft-sdk` 1.7.2 以上版本支持
setRemoteConfiguration	Boolean	否	是否开启数据采集的远程配置功能，默认为 `false`。开启之后，SDK 初始化或应用热启动会触发数据更新。`ft-sdk` 1.6.12 以上支持。`DataKit` 版本要求 >= 1.60 或使用公网 `Dataway`
setRemoteConfigMiniUpdateInterval	Int	否	设置数据更新最短间隔，单位秒，默认 12 小时。`ft-sdk` 1.6.12 以上支持
setRemoteConfigurationCallBack	FTRemoteConfigManager.FetchResult	否	远程配置结果返回，代码示例。`ft-sdk` 1.6.16 以上支持

文件缓存¶

ft-sdk 1.7.2 以上版本支持将同步缓存和 RUM 聚合数据写入文件缓存。为保证旧版本升级平滑，SDK 默认仍使用 SQLite 缓存；如果希望启用文件缓存，可在 FTSDKConfig 中显式开启。

JavaKotlin

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

FTSdk.install(config);

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

FTSdk.install(config)

如果需要先验证文件缓存写入情况，可以开启影子写入。开启后 SDK 仍从 SQLite 读取数据，同时将写入同步镜像到文件缓存；验证通过后再切换为 enableFileDataStore。

JavaKotlin

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

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

缓存大小限制¶

ft-sdk 1.7.2 以上版本建议使用 enableLimitWithCacheSize 配置 SDK 总缓存大小限制。开启后，单独的日志条数上限 FTLoggerConfig.setLogCacheLimitCount 和 RUM 条数上限 FTRUMConfig.setRumCacheLimitCount 将失效。

JavaKotlin

FTSDKConfig config = FTSDKConfig.builder(datawayUrl, clientToken)
        // 开启总缓存大小限制，示例为 100MB
        .enableLimitWithCacheSize(100 * 1024 * 1024L)
        // 缓存达到上限后删除最早缓存数据
        .setCacheDiscard(CacheDiscard.DISCARD_OLDEST);

FTSdk.install(config);

val config = FTSDKConfig.builder(datawayUrl, clientToken)
    // 开启总缓存大小限制，示例为 100MB
    .enableLimitWithCacheSize(100 * 1024 * 1024L)
    // 缓存达到上限后删除最早缓存数据
    .setCacheDiscard(CacheDiscard.DISCARD_OLDEST)

FTSdk.install(config)

黑名单过滤¶

ft-sdk 1.7.2 以上版本支持与 DataKit 兼容的黑名单过滤，用于在数据写入本地缓存前过滤 Logging、RUM 数据。该能力默认开启，可以通过 setEnableDataFilter(false) 关闭。

黑名单规则分为本地规则和远程规则：

本地规则通过 setDataFilters 配置，支持 logging、rum 两类规则。
远程规则由 SDK 通过 /v1/datakit/pull?filters=true 从 DataKit 或 Dataway 拉取。
本地规则与远程规则会同时生效，任一规则命中后该条数据都会被丢弃。
黑名单过滤在 LineDataModifier 之后、本地缓存写入之前执行。如果同时配置了 setLineDataModifier 和黑名单过滤，过滤规则会基于修改后的数据进行判断。

规则表达式需要写在 {} 中，支持 in、not in、match、not match 运算符，多个条件可以使用 and / or 组合。字段来源包括数据标签和字段，也支持 source、measurement、class 等数据类型标识字段。

JavaKotlin

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)

如需关闭本地与远程数据过滤，可显式设置：

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

远程黑名单的拉取间隔以服务端返回的 pull_interval 为准；服务端未返回有效值时，SDK 使用 10 秒作为兜底间隔。pull_interval 支持秒数或带单位的字符串，例如 10、30s、2m、1h。

运行时能力¶

关闭 SDK¶

如果动态改变 SDK 配置，需要先关闭，以避免错误数据的产生。

JavaKotlin

FTSdk.shutDown();

FTSdk.shutDown()

清理 SDK 缓存数据¶

使用 FTSdk 清理未上报的缓存数据。

JavaKotlin

FTSdk.clearAllData();

FTSdk.clearAllData()

主动同步数据¶

使用 FTSdk 主动同步数据。

FTSdk.setAutoSync(false) 时，才需要自行进行数据同步。

JavaKotlin

FTSdk.flushSyncData();

FTSdk.flushSyncData()

SDK 初始化¶

Application 配置¶

基础配置¶

文件缓存¶

缓存大小限制¶

黑名单过滤¶

运行时能力¶

关闭 SDK¶

清理 SDK 缓存数据¶

主动同步数据¶

文档内容是否对您有帮助？ ×