SDK 初始化¶
本文用于承载 Flutter SDK 初始化与运行时能力相关内容。
基础配置¶
void main() async {
WidgetsFlutterBinding.ensureInitialized();
// 本地环境部署、Datakit 部署
await FTMobileFlutter.sdkConfig(
datakitUrl: datakitUrl,
);
// 使用公网 DataWay
await FTMobileFlutter.sdkConfig(
datawayUrl: datawayUrl,
cliToken: cliToken,
);
}
| 字段 | 类型 | 必须 | 说明 |
|---|---|---|---|
| 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 两者二选一 |
| cliToken | String | 是 | 认证 token,需要与 datawayUrl 同时配置 |
| debug | bool | 否 | 设置是否允许打印日志,默认 false |
| env | String | 否 | 环境配置,默认 prod,任意字符,建议使用单个单词,例如 test |
| envType | enum EnvType | 否 | 环境配置,默认 EnvType.prod。注意:env 与 envType 只需配置一个 |
| autoSync | bool | 否 | 是否在采集数据后自动同步到服务器,默认 true。当为 false 时使用 FTMobileFlutter.flushSyncData() 自行管理数据同步 |
| syncPageSize | enum | 否 | 设置同步请求条目数,SyncPageSize.mini 5 条,SyncPageSize.medium 10 条,SyncPageSize.large 50 条,默认 SyncPageSize.medium |
| customSyncPageSize | number | 否 | 设置同步请求条目数,范围 [5, )。请求条目数越大,代表数据同步占用更大的计算资源 |
| syncSleepTime | number | 否 | 设置同步间歇时间,范围 [0,5000],默认不设置 |
| globalContext | object | 否 | 添加自定义标签。添加规则请查阅 冲突字段说明 |
| serviceName | String | 否 | 服务名 |
| customHttpOverrides | HttpOverrides | 否 | 自定义 HTTP Overrides。开启 HTTP 自动采集时,如果项目已自定义 HttpOverrides.global,可通过该参数传入自定义实现,SDK 会在采集链路中复用该实现 |
| enableLimitWithDbSize | boolean | 否 | 开启使用 DB 限制数据大小,默认 100MB,单位 Byte,默认不开启。开启后 logCacheLimitCount 及 rumCacheLimitCount 将失效。SDK 0.5.3-pre.2 以上支持 |
| dbCacheLimit | number | 否 | DB 缓存限制大小,范围 [30MB, ),默认 100MB,单位 byte,SDK 0.5.3-pre.2 以上支持 |
| dbCacheDiscard | string | 否 | 设置数据库中数据丢弃规则。FTDBCacheDiscard.discard 丢弃新数据(默认),FTDBCacheDiscard.discardOldest 丢弃旧数据。SDK 0.5.3-pre.2 以上支持 |
| enableLimitWithCacheSize | boolean | 否 | 开启使用缓存大小限制数据大小。Android 使用缓存总大小限制;iOS 映射为 DB 缓存大小限制。开启后优先使用 cacheLimit,未设置时兼容使用 dbCacheLimit |
| cacheLimit | number | 否 | 缓存限制大小,单位 byte。Android 对应缓存总大小;iOS 对应 DB 缓存限制 |
| cacheDiscard | enum FTCacheDiscard | 否 | 设置缓存数据丢弃规则。Android 使用缓存丢弃策略;iOS 映射为 DB 数据丢弃规则。FTCacheDiscard.discard 丢弃新数据(默认),FTCacheDiscard.discardOldest 丢弃旧数据 |
| enableFileDataStore | boolean | 否 | Android:是否启用 FileStore 文件缓存 |
| needTransformOldCache | boolean | 否 | Android:启用 FileStore 时是否迁移旧 SQLite 缓存数据 |
| fileDataStoreShadow | boolean | 否 | Android:是否在使用 SQLite 读取路径时同步写入 FileStore |
| compressIntakeRequests | boolean | 否 | 对上传同步数据进行 deflate 压缩,SDK 0.5.3-pre.2 以上支持,默认关闭 |
| enableDataIntegerCompatible | boolean | 否 | 需要与 Web 数据共存情况下建议开启,用于处理 Web 数据类型存储兼容问题。0.5.4-pre.1 以上默认开启 |
| dataModifier | Map |
否 | 对单个字段进行更改,使用示例请看 数据采集脱敏 |
| lineDataModifier | Map |
否 | 对单条数据进行更改,使用示例请看 数据采集脱敏 |
| enableDataFilter | bool | 否 | 是否开启 SDK 侧黑名单过滤,默认 true。支持过滤 Log 和 RUM 数据,SDK 0.5.7 以上版本支持,使用示例请看黑名单过滤 |
| dataFilters | Map |
否 | 配置应用内黑名单规则,支持 logging 和 rum 两类数据。SDK 0.5.7 以上版本支持,规则语法请看规则语法 |
| enableRemoteConfiguration | boolean | 否 | 是否开启远程配置。开启后 SDK 会按配置间隔拉取远程配置并应用到当前运行时 |
| remoteConfigMiniUpdateInterval | number | 否 | 远程配置最短更新间隔,需与 enableRemoteConfiguration 配合使用 |
| remoteConfigOverrideRules | List | 否 | 远程配置本地覆盖规则,用于调试或指定场景下覆盖远程配置结果 |
| iOSGroupIdentifiers | List |
否 | iOS App Group 标识列表,用于 Extension 与主 App 共享缓存数据 |
黑名单过滤¶
Flutter SDK 0.5.7 以上版本支持在数据写入本地缓存前过滤 RUM 与 Log 数据。该能力默认开启,可以通过 enableDataFilter: false 关闭 SDK 侧过滤。
黑名单规则可以在观测云工作空间的黑名单中统一配置,由 SDK 从 DataKit 或 DataWay 自动拉取;也可以通过 FTMobileFlutter.sdkConfig(dataFilters: ...) 在应用内配置。两种方式对应同一套黑名单过滤能力,可以同时使用,任一规则命中后该条数据都会被丢弃。
黑名单过滤在 lineDataModifier 之后、本地缓存写入之前执行。如果同时配置了 lineDataModifier 和黑名单过滤,过滤规则会基于修改后的数据进行判断。
enableDataFilter仅控制 SDK 侧的规则拉取与过滤。设置为false后,SDK 不再应用dataFilters或拉取工作空间规则;使用 DataKit 上报时,工作空间黑名单仍可能在 DataKit 端执行。Data Filter 作用于 SDK 数据写入链路。规则过多或正则表达式过于复杂时,可能影响数据写入性能,建议仅配置必要规则。
await FTMobileFlutter.sdkConfig(
datawayUrl: datawayUrl,
cliToken: cliToken,
enableDataFilter: true,
dataFilters: {
'logging': [
"{ source in [ 'df_rum_ios_log', 'df_rum_android_log' ] and message match [ 'timeout' ] }",
],
'rum': [
"{ resource_status match [ '5..' ] }",
],
},
);
SDK 初始化时会立即拉取工作空间黑名单规则,后续拉取间隔以服务端返回的 pull_interval 为准;服务端未返回有效值时,SDK 使用 10 秒作为兜底间隔。pull_interval 支持秒数或带单位的字符串,例如 10、30s、2m、1h。
规则语法¶
Data Filter 规则语法与黑名单过滤规则基本一致,完整语法说明可参考黑名单过滤规则。
dataFilters 的 key 表示数据分类,目前 SDK 支持:
| 分类 | 说明 |
|---|---|
logging |
Log 数据 |
rum |
RUM 数据 |
每条规则使用 { 条件 } 表示,命中任意一条规则即过滤该分类下的数据。规则中可以使用数据的 tag、field 字段以及 source、measurement 数据类型标识字段。
字段值格式和操作符语义可参考黑名单过滤规则中的字段值格式说明和操作符说明。
SDK 规则字符串中的字段值建议使用数组格式。反向操作符支持 not in、not match,同时兼容服务端下发规则使用的 notin、notmatch 以及 not_in。
用户信息绑定与解绑¶
使用方法¶
/// 绑定用户
///
/// [userid] 用户 id
/// [userName] 用户名
/// [userEmail] 用户邮箱
/// [userExt] 扩展数据
static Future<void> bindRUMUserData(String userId,
{String? userName, String? userEmail, Map<String, String>? ext})
/// 解绑用户
static Future<void> unbindRUMUserData()
代码示例¶
ext 添加规则请查阅 冲突字段说明。
运行时能力¶
主动同步数据¶
autoSync: false时,才需要自行进行数据同步。