Android SDK 자동 수집 가이드

Android SDK는 설치, 실행, 종료 등의 이벤트를 자동으로 수집하는 기능을 지원합니다.

자동 수집 소개

TE 시스템에서 자동으로 수집할 수 있는 호출은 다음과 같습니다. 실제 업무에 맞게 사용하세요.

1. 설치 이벤트(Install)：앱의 설치 행동을 기록
2. 실행 이벤트(Open APP)：앱을 실행하거나 백그라운드에서 앱을 실행
3. 종료 이벤트(Close APP)：앱을 종료하거나 앱이 백그라운드로 이동. 동시에 실행한 시간의 경과도 수집
4. 페이지 조회 이벤트(View Page)：앱 내에서 페이지 뷰(Activity)를 조회
5. 클릭 이벤트(Click)：앱 내의 컨트롤러(view)를 클릭
6. 크래시 이벤트(Crash)：앱이 크래시됐을 때의 정보 수집

이제 각 데이터 수집 방법에 대해 소개하겠습니다.

자동 수집 활성화

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

//TDAnalytics.TDAutoTrackEventType.APP_INSTALL
//TDAnalytics.TDAutoTrackEventType.APP_START
//TDAnalytics.TDAutoTrackEventType.APP_END
//TDAnalytics.TDAutoTrackEventType.APP_VIEW_SCREEN
//TDAnalytics.TDAutoTrackEventType.APP_CLICK
//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);

TIP

컨트롤러의 클릭 이벤트 또는 Fragment의 페이지 조회 이벤트를 수집하려면, 자동 수집 플러그인을 구현해야 합니다.

상세 소개

3.1 설치 이벤트(Install)

앱의 설치 이벤트를 기록하고, 앱이 실행될 때 전송합니다. 이벤트의 트리거 시간은 앱 설치 후 첫 실행 시간입니다. 앱의 버전 업은 설치 이벤트로 계산되지 않지만, 삭제 후 재설치는 계산됩니다.

• 이벤트 이름：ta_app_install

3.2 실행 이벤트(Open APP)

유저가 앱을 실행할 때, 또는 백그라운드에서 앱을 실행할 때 수집됩니다

• 이벤트 이름：ta_app_start
• 프리셋 속성: #resume_from_background, Boolean 타입으로, 앱이 직접 실행되었는지, 백그라운드에서 실행되었는지를 기록합니다. 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 종료 이벤트(Close APP)

유저가 앱을 종료하거나, 앱을 백그라운드로 이동할 때 수집됩니다.

• 이벤트 이름: ta_app_end
• 프리셋 속성: #duration, 숫자 타입으로, 앱 실행의 경과 시간을 통계합니다.(단위: 초)

3.4 페이지 조회 이벤트(View Page)

앱에서 페이지 조회(Activity)를 할 때 수집됩니다.

• 이벤트 이름：ta_app_view
• 프리셋 속성:

#screen_name, 문자열, Activity의 패키지 이름과 카테고리 이름

#title, 문자열, Activity의 타이틀, Activity의 title 속성 값을 가져옴

페이지 조회 이벤트에서는 다른 속성을 확장하여 분석 가치를 높일 수 있습니다. 다음은 확장 방법입니다.

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

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

SDK 초기화 완료 후, 다음 방법으로 Fragment의 자동 수집 기능을 호출할 수 있습니다.

ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).trackFragmentAppViewScreen();

android.app.Fragment의 Fragment는, 다음 방법으로 할 수 있습니다.

ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).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이라는 프리셋 속성을 추가할 수 있습니다. 동시에 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 클릭 이벤트(Click)

앱의 클릭 이벤트는 컨트롤러(view)를 클릭할 때 수집됩니다.

• 이벤트 이름：ta_app_click
• 프리셋 속성:

#screen_name 문자열 타입, view가 속해 있는 Activity의 패키지 이름 & 카테고리 이름

#title 문자열 타입, view가 속해 있는 Activity의 타이틀로, Activity의 title 값을 사용

#element_content 문자열 타입, view의 내용

#element_type 문자열타입, view의 타입

#element_id 문자열 타입, view의 ID, 기본적으로 android:id 사용

#element_position 문자열 타입, view에 position이 존재할 경우 수집

#element_selector 문자열 타입, view의 viewPath의 결합

페이지 상의 View의 클릭 이벤트에 대해, 다양한 방법으로 기타 속성을 설정하여 분석 가치를 높일 수 있습니다.

3.5.1 ViewID 정의

