Skip to content

Custom Rules for Data Collection

View

The automatic View collection rules require ft-sdk 0.1.17 or later, and you need to enable FTRUMConfig.setEnableTraceUserView(true).

Use setViewTrackingHandler(handler, type) to configure the automatic View handler for Router, Navigation, or both. type can be FTViewTrackingType.ROUTER, NAVIGATION, or ALL; when omitted, it defaults to ALL. The handler receives the FTViewTrackingContext that corresponds to the source type: in Router scenarios, you can read routerPageInfo; in Navigation scenarios, you can read navigationInfo. Returning null skips the automatic View; returning a HandlerView lets you rename it and add attributes.

import {
  FTRUMConfig,
  FTViewTrackingContext,
  FTViewTrackingHandler,
  FTViewTrackingType,
  HandlerView
} from '@guancecloud/ft_sdk/Index';

const viewHandler: FTViewTrackingHandler = {
  resolveHandlerView: (context: FTViewTrackingContext): HandlerView | null => {
    // Skip the automatic View for the login page.
    if (context.viewName === 'LoginPage') {
      return null;
    }

    // In Router scenarios, use ArkUI route information to filter or rename.
    if (context.trackingType === FTViewTrackingType.ROUTER &&
      context.routerPageInfo.path.startsWith('pages/internal/')) {
      return new HandlerView('InternalPage', { page_scope: new String('internal') });
    }

    return new HandlerView(context.viewName);
  }
};

const rumConfig = new FTRUMConfig()
  .setEnableTraceUserView(true)
  .setViewTrackingHandler(viewHandler, FTViewTrackingType.ALL);
Note

The input parameter passed to resolveHandlerView is FTViewTrackingContext, not a standalone View name string. After upgrading, use trackingType to distinguish routerPageInfo from navigationInfo, and avoid accessing fields that do not belong to the current source. This handler only affects automatic Views; it does not affect manual View collection such as FTRUMGlobalManager.startView(...).

Action

The automatic Action collection rules require ft-sdk 0.1.16 or later, and you need to enable FTRUMConfig.setEnableTraceUserAction(true).

Set the handler via setActionTrackingHandler(...). When it returns null, the SDK does not collect the Action; when it returns undefined, the SDK reports the Action name, attributes, location, and associated View information through the default automatic collection flow.

import {
  ActionEventWrapper,
  FTActionTrackingHandler,
  FTRUMConfig
} from '@guancecloud/ft_sdk/Index';

const actionHandler: FTActionTrackingHandler = {
  resolveHandlerAction: (event: ActionEventWrapper): null | undefined => {
    const source = event.getSource();

    // Ignore Actions triggered by the specified component.
    if (source?.getId() === 'ignore_action_view') {
      return null;
    }

    // Other operations continue to use the SDK's default automatic collection logic.
    return undefined;
  }
};

const rumConfig = new FTRUMConfig()
  .setEnableTraceUserAction(true)
  .setActionTrackingHandler(actionHandler);
Note

Actions that return null are skipped; when undefined is returned, the SDK continues with the default automatic collection. This handler only affects automatic Click collection; it does not affect manual calls to FTRUMGlobalManager.addAction(...) or startAction(...).

ActionEventWrapper provides the following information:

  • getSource(): The ArkUI FrameNode that triggered the Action. You can use it to filter by component ID, type, or custom attributes.
  • getSourceType(): The source type of the Action. The current HarmonyOS automatic collection pipeline passes ActionSourceType.CLICK_VIEW.
  • getExtra(): Additional information. The current automatic Click collection does not pass additional information and returns null.

Resource

Automatic Resource filtering requires ft-sdk 0.1.17 or later, and you need to enable FTRUMConfig.setEnableTraceUserResource(true). After setting the handler with setResourceUrlHandler(...), the automatic Resource collection for a URL is skipped when isInTakeUrl(url) returns true, and continues when it returns false.

import {
  FTInTakeUrlHandler,
  FTRUMConfig
} from '@guancecloud/ft_sdk/Index';

class ResourceUrlHandler extends FTInTakeUrlHandler {
  isInTakeUrl(url: string): boolean {
    return url.startsWith('https://telemetry.example.com/');
  }
}

const rumConfig = new FTRUMConfig()
  .setEnableTraceUserResource(true)
  .setResourceUrlHandler(new ResourceUrlHandler());

This rule only applies to automatic Resource collection for RCP, Axios, and NetworkKit; it does not prevent Trace Header injection, nor does it filter Resources manually reported through FTRUMGlobalManager.

Feedback

Is this page helpful?