자동 수집

최근 업데이트 2026. 10. 03.

1.2.0 버전부터 자동 수집 기능을 제공합니다. 인스턴스를 생성하는 config에서 자동 수집할 이벤트를 활성화하기만 하면 SDK가 미니 프로그램의 일부 행동을 자동으로 수집합니다. 현재 자동 수집을 지원하는 주요 이벤트는 다음과 같습니다:

현재 지원하는 자동 수집 데이터는 다음과 같습니다:

미니 프로그램 초기화, 유저가 한 번 사용할 때 한 번만 트리거됨
미니 프로그램 시작, 시작과 백그라운드에서 포그라운드로의 복귀를 포함
미니 프로그램이 백그라운드로 전환되며, 이번 방문(시작부터 백그라운드 전환까지)의 시간을 기록
미니 프로그램 페이지 표시 또는 포그라운드 전환, 페이지 경로와 이전 경로를 자동으로 기록
미니 프로그램 공유, 공유 시점의 페이지를 자동으로 기록
미니 프로그램 페이지 언로드, 페이지가 언로드될 때 자동으로 기록(3.2.0 이상 버전 지원)
미니 프로그램 페이지 즐겨찾기, 페이지가 즐겨찾기에 추가될 때 자동으로 기록(3.2.0 이상 버전 지원)
미니 프로그램 페이지 요소 클릭, 페이지 요소가 클릭될 때 자동으로 기록(3.2.0 이상 버전 지원)

다음에서는 각 데이터의 수집 방법을 자세히 소개합니다

1. 자동 수집 이벤트 활성화

config에서 파라미터 autoTrack의 요소는 각 자동 수집 이벤트의 스위치를 나타내며, true로 설정하면 자동 수집이 활성화됩니다:

var config = {
  appid: "YOU-APP-ID",
  server_url: "https://youserverurl.com",
  autoTrack: {
    appLaunch: true, // ta_mp_launch 자동 수집
    appShow: true, // ta_mp_show 자동 수집
    appHide: true, // ta_mp_hide 자동 수집
    pageShow: true, // ta_mp_view 자동 수집
    pageShare: true, // ta_mp_share 자동 수집
    pageLeave: true,// ta_page_leave 자동 수집
    mpFavorite: true,// ta_add_favorite 자동 수집
    mpClick: true,// ta_mp_click 자동 수집
    properties: { // 자동 수집 커스텀 속성
        staticKey: 'staticValue'
    },
    callback: (eventType:any) => { // 자동 수집 콜백
        if (eventType === 'appShow') {
            return { appShowKey: 'appShowValue' };
        } else if (eventType === 'appHide') {
            return { appHideKey: 'appHideValue' };
        } else {
            return {};
        }
    }
  }
};

appLaunch: 미니 프로그램 초기화 자동 수집
appShow: 미니 프로그램 시작 또는 백그라운드에서 포그라운드 진입 자동 수집
appHide: 미니 프로그램의 포그라운드에서 백그라운드 진입 자동 수집
pageShow: 미니 프로그램 페이지 표시 또는 포그라운드 전환 자동 수집
pageShare: 미니 프로그램 공유 자동 수집
pageLeave: 미니 프로그램 페이지 언로드 자동 수집
mpFavorite: 페이지 즐겨찾기 자동 수집
mpClick: 페이지 요소 클릭 자동 수집
properties: 자동 수집 커스텀 속성(appShow/appHide 지원)
callback: 자동 수집 콜백(appShow/appHide 지원)

플랫폼마다 실행 환경과 구조가 달라 지원하는 자동 수집 이벤트가 다릅니다. 지원 목록은 다음과 같습니다:

플랫폼	appLaunch	appShow	appHide	pageShow	pageShare	pageLeave	mpFavorite	mpClick
미니 프로그램	√	√	√	√	√	√	√	√
미니 게임	√	√	√

2. 자동 수집 이벤트 상세 설명

2.1 미니 프로그램 초기화

미니 프로그램 초기화는 미니 프로그램이 처음 열릴 때 또는 유저가 프로세스를 종료한 후 다시 열 때 트리거되며, 프로세스 라이프사이클 내에서 한 번만 트리거됩니다. 이벤트 상세 설명은 다음과 같습니다:

이벤트 이름: ta_mp_launch
자동 수집 속성:
- #scene: 장면 값으로, 위챗에서 제공하는 장면 값을 사용합니다
- #start_reason: 앱 시작 출처로, 내용은 JSON 문자열이며 getLaunchOptionsSync 인터페이스에서 가져온 파라미터입니다

미니 프로그램 초기화 이벤트로 일별 유저 사용 횟수와 인당 사용 횟수를 계산할 수 있으며, 장면 값으로 그룹화하여 장면 값별 유저의 사용 현황을 확인할 수도 있습니다.

2.2 미니 프로그램 시작

미니 프로그램 시작은 미니 프로그램이 시작되거나 백그라운드에서 포그라운드로 돌아올 때 트리거됩니다. 이벤트 상세 설명은 다음과 같습니다:

