본문으로 건너뛰기

자동 수집

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

Android SDK는 설치, 시작, 종료 등의 이벤트 자동 수집을 지원합니다.

1. 소개​

AE 시스템은 데이터를 자동으로 수집하는 인터페이스를 제공하며, 비즈니스 요구에 따라 자동으로 수집할 데이터를 직접 선택할 수 있습니다.

현재 지원하는 자동 수집 이벤트 유형은 다음과 같습니다.

  1. 설치 이벤트: APP이 설치된 행동을 기록합니다
  2. 시작 이벤트: APP을 여는 것과 백그라운드에서 APP을 여는 것을 포함합니다
  3. 종료 이벤트: APP을 닫는 것과 App이 백그라운드로 전환되는 것을 포함하며, 시작 후 사용 시간도 함께 수집합니다
  4. 페이지 조회 이벤트: 유저가 APP에서 페이지(Activity)를 조회합니다
  5. 클릭 이벤트: 유저가 APP에서 컨트롤을 클릭합니다
  6. 크래시 이벤트: APP에서 크래시가 발생하면 크래시 정보를 기록합니다

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

2. 자동 수집 활성화​

enableAutoTrack을 호출하여 자동 수집 기능을 활성화할 수 있습니다:

//APP 설치 이벤트 TDAnalytics.TDAutoTrackEventType.APP_INSTALL
//APP 시작 이벤트 TDAnalytics.TDAutoTrackEventType.APP_START
//APP 종료 이벤트 TDAnalytics.TDAutoTrackEventType.APP_END
//APP 페이지 조회 이벤트 TDAnalytics.TDAutoTrackEventType.APP_VIEW_SCREEN
//APP 컨트롤 클릭 이벤트 TDAnalytics.TDAutoTrackEventType.APP_CLICK
//APP 크래시 이벤트 TDAnalytics.TDAutoTrackEventType.APP_CRASH
//자동 수집 이벤트 활성화
TDAnalytics.enableAutoTrack(TDAnalytics.TDAutoTrackEventType.APP_START | TDAnalytics.TDAutoTrackEventType.APP_END
        | TDAnalytics.TDAutoTrackEventType.APP_INSTALL | TDAnalytics.TDAutoTrackEventType.APP_VIEW_SCREEN | TDAnalytics.TDAutoTrackEventType.APP_CLICK
        | TDAnalytics.TDAutoTrackEventType.APP_CRASH);
팁

컨트롤 클릭 이벤트나 Fragment 페이지 조회 이벤트를 수집해야 하는 경우 자동 수집 플러그인을 연동해야 합니다. 이 페이지의 7번 항목을 참고하십시오.

3. 상세 소개​

3.1 설치 이벤트​

APP 설치 이벤트는 APP의 실제 설치를 기록하며 APP 시작 시 전송됩니다. 이벤트 트리거 시간은 APP 설치 후 처음 시작한 시간입니다. APP 업그레이드는 설치 이벤트를 트리거하지 않으며, 삭제 후 재설치하면 설치 이벤트가 전송됩니다.

  • 이벤트 이름: ta_app_install

3.2 시작 이벤트​

APP 시작 이벤트는 유저가 APP을 열거나 백그라운드에서 APP을 깨울 때 트리거됩니다. 이벤트에 대한 자세한 소개는 다음과 같습니다.

  • 이벤트 이름: ta_app_start
  • 시스템 속성: #resume_from_background, 불리언 타입이며 APP을 유저가 열었는지 백그라운드에서 깨웠는지를 나타냅니다. 값이 true이면 백그라운드에서 깨운 것이고, false이면 직접 연 것입니다.
  • V2.8.1부터 SDK는 백그라운드 자동 시작(예: 백그라운드 서비스 직접 시작 또는 푸시)으로 트리거되는 start 이벤트를 기본적으로 더 이상 허용하지 않는다는 점에 유의하십시오. res/values 아래에 리소스 파일 ta_public_config.xml을 추가하여 활성화할 수 있습니다
<?xml version="1.0" encoding="utf-8"?>
<resources>
   <bool name="TAEnableBackgroundStartEvent">true</bool>
</resources>

3.3 종료 이벤트​

APP 종료 이벤트는 유저가 APP을 닫거나 APP을 백그라운드로 전환할 때 트리거됩니다. 이벤트에 대한 자세한 소개는 다음과 같습니다.

  • 이벤트 이름: ta_app_end
  • 시스템 속성: #duration, 숫자 타입이며 이번 APP 방문(시작부터 종료까지)의 시간을 나타냅니다. 단위는 초입니다.

