콘텐츠로 이동

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

Action

이 문서는 React Native SDK에서 Action 자동 수집의 사용자 정의 규칙을 설명합니다.

enableAutoTrackUserAction 을 활성화하면 SDK는 React Native 컴포넌트의 클릭 작업을 자동으로 수집합니다. Babel 플러그인을 설치하지 않은 경우 SDK는 기존의 런타임 자동 수집 방식을 계속 사용하며, Babel 플러그인을 설치하면 컴파일 단계에서 지원되는 인터랙션 핸들러 함수에 계측을 추가하고 더 안정적이고 가독성이 높은 action_name 을 생성합니다.

Babel 플러그인으로 Action 이름 자동 생성

SDK 0.4.3부터 지원합니다.

Babel 플러그인 버전은 react-native-mobile 패키지 버전과 일치해야 합니다.

플러그인 설치

Babel 플러그인을 개발 의존성으로 설치합니다:

npm install --save-dev @cloudcare/react-native-mobile-babel-plugin

프로젝트의 babel.config.js 에서 플러그인을 활성화합니다:

module.exports = {
  presets: ['module:metro-react-native-babel-preset'],
  plugins: [
'@cloudcare/react-native-mobile-babel-plugin',
],
};

런타임 스위치로 enableAutoTrackUserAction 을 계속 사용하며, 새로운 RUM 설정을 추가할 필요가 없습니다:

const rumConfig: FTRUMConfig = {
  androidAppId: Config.ANDROID_APP_ID,
  iOSAppId: Config.IOS_APP_ID,
  enableAutoTrackUserAction: true,
};

await FTReactNativeRUM.setConfig(rumConfig);

Babel 플러그인을 활성화하면 SDK는 Babel 자동 수집 경로만 사용하여 기존 런타임 경로와의 중복 보고를 방지합니다. 플러그인을 설치하지 않은 경우 기존 자동 수집 동작은 그대로 유지됩니다.

Action 이름 생성 규칙

플러그인은 다음 우선순위에 따라 action_name 을 생성합니다:

  1. ft-action-name 정적 속성;
  2. actionNameAttribute 로 설정한 사용자 정의 정적 속성;
  3. accessibilityLabel 정적 속성;
  4. trackingLabel, title, label, text, 사용자 정의 콘텐츠 속성 또는 컴포넌트 children;
  5. JSX 컴포넌트 이름.

기본적으로 컴포넌트 이름 접두사를 유지합니다. 예를 들어 다음 컴포넌트가 생성하는 action_name 은 Button ("Submit") 입니다:

<Button
  ft-action-name="Submit"
  title="Pay now"
  onPress={submit}
/>

ft-action-name 을 설정하지 않으면 위 예시는 accessibilityLabel, title, 컴포넌트 이름 순으로 시도합니다. 명시적 Action 이름 속성은 정적 문자열만 지원하며, 콘텐츠 속성은 표현식을 사용할 수 있습니다.

사용자 정의 컴포넌트 구성

플러그인은 기본적으로 react-native 에서 이름으로 import한 Button, Pressable, TouchableOpacity, TouchableHighlight, TouchableWithoutFeedback, TouchableNativeFeedback, Switch, TextInput 을 인식하며 import alias를 지원합니다. 사용자 정의 컴포넌트는 components.tracked 로 구성할 수 있습니다:

이 중 버튼과 Touchable 계열은 onPress 를 수집하고, Pressable 은 onLongPress 도 수집하며, Switch 는 onValueChange 를, TextInput 은 onFocus 를 수집합니다.

