HarmonyOS 应用接入¶

{
  "dependencies": {
    "ft_sdk": "file:../libs/ft_sdk.har"
  }
}

ohpm install

import { FTSDK } from 'ft_sdk/src/main/ets/components/FTSDK';
import { FTSDKConfig, FTRUMConfig, FTLoggerConfig } from 'ft_sdk/src/main/ets/components/Configs';

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { window } from '@kit.ArkUI';
import { FTSDK } from 'ft_sdk/src/main/ets/components/FTSDK';
import { FTSDKConfig, FTRUMConfig, FTLoggerConfig } from 'ft_sdk/src/main/ets/components/Configs';
import { TraceType } from 'ft_sdk/src/main/ets/components/trace/TraceType';

const DOMAIN = 0x0000;

export default class EntryAbility extends UIAbility {
  async onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): Promise<void> {
    await this.initFTSDK();
  }

  private async initFTSDK(): Promise<void> {
    try {
      // 本地环境部署（Datakit）
      // const sdkConfig = FTSDKConfig.builder(datakitUrl);

      // 公网 DataWay
      const sdkConfig = FTSDKConfig.builder(datawayUrl, clientToken)
        .setDebug(true)
        .setServiceName('Your-App-Name');
        // dbCacheLimit 默认值为 100MB，如需自定义可调用 .setDbCacheLimit(sizeInBytes)
        // rumCacheLimitCount 默认值为 100000，如需自定义可调用 .setRumCacheLimitCount(count)
        // logCacheLimitCount 默认值为 5000，如需自定义可调用 .setLogCacheLimitCount(count)

      await FTSDK.install(sdkConfig, this.context);

    const rumConfig = new FTRUMConfig()
        .setSamplingRate(1.0)
        .setRumAppId('your-app-id')
        .setEnableTraceUserAction(true)
        .setEnableTraceUserView(true)
        .setEnableTraceUserResource(true)
        .setEnableTrackAppANR(true);

    await FTSDK.installRUMConfig(rumConfig);

    const logConfig = new FTLoggerConfig()
      .setSamplingRate(1.0)
      .setEnableCustomLog(true)
      .setLogCacheLimitCount(10000)
      .setEnableLinkRumData(true);

    FTSDK.installLogConfig(logConfig);

      hilog.info(DOMAIN, 'FTSDK', 'FT SDK initialized successfully');
    } catch (error) {
      const errorObj: object = error as object;
      hilog.error(DOMAIN, 'FTSDK', `Failed to initialize FT SDK: ${JSON.stringify(errorObj)}`);
    }
  }

  onWindowStageCreate(windowStage: window.WindowStage): void {
    windowStage.loadContent('pages/Index', (err) => {
      if (err.code) {
        hilog.error(DOMAIN, 'FTSDK', `loadContent failed: ${err.code}`);
        return;
      }
      hilog.info(DOMAIN, 'FTSDK', 'Succeeded in loading the content.');
    });
  }
}

const rumConfig = new FTRUMConfig()
  .setRumAppId('your-app-id')
  .setSamplingRate(1.0)
  .setEnableTraceUserAction(true)
  .setEnableTraceUserView(true)
  .setEnableTraceUserResource(true)
  .setEnableTrackAppANR(true)
  .setEnableTraceWebView(true); // 开启 WebView 数据采集

await FTSDK.installRUMConfig(rumConfig);

import { Status } from 'ft_sdk/src/main/ets/components/bean/Status';

const logConfig = new FTLoggerConfig()
  .setSamplingRate(1.0)
  .setEnableCustomLog(true)
  .setLogCacheLimitCount(10000)
  .setLogLevelFiltersString([
    Status.ERROR.name,
    Status.WARNING.name,
    Status.INFO.name,
    Status.DEBUG.name
  ])
  .setEnableLinkRumData(true);

FTSDK.installLogConfig(logConfig);

import { TraceType } from 'ft_sdk/src/main/ets/components/trace/TraceType';