3.4 페이지 조회 이벤트​

APP 페이지 조회 이벤트는 유저가 페이지(Activity)를 조회할 때 트리거됩니다. 이벤트에 대한 자세한 소개는 다음과 같습니다.

  • 이벤트 이름: ta_app_view

  • 시스템 속성:

    #screen_name, 문자열 타입이며 Activity의 패키지 이름.클래스 이름입니다

    #title, 문자열 타입이며 Activity의 제목으로, Activity의 title 속성 값을 사용합니다

페이지 조회 이벤트에 다른 속성을 추가하여 분석 가치를 확장할 수 있습니다. 다음은 페이지 조회 이벤트의 속성을 커스터마이즈하는 방법입니다

3.4.1 Fragment 페이지 조회 이벤트 자동 수집 활성화​

android.support.v4.app.Fragment의 Fragment는 다음 방법으로 페이지 조회 이벤트를 자동 수집할 수 있습니다:

SDK 초기화가 완료된 후 다음 메서드를 호출하여 Fragment 자동 수집 기능을 시작합니다

TDAnalytics.trackFragmentAppViewScreen();

android.app.Fragment의 Fragment는 다음 방법으로 페이지 조회 이벤트를 직접 호출할 수 있습니다:

TDAnalytics.trackViewScreen(targetFragment);
  • targetFragment는 페이지 조회 이벤트를 업로드할 Fragment로 바꿀 수 있습니다

3.4.2 페이지 조회 이벤트의 속성 커스터마이즈​

Activity의 페이지 조회 이벤트는 ScreenAutoTracker 인터페이스의 메서드를 구현하여 속성을 추가할 수 있습니다. 다음 두 메서드로 페이지 조회 이벤트에 페이지 URL 정보와 기타 커스텀 속성을 추가할 수 있습니다:

public class MainActivity extends AppCompatActivity implements ScreenAutoTracker {
    private Context mContext;

    @Override
    public String getScreenUrl() {
        return "thinkingdata://page/main";
    }

    @Override
    public JSONObject getTrackProperties() throws JSONException {
        JSONObject jsonObject = new JSONObject();
        jsonObject.put("param1", "ABCD");
        jsonObject.put("param2", "thinkingdata");
        return jsonObject;
    }
}

getScreenUrl의 반환값은 해당 Activity의 URL Schema로 사용됩니다. 해당 페이지의 조회 이벤트가 트리거되면 시스템 속성 #url이 추가되며, 값은 현재 페이지의 URL Schema입니다. 동시에 SDK는 이동 전 페이지의 URL Schema를 가져오며, 가져올 수 있으면 시스템 속성 #referrer에 이전 주소로 추가합니다.

getTrackProperties의 반환값은 해당 페이지 조회 이벤트의 커스텀 속성이며, 해당 페이지의 조회 이벤트에 자동으로 추가됩니다

Fragment의 페이지 조회 이벤트에는 두 가지 방식으로 속성을 추가할 수 있습니다

  • @ThinkingDataFragmentTitle 방식으로 속성 추가
@ThinkingDataFragmentTitle(title = "myFragment")
public class ListViewFragment extends BaseFragment {
  // your fragment implementations
}
  • ScreenAutoTracker 인터페이스 구현
  @Override
  public JSONObject getTrackProperties() {
      try {
          JSONObject properties = new JSONObject();
          properties.put("#title", "RecyclerViewFragment");
          return properties;
      } catch (JSONException e) {
          // ignore
      }
      return null;
  }

3.5 클릭 이벤트​

APP 컨트롤 클릭 이벤트는 유저가 컨트롤(view)을 클릭할 때 트리거됩니다

  • 이벤트 이름: ta_app_click

  • 시스템 속성:

    #screen_name, 문자열 타입이며 컨트롤이 속한 Activity의 패키지 이름.클래스 이름입니다

    #title, 문자열 타입이며 컨트롤이 속한 Activity의 제목으로, Activity의 title 속성 값을 사용합니다

    #element_content, 문자열 타입이며 컨트롤의 내용입니다

    #element_type, 문자열 타입이며 컨트롤의 유형입니다

    #element_id, 문자열 타입이며 컨트롤의 ID로, 기본적으로 android:id를 사용합니다

    #element_position, 문자열 타입이며 컨트롤에 position이 있을 때만 업로드됩니다

    #element_selector, 문자열 타입이며 컨트롤의 viewPath를 이어 붙인 값입니다

페이지의 View 클릭 이벤트는 다음과 같은 여러 방법으로 속성을 더 설정하여 분석 가치를 확장할 수 있습니다:

