# Android SDK 자동 수집 가이드
Android SDK는 설치, 실행, 종료 등의 이벤트를 자동으로 수집하는 기능을 지원합니다.
# 자동 수집 소개
TE 시스템에서 자동으로 수집할 수 있는 호출은 다음과 같습니다. 실제 업무에 맞게 사용하세요.
- 설치 이벤트(Install):앱의 설치 행동을 기록
- 실행 이벤트(Open APP):앱을 실행하거나 백그라운드에서 앱을 실행
- 종료 이벤트(Close APP):앱을 종료하거나 앱이 백그라운드로 이동. 동시에 실행한 시간의 경과도 수집
- 페이지 조회 이벤트(View Page):앱 내에서 페이지 뷰(Activity)를 조회
- 클릭 이벤트(Click):앱 내의 컨트롤러(view)를 클릭
- 크래시 이벤트(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회 발생한 간격 동안 앱이 백그라운드에 있던 시간, 단위: 초 |
속성 이름 | 이름 | 타입 | 설명 |
---|---|---|---|
#duration | 이벤트 시간 경과 | 숫자 | 앱 시작부터의 시간 경과(시작부터 종료까지), 단위는 초 |
속성 이름 | 이름 | 타입 | 설명 |
---|---|---|---|
#title | 페이지 제목 | 문자열 | view가 속해 있는 Activity의 제목으로, Activity의 title 속성으로 값이 부여됩니다. |
#screen_name | 페이지 이름 | 문자열 | view가 속해 있는 Activity의 패키지 이름, 카테고리 이름 |
#url | 페이지 URL | 문자열 | 현재 페이지의 URL, getScreenUrl을 호출하여 URL 설정이 필요합니다. |
#referrer | 리퍼러 | 문자열 | 이 페이지로 이동하기 전의 URL로, getScreenUrl을 호출하여 설정이 필요합니다. |
속성 이름 | 이름 | 타입 | 설명 |
---|---|---|---|
#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 위의 내용 |
속성 이름 | 이름 | 타입 | 설명 |
---|---|---|---|
#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;
}
}
});
← 프리셋 속성 및 시스템 필드 디버깅 →