이벤트 이름: ta_mp_show
자동 수집 속성:
- #scene, 장면 값으로, 위챗에서 제공하는 장면 값을 사용합니다
- #url_path, 페이지 경로로, 미니 프로그램 시작 시 표시되는 페이지의 경로입니다
- #start_reason: 앱 시작 출처로, 내용은 JSON 문자열이며 getLaunchOptionsSync 인터페이스에서 가져온 파라미터입니다

미니 프로그램 시작은 포그라운드/백그라운드 전환의 영향을 받아(건수가 많음) 직접 분석하기에는 적합하지 않지만, 행동 경로에서 유저의 1회 사용을 식별하는 데 활용할 수 있으며 유저 행동 경로의 시작 행동으로 사용할 수 있습니다

2.3 미니 프로그램 숨김

미니 프로그램 숨김은 미니 프로그램이 백그라운드로 전환될 때 트리거되며, 이번 사용 시간을 기록합니다. 이벤트 상세 설명은 다음과 같습니다:

이벤트 이름: ta_mp_hide
자동 수집 속성:
- #scene, 장면 값으로, 위챗에서 제공하는 장면 값을 사용합니다
- #duration, 숫자형으로, 이번 시작(ta_mp_show)부터 숨김까지의 지속 시간을 나타냅니다

미니 프로그램 숨김 이벤트는 사용 시간(단위: 초)을 기록하므로 유저의 총 사용 시간과 인당 사용 시간을 바로 계산할 수 있으며, 초기화 횟수로 나누어 1회 사용 시간을 계산할 수도 있습니다.

2.4 미니 프로그램 페이지 조회

미니 프로그램 페이지 조회는 미니 프로그램의 페이지가 열릴 때 또는 미니 프로그램이 백그라운드에서 포그라운드로 돌아와 페이지가 표시될 때 트리거되며, 페이지 경로와 방문의 이전 경로를 기록합니다. 이벤트 상세 설명은 다음과 같습니다:

이벤트 이름: ta_mp_view
자동 수집 속성:
- #scene, 장면 값으로, 위챗에서 제공하는 장면 값을 사용합니다
- #url_path, 페이지 경로로, 표시되는 페이지의 경로입니다
- #referrer, 이전 경로로, 표시되는 페이지 직전 페이지의 경로, 즉 이동 전 경로입니다. 미니 프로그램을 시작할 때 표시되는 첫 페이지인 경우 값은 "直接打开"입니다

미니 프로그램 페이지 조회 이벤트로 각 페이지의 pv, uv와 유저가 미니 프로그램을 이용하는 경로를 계산할 수 있습니다.

미니 프로그램 페이지 공유는 공유 버튼을 클릭할 때 트리거됩니다(오른쪽 상단 내비게이션 바의 공유 버튼과 페이지 안의 공유 버튼 포함). 이벤트 상세 설명은 다음과 같습니다:

이벤트 이름: ta_mp_share
자동 수집 속성:
- #scene, 장면 값으로, 위챗에서 제공하는 장면 값을 사용합니다
- #url_path, 페이지 경로로, 공유할 때 있던 페이지의 경로입니다

미니 프로그램 페이지 공유 이벤트는 페이지의 공유율을 분석하는 데 적합하며, 페이지 공유를 최적화하는 데 도움이 됩니다.

2.6 미니 프로그램 페이지 언로드

미니 프로그램 페이지가 언로드될 때(예: 다른 페이지로 이동할 때) 트리거됩니다. 이벤트 상세 설명은 다음과 같습니다:

이벤트 이름: ta_page_leave
자동 수집 속성:
- #duration, 페이지 체류 시간
- #url_path, 페이지 경로로, 페이지가 언로드될 때의 경로입니다

2.7 미니 프로그램 페이지 즐겨찾기

미니 프로그램 페이지가 즐겨찾기에 추가될 때 트리거됩니다. 이벤트 상세 설명은 다음과 같습니다:

이벤트 이름: ta_add_favorite
자동 수집 속성:
- #url_path, 페이지 경로로, 페이지가 언로드될 때의 경로입니다

2.8 미니 프로그램 페이지 요소 클릭

미니 프로그램 페이지 요소가 클릭될 때 트리거됩니다. 이벤트 상세 설명은 다음과 같습니다:

이벤트 이름: ta_mp_click
자동 수집 속성:
- #element_id, 요소 ID
- #element_type, 요소 타입
- #element_content, 요소 내용
- #element_name, 요소 이름

이 문서가 도움이 되었나요?

1. 자동 수집 이벤트 활성화​

2. 자동 수집 이벤트 상세 설명​

2.1 미니 프로그램 초기화​

2.2 미니 프로그램 시작​

2.3 미니 프로그램 숨김​

2.4 미니 프로그램 페이지 조회​

2.5 미니 프로그램 페이지 공유​

2.6 미니 프로그램 페이지 언로드​

2.7 미니 프로그램 페이지 즐겨찾기​

2.8 미니 프로그램 페이지 요소 클릭​