viewID는 기본적으로 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는 viewID의 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 {
    /**
     * Add properties when clicking items at groupPosition and childPosition
     * @param groupPosition
     * @param childPosition
     * @return
     * @throws JSONException
     */
    JSONObject getThinkingChildItemTrackProperties(int groupPosition, int childPosition) throws JSONException;

    /**
     * Add properties when clicking items at groupPosition
     * @param groupPosition
     * @return
     * @throws JSONException
     */
    JSONObject getThinkingGroupItemTrackProperties(int groupPosition) throws JSONException;
}

• ListView와 GridView는 ThinkingAdapterViewItemTrackProperties 인터페이스 구현이 필수입니다.

public interface ThinkingAdapterViewItemTrackProperties {
    /**
     * Add properties when clicking items in the position 
     * @param position
     * @return
     * @throws JSONException
     */
    JSONObject getThinkingItemTrackProperties(int position) throws JSONException;
}

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

AlertDialog(안드로이드.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 주석을 사용해 view의 클릭 이벤트 전송

android:onclick을 사용하는 view가 있다면, @ThinkingDataTrackViewOnClick 주석을 추가함으로써 클릭 이벤트 호출 방식을 구현할 수 있습니다.

@ThinkingDataTrackViewOnClick
public void buttonOnClick(View v){}

buttonOnClick이 호출되면, 그것을 클릭 이벤트로 전송합니다.

3.6 크래시 이벤트(Crash)

앱에 예상치 못한 오류가 발생할 때, 크래시 이벤트가 수집됩니다.

• 이벤트 이름：ta_app_crash
• 프리셋 속성：#app_crashed_reason 문자열형으로, 크래시 발생 시의 스택 트레이스를 기록합니다.

자동 수집 이벤트 비활성화

다음 방법으로, 특정 페이지 또는 view의 자동 수집 이벤트를 비활성화 할 수 있습니다.

4.1 페이지의 자동 수집 이벤트 비활성화

특정 페이지의 Activity 자동 수집 이벤트(페이지 조회 및 view 클릭)를 수집하고 싶지 않은 경우, 다음 방법으로 가능합니다.

//ignore a single screen
ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).ignoreAutoTrackActivity(MainActivity.class);
//ignore multiple screens
List<Class<?>> classList = new ArrayList<>();
classList.add(MainActivity.class);
ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).ignoreAutoTrackActivities(classList);

Activity 또는 Fragment 앞에 @ThinkingDataIgnoreTrackAppViewScreen 주석을 추가함으로써, 특정 Activity 또는 Fragment의 페이지 조회 이벤트를 비활성화 할 수 있습니다.

//ignore the view screen event of TestActivity
@ThinkingDataIgnoreTrackAppViewScreen
public class TestActivity extends AppCompatActivity {
    ...
}

Activity 앞에 @ThinkingDataIgnoreTrackAppViewScreenAndAppClick 주석을 추가함으로써, Activity의 특정 페이지 조회 이벤트 및 해당 이벤트의 view 클릭 이벤트를 비활성화 할 수 있습니다.

//ignore the view screen event ofTestActivity as well as the view click event under the screen
@ThinkingDataIgnoreTrackAppViewScreenAndAppClick
public class TestActivity extends AppCompatActivity {
    ...
}

4.2 특정 타입 view의 클릭 이벤트 비활성화

특정 타입 view의 클릭 이벤트를 비활성화 하고 싶은 경우, 다음 방법으로 가능합니다.

TDAnalytics.ignoreViewType(ignoredClass);

• ignoredClass가 비활성화 하고 싶은 view의 타입Dialog, Checkbox 등
• ignoredClass는 비활성화 하고 싶은 view의 타입(Dialog, Checkbox 등)

4.3 특정 엘리먼트 view의 클릭 이벤트 비활성화

• 특정 엘리먼트 view의 클릭 이벤트를 비활성화 싶은 경우, 다음 방법으로 가능합니다.

TDAnalytics.ignoreView(targetView);

• targetView는 비활성화할 View입니다.

주석을 사용한 이벤트 빠른 설정

특정 메서드 호출 횟수를 모니터링하거나, 특정 메서드 호출 후 즉시 이벤트를 전송하고 싶은 경우, @ThinkingDataTrackEvent 주석을 사용하여 빠르게 설정할 수 있습니다. 속성은 단순 이벤트에만 적용됩니다.

//use annotation
@ThinkingDataTrackEvent(eventName = "event_name", properties = "{\"paramString\":\"value\",\"paramNumber\":123,\"paramBoolean\":true}")
public void fun(){}

해당 시점에 fun이 호출되면, 다음 이벤트가 자동으로 전송됩니다.

이벤트 이름: event_name, 속성 "paramString":"value", "paramNumber":123 와 "paramBoolean":true

이벤트 이름: event_name, 속성 "paramString": "value", "paramNumber": 123, "paramBoolean": true

자동 수집 이벤트의 프리셋 속성

