SDK Initialization¶

This article covers React Native SDK initialization and runtime capabilities.

Importing the SDK¶

Now, in your code, you can use:

import {
  FTMobileReactNative,
  FTReactNativeLog,
  FTReactNativeTrace,
  FTReactNativeRUM,
  FTMobileConfig,
  FTLogConfig,
  FTTraceConfig,
  FTRUMConfig,
  ErrorMonitorType,
  DeviceMetricsMonitorType,
  DetectFrequency,
  TraceType,
  FTLogStatus,
  EnvType,
} from '@cloudcare/react-native-mobile';

Basic Configuration¶

// Local environment deployment (Datakit deployment)
let config: FTMobileConfig = {
  datakitUrl: datakitUrl,
};

// Using the public DataWay
let config: FTMobileConfig = {
  datawayUrl: datawayUrl,
  clientToken: clientToken,
};

await FTMobileReactNative.sdkConfig(config);

Blacklist Filtering¶

React Native SDK 0.4.2 and later supports filtering RUM and Log data before the data is written to the local cache. This capability is enabled by default. You can disable SDK-side filtering with enableDataFilter: false.

Blacklist rules can be centrally configured in the Blacklist of the Guance workspace, and the SDK pulls them automatically from DataKit or DataWay. They can also be configured in-app through FTMobileConfig.dataFilters. Both approaches share the same blacklist filtering capability and can be used at the same time. When any rule is matched, that data record is discarded.

Blacklist filtering runs after lineDataModifier and before the data is written to the local cache. If both lineDataModifier and blacklist filtering are configured, the filtering rules are evaluated against the modified data.

enableDataFilter only controls rule pulling and filtering on the SDK side. When set to false, the SDK no longer applies dataFilters or pulls workspace rules. When reporting through DataKit, the workspace blacklist may still be enforced on the DataKit side.

Data Filter works on the SDK data write pipeline. Too many rules or overly complex regular expressions may affect data write performance. It is recommended to configure only the necessary rules.

let config: FTMobileConfig = {
  datawayUrl: datawayUrl,
  clientToken: clientToken,
  enableDataFilter: true,
  dataFilters: {
    logging: [
      "{ `source` in [ 'df_rum_ios_log' , 'df_rum_android_log' ] and `message` match [ 'timeout' ] }",
    ],
    rum: [
      "{ `resource_status` match [ '5..' ] }",
    ],
  },
};

await FTMobileReactNative.sdkConfig(config);

During SDK initialization, the workspace blacklist rules are pulled immediately. Subsequent pull intervals follow the pull_interval returned by the server; when the server does not return a valid value, the SDK uses 10 seconds as a fallback interval. pull_interval supports a number of seconds or a string with a unit, for example 10, 30s, 2m, 1h.

Rule Syntax¶

The Data Filter rule syntax is basically the same as that of blacklist filtering rules. For the full syntax, refer to Blacklist Filtering Rules.

The key of dataFilters indicates the data category. Currently the SDK supports:

Each rule is expressed as { condition }. When any rule is matched, the data in that category is filtered out. Rules can use the data's tag and field fields, as well as the data type identifier fields source and measurement.

For the field value format and operator semantics, refer to Field Value Format and Operators in the blacklist filtering rules.

In SDK rule strings, field values are recommended to use array format. Negative operators support not in and not match, and are also compatible with notin, notmatch, and not_in used in rules delivered by the server.

{ `status` in [ 'debug' ] and `env` not in [ 'prod' ] and `message` not match [ '.*error.*' ] }

User Information Binding and Unbinding¶

Usage¶

/**
 * Binds a user.
 * @param userId User ID.
 * @param userName User name.
 * @param userEmail User email.
 * @param extra Extra user information.
 */
bindRUMUserData(userId: string, userName?: string, userEmail?: string, extra?: object): Promise<void>;

/**
 * Unbinds a user.
 */
unbindRUMUserData(): Promise<void>;

Usage Example¶

import { FTMobileReactNative } from '@cloudcare/react-native-mobile';
FTMobileReactNative.bindRUMUserData('react-native-user', 'user_name');

FTMobileReactNative.unbindRUMUserData();

Runtime Capabilities¶

Shutting Down the SDK¶

Use FTMobileReactNative to shut down the SDK.

/**
 * Shuts down the running objects inside the SDK.
 */
shutDown(): Promise<void>;

FTMobileReactNative.shutDown();

Clearing SDK Cache Data¶

Use FTMobileReactNative to clear cache data that has not been reported.

/**
 * Clears all data that has not yet been uploaded to the server.
 */
clearAllData(): Promise<void>;

FTMobileReactNative.clearAllData();

Syncing Data Manually¶

When FTMobileConfig.autoSync is set to true, no extra action is required; the SDK syncs automatically.

When FTMobileConfig.autoSync is set to false, data sync must be triggered manually.

/**
 * Manually syncs data. Trigger this manually when `FTMobileConfig.autoSync = false` is configured.
 */
flushSyncData(): Promise<void>;

FTMobileReactNative.flushSyncData();

Initialization Order¶

Complete SDK initialization before registering the App in the top-level index.js file, to ensure that the SDK is fully ready before you call any other SDK methods.

After completing the basic configuration, then configure RUM, Log, and Trace.

import App from './App';

async function sdkInit() {
  await FTMobileReactNative.sdkConfig(config);
  await FTReactNativeRUM.setConfig(rumConfig);
  // ...
}

sdkInit();
AppRegistry.registerComponent('main', () => App);

Dynamic Configuration¶

The dynamic configuration capabilities have been moved to Dynamic Configuration.