module.exports = {
  presets: ['module:metro-react-native-babel-preset'],
  plugins: [
    [
'@cloudcare/react-native-mobile-babel-plugin',
{
        actionNameAttribute: 'analytics-name',
        components: {
          useContent: true,
          useNamePrefix: true,
          tracked: [
            {
              name: 'CustomButton',
              contentProp: 'caption',
              handlers: [
                {
                  event: 'onPress',
                  actionType: 'submit',
                },
              ],
            },
          ],
        },
      },
    ],
  ],
};
구성 항목 유형 기본값 설명
actionNameAttribute string - 우선순위가 ft-action-name 보다 낮은 추가 정적 Action 이름 속성을 설정합니다
components.useContent boolean true 콘텐츠 속성과 children에서 이름을 추출할지 여부
components.useNamePrefix boolean true Button ("Submit") 형식의 컴포넌트 이름 접두사를 생성할지 여부이며, 비활성화하면 Submit 만 생성합니다
components.tracked Array [] 추적할 사용자 정의 컴포넌트를 구성합니다
tracked[].name string - JSX 컴포넌트 이름이며, Menu.Item 형태의 멤버 컴포넌트도 구성할 수 있습니다
tracked[].contentProp string - 추가 콘텐츠 속성을 지정합니다
tracked[].handlers Array - 추적할 인터랙션 속성을 설정합니다
tracked[].handlers[].event string - 컴포넌트의 인터랙션 핸들러 속성 이름입니다. 예: onPress
tracked[].handlers[].actionType string click RUM action_type 에 보고할 값을 설정합니다. 생략하거나 빈 문자열이거나 공백 문자만 포함하는 경우 click 을 사용합니다
tracked[].handlers[].mode string default delayed 로 설정하면 핸들러를 실제 인터랙션 함수를 반환하는 팩토리 함수로 간주합니다

tracked[] 는 useContent 와 useNamePrefix 를 개별적으로 설정하여 components 레벨의 기본값을 재정의할 수도 있습니다.

여러 후보 이름을 포함하는 복합 컴포넌트의 경우 SDK는 인터랙션 핸들러의 첫 번째 숫자 인자를 사용하여 이름을 선택하며, 인자가 유효한 인덱스가 아니면 첫 번째 후보 이름을 사용합니다.

사용 제한

  • 플러그인은 startAction(actionName, actionType, property) 를 통해 Action을 보고합니다. actionType 은 기본적으로 click 을 사용하며, 사용자 정의 컴포넌트의 handler 설정에서 안정적이고 낮은 카디널리티의 사용자 정의 값을 지정할 수도 있습니다.
  • import * as ReactNative from 'react-native' 형태의 namespace import는 자동으로 인식하지 않습니다.
  • Web 빌드와 node_modules 아래의 파일은 변환되지 않습니다.
  • TextInput 에 onFocus 가 없는 경우, 플러그인은 원본 컴포넌트 이름을 사용하고 spread 속성이 없는 안전한 상황에서만 핸들러 함수를 주입합니다.
  • ft-enable-track 과 ft-extra-property 는 계속 적용됩니다. 이벤트에 React Native Fiber target이 포함되지 않은 경우 기본적으로 수집을 허용하며 확장 속성을 추가하지 않습니다.

특정 컴포넌트 클릭 이벤트의 actionName 사용자 정의

Babel 플러그인을 설치한 경우 ft-action-name 으로 설정하는 것을 권장하며, 플러그인을 설치하지 않은 경우 accessibilityLabel 로 계속 설정할 수 있습니다.

<Button
  title="Custom Action Name"
  ft-action-name="custom_action_name"
  accessibilityLabel="custom_action_name"
  onPress={() => {
    console.log('btn click');
  }}
/>

특정 컴포넌트 클릭 이벤트 수집하지 않기

ft-enable-track 사용자 정의 파라미터를 추가하여 설정할 수 있으며, 설정값은 false 입니다.

<Button
  title="Action Click"
  ft-enable-track="false"
  onPress={() => {
    console.log('btn click');
  }}
/>

특정 컴포넌트 클릭 이벤트에 추가 속성 추가

ft-extra-property 사용자 정의 파라미터를 추가하여 설정할 수 있으며, 값은 JSON 문자열이어야 합니다.

<Button
  title="Action 添加额外属性"
  ft-extra-property='{"e_name": "John Doe", "e_age": 30, "e_city": "New York"}'
  onPress={() => {
    console.log('btn click');
  }}
/>

문서 평가

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