const traceConfig = new FTTraceConfig()
  .setSamplingRate(0.8)
  .setTraceType(TraceType.DDTRACE)
  .setEnableAutoTrace(true)
  .setEnableLinkRUMData(true);

FTSDK.installTraceConfig(traceConfig);

startView(viewName: string, property?: Record<string, object>): void
stopView(property?: Record<string, object>): void
updateLoadTime(loadTime: number): void

import { FTRUMGlobalManager } from 'ft_sdk/src/main/ets/components/rum/FTRUMGlobalManager';

// 场景 1
FTRUMGlobalManager.getInstance().startView('ProductPage');

// 场景 2: 动态参数
// PropertyWrapper class must be defined (ArkTS requirement)
class PropertyWrapper {
  value: string | number | boolean;
  constructor(v: string | number | boolean) {
    this.value = v;
  }
}

class ViewProperty {
  private properties: Map<string, string | number | boolean> = new Map();

  set(key: string, value: string | number | boolean): void {
    this.properties.set(key, value);
  }

  toObject(): Record<string, object> {
    const result: Record<string, object> = {} as Record<string, object>;
    this.properties.forEach((value, key) => {
      result[key] = new PropertyWrapper(value) as object;
    });
    return result;
  }
}

const viewProperty = new ViewProperty();
viewProperty.set('page_category', 'product');
viewProperty.set('page_id', '12345');
FTRUMGlobalManager.getInstance().startView('ProductPage', viewProperty.toObject());

FTRUMGlobalManager.getInstance().updateLoadTime(100000000);

// 场景 1
FTRUMGlobalManager.getInstance().stopView();

// 场景 2: 动态参数
const stopViewProperty = new ViewProperty();
stopViewProperty.set('view_duration', 1000);
FTRUMGlobalManager.getInstance().stopView(stopViewProperty.toObject());

addAction(actionName: string, actionType: string, duration: number, startTime: number, property?: Record<string, object>): void

import { FTRUMGlobalManager } from 'ft_sdk/src/main/ets/components/rum/FTRUMGlobalManager';

// 场景 1: 直接完成
FTRUMGlobalManager.getInstance().addAction('buy_button_click', 'click');

// 场景 2: 动态参数
// PropertyWrapper class must be defined (ArkTS requirement)
class PropertyWrapper {
  value: string | number | boolean;
  constructor(v: string | number | boolean) {
    this.value = v;
  }
}

class ActionProperty {
  private properties: Map<string, string | number | boolean> = new Map();

  set(key: string, value: string | number | boolean): void {
    this.properties.set(key, value);
  }

  toObject(): Record<string, object> {
    const result: Record<string, object> = {} as Record<string, object>;
    this.properties.forEach((value, key) => {
      result[key] = new PropertyWrapper(value) as object;
    });
    return result;
  }
}

const actionProperty = new ActionProperty();
actionProperty.set('product_id', '12345');
actionProperty.set('product_name', 'iPhone 15');
FTRUMGlobalManager.getInstance().addActionWithProperty('buy_button_click', 'click', actionProperty.toObject());

// 场景 3: 开始 Action（包含时长计算机制）
FTRUMGlobalManager.getInstance().startAction('buy_button_click', 'click');
// ... 执行操作 ...
FTRUMGlobalManager.getInstance().stopAction();

Button('Buy Now')
  .id('buy-btn')
  .customProperty('buy-btn', 'Buy Now')
  .onClick(() => {
    // 点击事件会自动被追踪
  })

startResource(resourceId: string, property?: Record<string, object>): void
stopResource(resourceId: string): void
addResource(resourceId: string, resourceParams: ResourceParams, netStatusBean?: NetStatusBean): void

import { FTRUMGlobalManager } from 'ft_sdk/src/main/ets/components/rum/FTRUMGlobalManager';
import { ResourceParams } from 'ft_sdk/src/main/ets/components/rum/bean/ResourceParams';
import { NetStatusBean } from 'ft_sdk/src/main/ets/components/rum/bean/NetStatusBean';