3.5.1 컨트롤 ID 커스터마이즈​

컨트롤 ID는 기본적으로 android:id를 사용합니다. 이 속성을 가져올 수 없거나 컨트롤 ID를 직접 정의하려면 다음 방법으로 #element_id 속성을 덮어쓸 수 있습니다

TDAnalytics.setViewID(view,viewID);

Dialog는 다음 방법을 사용할 수 있습니다:

//android.app.Dialog
TDAnalytics.setViewID(view,viewID);

또는

//android.support.v7.app.AlertDialog
TDAnalytics.setViewID(view,viewID);

파라미터 view는 컨트롤 ID를 설정할 view이고, 파라미터 viewID는 설정할 컨트롤 ID입니다. 해당 컨트롤의 클릭 이벤트를 업로드할 때 #element_id의 값은 여기서 전달한 값이 됩니다

3.5.2 컨트롤 클릭 이벤트의 속성 커스터마이즈​

다음 방법으로 특정 컨트롤(view)의 클릭 이벤트에 커스텀 속성을 추가할 수 있습니다:

TDAnalytics.setViewProperties(view,properties);

파라미터 view는 커스텀 속성을 설정할 view이고, 파라미터 properties는 JSONObject 타입의 설정할 커스텀 속성입니다. 해당 컨트롤의 클릭 이벤트를 업로드할 때 이 속성들이 추가됩니다.

또한 ExpandableListView, ListView, GridView는 Adapter에서 인터페이스를 구현하는 방식으로 특정 item을 클릭할 때의 커스텀 속성을 추가할 수도 있습니다.

  • ExpandableListView는 ThinkingExpandableListViewItemTrackProperties 인터페이스를 구현해야 합니다
public interface ThinkingExpandableListViewItemTrackProperties {
    /**
     * groupPosition, childPosition 위치의 item을 클릭할 때의 속성 추가
     * @param groupPosition
     * @param childPosition
     * @return
     * @throws JSONException
     */
    JSONObject getThinkingChildItemTrackProperties(int groupPosition, int childPosition) throws JSONException;

    /**
     * groupPosition 위치의 item을 클릭할 때의 속성 추가
     * @param groupPosition
     * @return
     * @throws JSONException
     */
    JSONObject getThinkingGroupItemTrackProperties(int groupPosition) throws JSONException;
}
  • ListView와 GridView는 ThinkingAdapterViewItemTrackProperties 인터페이스를 구현해야 합니다
public interface ThinkingAdapterViewItemTrackProperties {
    /**
     * position 위치의 item을 클릭할 때의 속성 추가
     * @param position
     * @return
     * @throws JSONException
     */
    JSONObject getThinkingItemTrackProperties(int position) throws JSONException;
}

3.5.3 AlertDialog의 클릭 이벤트에 페이지(Activity) 정보 추가​

AlertDialog(android.app.AlertDialog와 android.support.v7.app.AlertDialog)의 클릭 이벤트는 다음 방법으로 소속 페이지(Activity)를 연결할 수 있으며, 클릭 이벤트에 소속 페이지의 #screen_name과 #title 속성이 추가됩니다.

  • dialog.show()를 호출하여 dialog를 표시하는 경우 다음 방법을 사용하십시오:
dialog.setOwnerActivity(targetActivity);
  • builder.show()를 호출하여 dialog를 표시하는 경우 다음 방법을 사용하십시오:
builder.show().setOwnerActivity(activity);

3.5.4 @ThinkingDataTrackViewOnClick 어노테이션으로 컨트롤 클릭 이벤트 업로드​

android:onclick으로 컨트롤(view)에 클릭 이벤트 호출 메서드를 추가한 경우, 호출 메서드에 @ThinkingDataTrackViewOnClick 어노테이션을 추가할 수 있습니다. 해당 호출 메서드가 실행되면 SDK가 컨트롤 클릭 이벤트를 업로드합니다

@ThinkingDataTrackViewOnClick
public void buttonOnClick(View v){}

buttonOnClick 메서드가 호출되면 컨트롤 클릭 이벤트가 업로드됩니다

3.6 크래시 이벤트​

APP에서 처리되지 않은 예외가 발생하면 APP 크래시 이벤트가 전송됩니다

  • 이벤트 이름: ta_app_crash
  • 시스템 속성: #app_crashed_reason, 문자 타입이며 크래시 발생 시의 스택 트레이스를 기록합니다

4. 자동 수집 이벤트 무시​

