콘텐츠로 이동

데이터 수집 사용자 정의 규칙

View

자동 View 수집 규칙을 사용하려면 ft-sdk 0.1.17 이상 버전이 필요하며 FTRUMConfig.setEnableTraceUserView(true)를 활성화해야 합니다.

setViewTrackingHandler(handler, type)을 사용하여 Router, Navigation 또는 둘 다에 대한 자동 View 핸들러를 구성합니다. type은 FTViewTrackingType.ROUTER, NAVIGATION, ALL을 사용할 수 있으며, 생략하면 기본값은 ALL입니다. 핸들러는 소스 유형에 해당하는 FTViewTrackingContext를 전달받습니다. Router 시나리오에서는 routerPageInfo를, Navigation 시나리오에서는 navigationInfo를 읽을 수 있습니다. null을 반환하면 해당 자동 View는 건너뛰어지고, HandlerView를 반환하면 이름을 변경하고 속성을 추가할 수 있습니다.

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

const viewHandler: FTViewTrackingHandler = {
  resolveHandlerView: (context: FTViewTrackingContext): HandlerView | null => {
    // 로그인 페이지의 자동 View는 수집하지 않습니다.
    if (context.viewName === 'LoginPage') {
      return null;
    }

    // Router 시나리오에서는 ArkUI 라우트 정보를 사용하여 필터링하거나 이름을 변경할 수 있습니다.
    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);
주의

resolveHandlerView의 입력 인자는 FTViewTrackingContext이며, 별도의 View 이름 문자열이 아닙니다. 업그레이드 후에는 trackingType에 따라 routerPageInfo와 navigationInfo를 구분하여 현재 소스에 속하지 않는 필드에 접근하지 않도록 주의하세요. 이 핸들러는 자동 View에만 영향을 미치며 FTRUMGlobalManager.startView(...) 등 수동 View 수집에는 영향을 미치지 않습니다.

Action

자동 Action 수집 규칙을 사용하려면 ft-sdk 0.1.16 이상 버전이 필요하며 FTRUMConfig.setEnableTraceUserAction(true)를 활성화해야 합니다.

setActionTrackingHandler(...)를 통해 핸들러를 설정합니다. null을 반환하면 SDK는 해당 Action을 수집하지 않으며, undefined를 반환하면 SDK는 기본 자동 수집 프로세스에 따라 Action 이름, 속성, 위치 및 View 연결 정보를 보고합니다.

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

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

    // 지정된 컴포넌트가 트리거한 Action을 무시합니다.
    if (source?.getId() === 'ignore_action_view') {
      return null;
    }

    // 그 외 작업은 SDK의 기본 자동 수집 로직을 계속 사용합니다.
    return undefined;
  }
};

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

null을 반환한 Action은 건너뛰어지며, undefined를 반환하면 SDK는 기본 자동 수집을 계속 수행합니다. 이 핸들러는 자동 Click 수집에만 영향을 미치며, 수동으로 호출하는 FTRUMGlobalManager.addAction(...) 또는 startAction(...)에는 영향을 미치지 않습니다.

ActionEventWrapper는 다음 정보를 제공합니다.

  • getSource(): 작업을 트리거한 ArkUI FrameNode입니다. 컴포넌트 ID, 유형 또는 사용자 정의 속성을 기준으로 필터링할 수 있습니다.
  • getSourceType(): 작업 소스 유형입니다. 현재 HarmonyOS 자동 수집 체인에서는 ActionSourceType.CLICK_VIEW를 전달합니다.
  • getExtra(): 추가 정보입니다. 현재 자동 Click 수집에서는 추가 정보가 전달되지 않으며 null을 반환합니다.

Resource

자동 Resource 필터링을 사용하려면 ft-sdk 0.1.17 이상 버전이 필요하며 FTRUMConfig.setEnableTraceUserResource(true)를 활성화해야 합니다. setResourceUrlHandler(...)로 핸들러를 설정하면 isInTakeUrl(url)이 true를 반환하는 URL의 자동 Resource 수집은 건너뛰고, 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());

이 규칙은 RCP, Axios 및 NetworkKit의 자동 Resource 수집에만 적용됩니다. Trace 헤더 주입을 차단하지 않으며 FTRUMGlobalManager를 통해 수동으로 보고된 Resource도 필터링하지 않습니다.

문서 평가

이 페이지가 도움이 되었나요?