다음 프리셋 속성들은 자동 수집 이벤트에서 독특한 프리셋 속성입니다.

• APP 실행 이벤트(ta_app_start)의 프리셋 속성

속성 이름	이름	타입	설명
#resume_from_background	백그라운드에서 재실행 여부	문자열	APP의 실행이 직접 실행인지, 백그라운드에서 재실행인지 여부입니다. true는 백그라운드에서 재실행이고, false는 직접 실행입니다.
#start_reason	애플리케이션의 실행 이유	문자열	JSON 문자열입니다. 앱이 URL 또는 Intent를 사용하여 열릴 경우, URL의 내용과 Intent의 데이터를 자동으로 기록합니다. 예: {url:"thinkingdata://", "data":{}}
#background_duration	백그라운드 체류 시간	숫자	start 이벤트가 2회 발생한 간격 동안 앱이 백그라운드에 있던 시간, 단위: 초

- APP 종료 이벤트(ta_app_end)의 프리셋 속성

속성 이름	이름	타입	설명
#duration	이벤트 시간 경과	숫자	앱 시작부터의 시간 경과(시작부터 종료까지), 단위는 초

- APP 가시화 페이지 이벤트(ta_app_view)의 프리셋 속성

속성 이름	이름	타입	설명
#title	페이지 제목	문자열	view가 속해 있는 Activity의 제목으로, Activity의 title 속성으로 값이 부여됩니다.
#screen_name	페이지 이름	문자열	view가 속해 있는 Activity의 패키지 이름, 카테고리 이름
#url	페이지 URL	문자열	현재 페이지의 URL, getScreenUrl을 호출하여 URL 설정이 필요합니다.
#referrer	리퍼러	문자열	이 페이지로 이동하기 전의 URL로, getScreenUrl을 호출하여 설정이 필요합니다.

- APP view 클릭 이벤트(ta_app_click)의 프리셋 속성

속성 이름	이름	타입	설명
#title	페이지 제목	문자열	view가 속해 있는 Activity의 제목으로, Activity의 title 속성으로 값이 부여됩니다.
#screen_name	페이지 이름	문자열	view가 속해 있는 Activity의 패키지 이름, 카테고리 이름
#element_id	요소 ID	문자열	view의 ID, 기본적으로 android:id를 사용하며, setViewID를 호출하여 설정 가능합니다.
#element_type	요소 타입	문자열	view의 타입
#element_selector	요소 선택자	문자열	view의 viewPath의 스플라이싱
#element_position	요소 위치	문자열	view의 위치 정보, view에 position 속성이 존재할 때 전송됩니다.
#element_content	요소 내용	문자열	view 위의 내용

- AAPP 크래시 이벤트(ta_app_crash)의 프리셋 속성

속성 이름	이름	타입	설명
#app_crashed_reason	이상 정보	문자열	크래시 발생 시의 스택 트레이스가 기록됩니다.

자동 수집 기능 플러그인의 통합(선택사항)

::: 팁

view 클릭 이벤트와 Fragment 페이지 조회 이벤트가 활성화된 상태에서, 옵션 플러그인을 구현할 수 있습니다.

:::

apply plugin: 'cn.thinkingdata.android'

buildscript {
    repositories {
        google()
        jcenter()
    }
    dependencies {
        classpath 'cn.thinkingdata.android:android-gradle-plugin2:1.0.5'
    }
}

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

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

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

컴파일 로그를 열고 싶다면 debug = true로 설정하세요. (기본값은 false입니다)

특정 경로 아래에 있는 클래스를 스캔하고 싶지 않다면 exclude = ['cn.thinkingdata.android', 'android.support']를 설정하세요.

V2.1.0 이후, 민감 속성(예: AndroidID 등)을 설정하기 위한 코드 분리가 가능합니다. disableAndroidID = true로 설정하세요.

자동 수집 이벤트의 커스텀 속성 설정

enableAutoTrack(List<ThinkingAnalyticsSDK.AutoTrackEventType>, JSONObject)을 호출하여, 자동 수집 기능을 활성화하고, 커스텀 속성을 동시에 설정할 수 있습니다.

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

setAutoTrackProperties(List<ThinkingAnalyticsSDK.AutoTrackEventType>, JSONObject)을 호출하여, 설정 또는 커스텀 속성을 업데이트할 수 있습니다.

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

자동 수집 이벤트의 콜백 설정

콜백을 설정함으로써 활성화된 자동 수집 이벤트가 발생했을 때 현재 이벤트의 이벤트 타입과 이벤트 속성을 얻을 수 있으며, 응답 값을 설정함으로써 이벤트에 추가 값을 전송할 수 있습니다.

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;
        }
    }
});