다음 방법으로 특정 페이지나 컨트롤의 자동 수집 이벤트를 무시할 수 있습니다

4.1 페이지의 자동 수집 이벤트 무시​

특정 페이지(Activity)에서 자동 수집 이벤트(페이지 조회 및 컨트롤 클릭 이벤트 포함)를 전송하지 않으려면 다음 방법으로 무시할 수 있습니다:

//단일 페이지 무시
TDAnalytics.ignoreAutoTrackActivity(MainActivity.class);
//여러 페이지 무시
List<Class<?>> classList = new ArrayList<>();
classList.add(MainActivity.class);
TDAnalytics.ignoreAutoTrackActivities(classList);

Activity 또는 Fragment 앞에 @ThinkingDataIgnoreTrackAppViewScreen 어노테이션을 추가하여 특정 Activity 또는 Fragment의 페이지 조회 이벤트를 무시할 수도 있습니다

//TestActivity의 페이지 조회 이벤트 무시
@ThinkingDataIgnoreTrackAppViewScreen
public class TestActivity extends AppCompatActivity {
    ...
}

Activity 앞에 @ThinkingDataIgnoreTrackAppViewScreenAndAppClick 어노테이션을 추가하면 특정 Activity의 페이지 조회 이벤트와 해당 페이지의 컨트롤 클릭 이벤트를 무시합니다

//TestActivity의 페이지 조회 이벤트와 해당 페이지의 컨트롤 클릭 이벤트 무시
@ThinkingDataIgnoreTrackAppViewScreenAndAppClick
public class TestActivity extends AppCompatActivity {
    ...
}

4.2 특정 유형 컨트롤의 클릭 이벤트 무시​

특정 유형 컨트롤의 클릭 이벤트를 무시하려면 다음 방법을 사용할 수 있습니다

TDAnalytics.ignoreViewType(ignoredClass);
  • ignoredClass는 무시할 컨트롤 유형입니다(예: Dialog, Checkbox 등)

4.3 특정 요소(View)의 클릭 이벤트 무시​

특정 요소(View)의 클릭 이벤트를 무시하려면 다음 방법을 사용할 수 있습니다

TDAnalytics.ignoreView(targetView);
  • targetView는 무시할 View입니다

5. 어노테이션으로 이벤트 빠르게 설정​

특정 메서드의 호출 횟수를 모니터링하거나 특정 메서드가 호출될 때마다 이벤트를 업로드해야 하는 경우, @ThinkingDataTrackEvent 어노테이션으로 업로드할 이벤트를 빠르게 설정할 수 있습니다. 단, 속성에 변수를 전달할 수 없으므로 간단한 이벤트를 업로드하는 데만 적합합니다

//어노테이션 사용
@ThinkingDataTrackEvent(eventName = "event_name", properties = "{\"paramString\":\"value\",\"paramNumber\":123,\"paramBoolean\":true}")
public void fun(){}

이때 fun 메서드가 호출되면 이벤트 이름이 event_name이고 속성이 "paramString":"value", "paramNumber":123, "paramBoolean":true인 이벤트가 업로드됩니다

6. 자동 수집 이벤트의 시스템 속성​

다음 시스템 속성은 각 자동 수집 이벤트에만 있는 시스템 속성입니다

  • APP 시작 이벤트(ta_app_start)의 시스템 속성
속성 이름한국어 이름속성 타입설명

#resume_from_background

백그라운드에서 깨웠는지 여부

불리언

APP을 열었는지 백그라운드에서 깨웠는지를 나타냅니다. 값이 true이면 백그라운드에서 깨운 것이고, false이면 직접 연 것입니다
#start_reason

앱 시작 출처

텍스트

내용은 JSON 문자열입니다. 앱을 url 또는 intent 방식으로 열면 url 내용과 intent의 data 데이터를 자동으로 기록합니다. 예시:{url:"thinkingdata://","data":{}}

#background_duration

백그라운드 체류 시간

숫자

두 번의 start 이벤트 사이에 앱이 백그라운드에 있었던 시간을 기록합니다.

단위: 초

  • APP 종료 이벤트(ta_app_end)의 시스템 속성
속성 이름한국어 이름속성 타입설명
#duration이벤트 시간숫자이번 APP 방문(시작부터 종료까지)의 시간을 나타내며, 단위는 초입니다
  • APP 페이지 조회 이벤트(ta_app_view)의 시스템 속성
속성 이름표시 이름속성 타입설명
#title

페이지 제목

