SDK 初始化¶

本文介绍 0.3.0 及以上版本的 Mobile SDK 初始化与运行时基础 API。

获取 API 对象¶

普通 uni-app 从 UTS 模块导入，并在应用入口提前加载一次 setup.js：

import '@/uni_modules/GC-UniPlugin/setup.js';
import { mobileAgent } from '@/uni_modules/GC-UniPlugin';

uni 小程序从公共 JS 层导入：

import { mobileAgent } from '@/uni_modules/GC-JSPlugin';

uni 小程序的 SDK 由宿主 App 初始化，不调用 sdkConfig()。本页其他运行时 API 可在宿主初始化完成后调用。

基础配置¶

mobileAgent.sdkConfig({
    datakitUrl: 'http://10.0.0.1:9529',
    debug: true,
    env: 'common',
    globalContext: {
        custom_key: 'custom value'
    }
});

参数名称	参数类型	必须	参数说明
datakitUrl	string	否	本地环境部署的 Datakit 上报地址，例如 `http://10.0.0.1:9529`。与 `datawayUrl` 二选一；初始化时可暂不设置，之后通过 `setDatakitURL` 动态设置
datawayUrl	string	否	公网 DataWay 上报地址。与 `datakitUrl` 二选一；初始化时可暂不设置，之后通过 `setDatawayURL` 动态设置
clientToken	string	使用 `datawayUrl` 时是	与 DataWay 地址匹配的认证 Token
debug	boolean	否	是否打印 Debug 日志，默认 `false`
env	string	否	环境名称，默认 `prod`，建议使用单个单词，例如 `test`
service	string	否	所属业务或服务名称，默认值由平台 SDK 决定
globalContext	object	否	初始化时附加的全局标签
offlinePackage	boolean	否	仅 Android；普通 uni-app 离线打包或现有 `0.2.x` uni 小程序项目仍在 JS 侧初始化 SDK 时设置为 `true`，默认 `false`，详见Android 云打包与离线打包区别
autoSync	boolean	否	是否自动同步数据，默认 `true`；关闭后使用 `flushSyncData` 主动同步
syncPageSize	number	否	单次同步的数据条目数，范围 `[5,)`，默认 `10`
syncSleepTime	number	否	同步间歇时间，范围 `[0,5000]`，单位毫秒
enableDataIntegerCompatible	boolean	否	是否开启数据整数兼容处理，默认开启
compressIntakeRequests	boolean	否	是否对同步数据进行 deflate 压缩，默认关闭
enableLimitWithDbSize	boolean	否	是否启用 DB 容量限制；开启后 `logCacheLimitCount` 与 `rumCacheLimitCount` 失效
dbCacheLimit	number	否	DB 缓存限制，范围 `[30MB,)`，默认 `100MB`，单位 byte
dbDiscardStrategy	string	否	DB 数据丢弃策略：`discard`（默认）或 `discardOldest`
dataModifier	object	否	单字段脱敏修改，详见数据采集脱敏
lineDataModifier	object	否	单条数据脱敏修改，详见数据采集脱敏
remoteConfiguration	boolean	否	是否开启远程配置，默认 `false`；开启后 SDK 初始化或应用热启动会触发配置更新
remoteConfigMiniUpdateInterval	number	否	远程配置最小更新间隔，范围 `[0,)`，单位秒，默认 12 小时
enableDataFilter	boolean	否	是否开启与 DataKit 兼容的数据过滤，默认 `true`
dataFilters	object	否	本地数据过滤规则；key 支持 `logging`、`rum`，value 为规则字符串数组

远程配置与数据过滤¶

mobileAgent.sdkConfig({
    datakitUrl: 'http://10.0.0.1:9529',
    remoteConfiguration: true,
    remoteConfigMiniUpdateInterval: 600,
    enableDataFilter: true,
    dataFilters: {
        logging: [
            "{ message match [ 'password' ] }"
        ],
        rum: [
            "{ resource_status match [ '5..' ] }"
        ]
    }
});

remoteConfiguration 用于开启采样率等 SDK 配置的远程更新；如需主动触发更新，可使用 updateRemoteConfigWithMiniUpdateInterval。
dataFilters 是随 App 发布的本地黑名单规则；命中任意规则的数据会在写入本地缓存前被丢弃。
本地规则和远程规则同时生效。规则会在 lineDataModifier 之后执行，因此会基于修改后的数据进行判断。
每条规则使用 { 条件 } 表示，字段和值格式请参考黑名单过滤规则。

用户信息绑定与解绑¶

mobileAgent.bindRUMUserData({
    userId: 'Test userId',
    userName: 'Test name',
    userEmail: 'test@example.com',
    extra: {
        age: '20'
    }
});

mobileAgent.unbindRUMUserData();

API - bindRUMUserData¶

字段	类型	必须	说明
userId	string	是	用户 ID
userName	string	否	用户名称
userEmail	string	否	用户邮箱
extra	object	否	用户额外信息

API - unbindRUMUserData¶

解绑当前用户。

运行时能力¶

关闭 SDK¶

mobileAgent.shutDown();

关闭 SDK 后，如需重新使用，必须重新执行完整初始化。uni 小程序通常不应关闭宿主 App 持有的 SDK，除非双方已约定生命周期管理方式。

清理 SDK 缓存数据¶

mobileAgent.clearAllData();

清除所有尚未上传至服务器的数据。

主动同步数据¶

mobileAgent.flushSyncData();

当 autoSync 为 true 时无需额外操作；当 autoSync 为 false 时，调用该方法触发数据同步。