const resourceId = 'https://api.example.com/data';

// 开始资源追踪
FTRUMGlobalManager.getInstance().startResource(resourceId);

const resourceParams = new ResourceParams();
resourceParams.setUrl(resourceId);
resourceParams.setResourceStatus(200);
resourceParams.setResponseContentLength(1024);
resourceParams.resourceType = 'xhr';

const netStatusBean = new NetStatusBean();
netStatusBean.setResourceHostIP('192.168.1.1');
netStatusBean.setDNSTime(10000000);
netStatusBean.setTcpTime(20000000);
netStatusBean.setTTFB(50000000);
netStatusBean.setResponseTime(100000000);

// 结束资源追踪并添加资源数据
FTRUMGlobalManager.getInstance().stopResource(resourceId);
FTRUMGlobalManager.getInstance().addResource(resourceId, resourceParams, netStatusBean);

addError(log: string, message: string, errorType: ErrorType, appState: AppState, property?: Record<string, object>): void

import { FTRUMGlobalManager } from 'ft_sdk/src/main/ets/components/rum';
import { ErrorType, AppState } from 'ft_sdk/src/main/ets/components/rum';

const rumManager = FTRUMGlobalManager.getInstance();

// Option 1: Use ErrorProperty class (recommended for ArkTS)
// Note: ErrorProperty is a helper class, you can create your own or use Map
// PropertyWrapper class must be defined outside the method (ArkTS requirement)
class PropertyWrapper {
  value: string | number | boolean;
  constructor(v: string | number | boolean) {
    this.value = v;
  }
}

class ErrorProperty {
  private properties: Map<string, string | number | boolean> = new Map();

  set(key: string, value: string | number | boolean): void {
    this.properties.set(key, value);
  }

  toObject(): Record<string, object> {
    const result: Record<string, object> = {} as Record<string, object>;
    this.properties.forEach((value, key) => {
      // Create wrapper object using class (ArkTS requirement)
      result[key] = new PropertyWrapper(value) as object;
    });
    return result;
  }
}

const property = new ErrorProperty();
property.set('error_code', 'ERR_001');
property.set('user_id', 'test_user');

rumManager.addError(
  'Error stack trace:\n  at ProductPage.onClick\n  at Button.onClick',
  'Failed to load product data',
  ErrorType.CUSTOM,
  AppState.RUN,
  property.toObject()
);

// Option 2: Pass null if no properties needed
rumManager.addError(
  'Error stack trace:\n  at ProductPage.onClick\n  at Button.onClick',
  'Failed to load product data',
  ErrorType.CUSTOM,
  AppState.RUN
);

addLongTask(taskName: string, duration: number, property?: Record<string, string | number | boolean>): void

import { FTRUMGlobalManager } from 'ft_sdk/src/main/ets/components/rum';

const rumManager = FTRUMGlobalManager.getInstance();

// Option 1: Use Map for properties (recommended for ArkTS)
const property = new Map<string, string | number | boolean>();
property.set('task_type', 'data_processing');
property.set('data_size', 10000);

// Convert Map to Record (ArkTS compatible)
const propertyRecord: Record<string, string | number | boolean> = {} as Record<string, string | number | boolean>;
property.forEach((value, key) => {
  propertyRecord[key] = value;
});

const duration = 500000000;
rumManager.addLongTask('Data Processing', duration, propertyRecord);

// Option 2: Pass empty object or omit property parameter
rumManager.addLongTask('Data Processing', duration);

FTLogger.getInstance().logBackground(content: string, status: Status): void
FTLogger.getInstance().logBackground(content: string, status: Status, property?: Map<string, object>): void
FTLogger.getInstance().logBackground(content: string, status: string, property?: Map<string, object>): void

import { FTLogger } from 'ft_sdk/src/main/ets/components/log/FTLogger';
import { Status } from 'ft_sdk/src/main/ets/components/bean/Status';