텍스트현재 페이지 Activity의 제목으로, Activity의 title 속성 값을 사용합니다
#screen_name페이지 이름텍스트현재 페이지 Activity의 패키지 이름.클래스 이름
#url페이지 주소텍스트현재 페이지의 주소이며, getScreenUrl을 호출하여 url을 설정해야 합니다
#referrer이전 주소텍스트이동 전 페이지의 주소이며, 이동 전 페이지에서 getScreenUrl을 호출하여 url을 설정해야 합니다
  • APP 컨트롤 클릭 이벤트(ta_app_click)의 시스템 속성
속성 이름표시 이름속성 타입설명
#title페이지 제목텍스트컨트롤이 속한 Activity의 제목으로, Activity의 title 속성 값을 사용
#screen_name페이지 이름텍스트컨트롤이 속한 Activity의 패키지 이름.클래스 이름
#element_id요소 ID텍스트컨트롤의 ID. 기본적으로 android:id를 사용하며 setViewID를 호출하여 설정 가능
#element_type요소 유형텍스트컨트롤의 유형
#element_selector요소 선택자텍스트컨트롤의 viewPath를 이어 붙인 값
#element_position요소 위치텍스트컨트롤의 위치 정보. 컨트롤에 position 속성이 있을 때만 업로드
#element_content요소 내용텍스트컨트롤의 내용
  • APP 크래시 이벤트(ta_app_crash)의 시스템 속성
속성 이름한국어 이름속성 타입설명
#app_crashed_reason예외 정보텍스트문자 타입이며 크래시 발생 시의 스택 트레이스를 기록

7. 선택 플러그인​

팁

컨트롤 클릭 이벤트와 Fragment 페이지 조회 이벤트를 활성화해야 하는 경우에만 이 플러그인을 연동하면 됩니다.

팁

2.1.0 버전부터 Gradle 8.0과 호환됩니다.

Android 분석 SDK 버전플러그인 버전
[oldest - 3.0.0)1.2.0
[3.0.0 - 3.1.0]2.1.0
(3.1.0 - latest]2.2.0
buildscript {
    repositories {
        google()
        jcenter()
    }
    dependencies {
        classpath 'cn.thinkingdata.android:android-gradle-plugin2:2.2.0'
    }
}

프로젝트의 build.gradle 파일에서 플러그인 관련 파라미터를 설정할 수 있습니다

apply plugin: 'cn.thinkingdata.android'
android {

}
ThinkingAnalytics {
    debug = true
    exclude = []
    sdk{
        disableAndroidID = false
    }
}

파라미터 설명:

  • debug: 컴파일 로그를 출력할지 여부입니다. true이면 컴파일 로그를 출력하며, 기본값은 false입니다.
  • exclude: 특정 경로의 클래스를 스캔 대상에서 제외합니다. exclude = ['cn.thinkingdata.android','android.support']로 설정할 수 있습니다.
  • useInclude, include: 특정 경로의 클래스만 스캔하려면 useInclude = true, include= ['cn.thinkingdata.android','android.support']로 설정할 수 있습니다.
  • disableAndroidID: 시스템 API를 호출하여 AndroidID를 가져오는 것을 비활성화할지 여부입니다. 플러그인 V2.1.0 버전부터 disableAndroidID = true로 설정할 수 있습니다.

8. 커스텀 속성 설정​

TDAnalytics.enableAutoTrack(int autoTrackEventType, JSONObject properties)를 호출하여 자동 수집 기능을 활성화하면서 커스텀 속성을 설정할 수 있습니다

JSONObject properties = new JSONObject();
try {
    properties.put("auto_self_define_key", "auto_self_define_value");
} catch (Exception e) {
    e.printStackTrace();
}
TDAnalytics.enableAutoTrack(typeList, properties);

9. 자동 수집 이벤트 콜백 설정​

콜백을 설정하면 활성화된 자동 수집 이벤트가 발생할 때 현재 이벤트의 이벤트 유형과 포함된 이벤트 속성을 가져올 수 있으며, 반환값을 설정하는 방식으로 해당 이벤트에 추가로 전송할 속성을 더할 수 있습니다.

TDAnalytics.enableAutoTrack(TDAnalytics.TDAutoTrackEventType.APP_END | TDAnalytics.TDAutoTrackEventType.APP_START, new TDAnalytics.TDAutoTrackEventHandler() {
    @Override
    public JSONObject getPropertiesWithEventType(int eventType, JSONObject properties) {
        try {
            return new JSONObject("{\"keykey\":\"value1111\"}");
        } catch (JSONException e) {
            e.printStackTrace();
            return null;
        }
    }
});
이 문서가 도움이 되었나요?
이 페이지의 내용