SDK Initialization¶

This document describes the initialization and runtime basic APIs of the Mobile SDK for version 0.3.0 and above.

Getting the API Object¶

A regular uni-app imports from the UTS module and loads setup.js once at the application entry:

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

A uni mini-program imports from the common JS layer:

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

The SDK of a uni mini-program is initialized by the host App and does not call sdkConfig(). Other runtime APIs on this page can be called after the host initialization is complete.

Basic Configuration¶

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

Parameter	Type	Required	Description
datakitUrl	string	No	The DataKit reporting URL for a local deployment, e.g., `http://10.0.0.1:9529`. Choose one from `datakitUrl` and `datawayUrl`; it can be omitted initially and set dynamically later via `setDatakitURL`
datawayUrl	string	No	The public DataWay reporting URL. Choose one from `datakitUrl` and `datawayUrl`; it can be omitted initially and set dynamically later via `setDatawayURL`
clientToken	string	Yes when using `datawayUrl`	The authentication token matching the DataWay URL
debug	boolean	No	Whether to print debug logs, default `false`
env	string	No	The environment name, default `prod`; it is recommended to use a single word, e.g., `test`
service	string	No	The business or service name; the default value is determined by the platform SDK
globalContext	object	No	Global tags attached at initialization
offlinePackage	boolean	No	Android only; set to `true` when using offline packaging for a regular uni-app, or when an existing `0.2.x` uni mini-program project still initializes the SDK on the JS side; default `false`. See Differences between Android Cloud Packaging and Offline Packaging
autoSync	boolean	No	Whether to automatically sync data, default `true`; if disabled, use `flushSyncData` to sync manually
syncPageSize	number	No	The number of data items per sync, range `[5,)`, default `10`
syncSleepTime	number	No	The interval between syncs, range `[0,5000]`, in milliseconds
enableDataIntegerCompatible	boolean	No	Whether to enable integer data compatibility, enabled by default
compressIntakeRequests	boolean	No	Whether to compress sync data with deflate, disabled by default
enableLimitWithDbSize	boolean	No	Whether to enable DB size limit; when enabled, `logCacheLimitCount` and `rumCacheLimitCount` become invalid
dbCacheLimit	number	No	DB cache limit, range `[30MB,)`, default `100MB`, in bytes
dbDiscardStrategy	string	No	DB data discard strategy: `discard` (default) or `discardOldest`
dataModifier	object	No	Single-field data masking. See Data Collection Masking
lineDataModifier	object	No	Single-data masking. See Data Collection Masking
remoteConfiguration	boolean	No	Whether to enable remote configuration, default `false`; when enabled, configuration updates are triggered on SDK initialization or app warm start
remoteConfigMiniUpdateInterval	number	No	Minimum update interval for remote configuration, range `[0,)`, in seconds, default 12 hours
enableDataFilter	boolean	No	Whether to enable data filtering compatible with DataKit, default `true`
dataFilters	object	No	Local data filtering rules; keys support `logging` and `rum`, values are arrays of rule strings

Remote Configuration and Data Filtering¶

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 is used to enable remote updates of SDK configuration such as sampling rate; to trigger an update manually, use updateRemoteConfigWithMiniUpdateInterval.
dataFilters are local blacklist rules shipped with the App; data that matches any rule is discarded before being written to the local cache.
Local rules and remote rules take effect simultaneously. Rules are executed after lineDataModifier, so they evaluate the modified data.
Each rule is expressed as { condition }. For field and value formats, refer to Blacklist Filter Rules.

User Info Binding and Unbinding¶

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

mobileAgent.unbindRUMUserData();

API - bindRUMUserData¶

Field	Type	Required	Description
userId	string	Yes	User ID
userName	string	No	User name
userEmail	string	No	User email
extra	object	No	Additional user information

API - unbindRUMUserData¶

Unbinds the current user.

Runtime Capabilities¶

Shut Down SDK¶

mobileAgent.shutDown();

After shutting down the SDK, a full re-initialization is required to use it again. In a uni mini-program, the SDK held by the host App should generally not be shut down, unless both parties have agreed on a lifecycle management approach.

Clear SDK Cache Data¶

mobileAgent.clearAllData();

Clears all data that has not yet been uploaded to the server.

Manually Sync Data¶

mobileAgent.flushSyncData();

When autoSync is true, no additional action is needed. When autoSync is false, call this method to trigger data sync.