// 上传单个日志
FTLogger.getInstance().logBackground('Failed to load product data', Status.ERROR);

// 传递参数
const property = new Map<string, object>();
property.set('error_code', 'ERR_001');
property.set('user_id', 'test_user');
FTLogger.getInstance().logBackground('Network request timeout', Status.WARN, property);

// 使用字符串状态
FTLogger.getInstance().logBackground('User logged in successfully', 'info');

import http from '@ohos.net.http';

const httpRequest = http.createHttp();
const response = await httpRequest.request('https://api.example.com/data', {
  method: http.RequestMethod.GET
});
// Trace Headers 会自动注入到请求中

import { FTTraceManager } from 'ft_sdk/src/main/ets/components/trace/FTTraceManager';
import http from '@ohos.net.http';

const url = 'https://api.example.com/data';
const resourceId = 'unique-resource-id'; // 用于标识资源的唯一 ID

// 获取链路头参数
const traceHeaders: Record<string, string> = FTTraceManager.getInstance().getTraceHeader(resourceId, url);

// 将 Trace Headers 添加到请求中
const httpRequest = http.createHttp();
const response = await httpRequest.request(url, {
  method: http.RequestMethod.GET,
  header: traceHeaders
});

/**
 * 绑定用户信息（仅用户 ID）
 * @param id 用户 ID
 */
static bindRumUserDataById(id: string): void

/**
 * 绑定用户信息（完整用户数据）
 * @param userData 用户数据对象
 */
static async bindRumUserData(userData: UserData): Promise<void>

/**
 * 解绑用户信息
 */
static async unbindRumUserData(): Promise<void>

import { FTSDK } from 'ft_sdk/src/main/ets/components/FTSDK';
import { UserData } from 'ft_sdk/src/main/ets/components/rum/bean/UserData';

// 方式一：仅绑定用户 ID（推荐用于快速绑定）
FTSDK.bindRumUserDataById('user_001');

// 方式二：绑定完整用户信息（推荐用于需要更多用户信息的场景）
  const userData = new UserData();
userData.setId('user_001');
userData.setName('test.user');
userData.setEmail('test@mail.com');
const exts: Record<string, string> = {
  'ft_key': 'ft_value',
  'user_type': 'vip'
};
userData.setExts(exts);
await FTSDK.bindRumUserData(userData);

// 解绑用户信息（用户退出登录时调用）
await FTSDK.unbindRumUserData();

import { FTSDK } from 'ft_sdk/src/main/ets/components/FTSDK';

const globalContext = new Map<string, string>();
globalContext.set('platform', 'harmonyos');
globalContext.set('version', '1.0.0');
FTSDK.appendGlobalContext(globalContext);

const rumGlobalContext = new Map<string, string>();
rumGlobalContext.set('user_type', 'vip');
rumGlobalContext.set('channel', 'official');
FTSDK.appendRUMGlobalContext(rumGlobalContext);

import { FTSDK } from 'ft_sdk/src/main/ets/components/FTSDK';

FTSDK.flushSyncData();

import { FTSDK } from 'ft_sdk/src/main/ets/components/FTSDK';

await FTSDK.clearAllData();

import { FTWebViewHandler } from 'ft_sdk/src/main/ets/components/web/FTWebViewHandler';
import { webview } from '@kit.ArkWeb';

@Component
export struct MyWebViewPage {
  @State webController: webview.WebviewController = new webview.WebviewController();
  private webViewHandler: FTWebViewHandler = new FTWebViewHandler();

  aboutToAppear() {
    // 只需要传入 webController，配置会从应用入口的 RUM 配置中读取
    this.webViewHandler.setWebView(this.webController);
  }

  aboutToDisappear() {
    this.webViewHandler.clearWebController();
  }

  build() {
    Web({ 
      src: 'https://example.com', 
      controller: this.webController 
    })
    .javaScriptAccess(true)
    .javaScriptProxy(this.webViewHandler.getJavaScriptProxy(this.webController))
  }
}