# iOS SDK 자동 수집 가이드
# 자동 수집 소개
TE 시스템에서 자동으로 수집할 수 있는 호출은 다음과 같습니다. 실제 업무에 맞게 사용해 주세요.
- 설치 이벤트(Install):앱의 설치 행동을 기록
- 실행 이벤트(Open APP):앱을 실행하거나 백그라운드에서 앱을 실행
- 종료 이벤트(Close APP):앱을 종료하거나 앱이 백그라운드로 이동. 동시에 실행한 시간의 경과도 수집
- 페이지 조회 이벤트(View Page):앱 내에서 페이지 뷰(Activity)를 조회
- 클릭 이벤트(Click):앱 내의 컨트롤러(view)를 클릭
- 크래시 이벤트(Crash):앱이 크래시됐을 때의 정보 수집
각 데이터 수집 메소드에 대해 소개합니다.
# 자동 수집 활성화
enableAutoTrack
를 호출하여 자동 수집 기능을 활성화할 수 있습니다:
[TDAnalytics enableAutoTrack:
ThinkingAnalyticsEventTypeAppStart | // 앱 실행 이벤트
ThinkingAnalyticsEventTypeAppInstall | // 앱 설치 이벤트
ThinkingAnalyticsEventTypeAppEnd | // 앱 종료 이벤트
ThinkingAnalyticsEventTypeAppViewScreen | // 앱 페이지 조회 이벤트
ThinkingAnalyticsEventTypeAppClick | // 앱 클릭 이벤트
ThinkingAnalyticsEventTypeAppViewCrash]; // 앱 크래시 이벤트
# 상세 소개
# 3.1 설치 이벤트(Install)
앱의 설치 이벤트를 기록하고, 앱이 실행될 때 전송됩니다. 이벤트의 트리거 시간은 앱 설치 후 첫 실행 시간입니다. 앱의 버전업은 설치 이벤트로 계산되지 않지만, 삭제 후 재설치는 계산됩니다.
- 이벤트 이름:ta_app_install
# 3.2 실행 이벤트(Open APP)
유저가 앱을 실행할 때, 또는 백그라운드에서 앱을 실행할 때 수집됩니다.
- 이벤트 이름: ta_app_start
- 프리셋 속성:
#resume_from_background
, Boolean 타입으로, 앱이 직접 실행되었는지, 백그라운드에서 실행되었는지를 기록합니다. true는 백그라운드에서의 실행, false는 직접 실행입니다.
# 3.3 종료 이벤트(Close APP)
유저가 앱을 종료하거나, 앱을 백그라운드로 이동할 때 수집됩니다.
- 이벤트 이름: ta_app_end
- 프리셋 속성:
#duration
, 숫자 타입으로, 앱 실행의 경과 시간을 통계합니다.(단위: 초)
# 3.4 페이지 조회 이벤트(View Page)
앱에서 페이지 조회(View Controller)를 할 때 수집됩니다.
- 이벤트 이름:ta_app_view
- 프리셋 속성:
#screen_name
, 문자열 타입, View Controller의 패키지명과 카테고리명
#title
, 문자열 타입, View Controller의 타이틀, controller.navigationItem.title 속성값을 획득
페이지 조회 이벤트에서는 다른 속성을 확장하여 분석 가치를 높일 수 있습니다. 다음은 확장 방법입니다.
# 3.4.1 페이지 뷰 이벤트의 속성을 커스텀
UIViewController
를 상속받은 View Controller에 대해, Protocol getTrackProperties:
의 반환값을 View Controller의 앱 페이지 조회 이벤트에 추가합니다; 반면에 getScreenUrl:
의 반환값은 해당 페이지의 URL Schema로, 해당 페이지 조회 이벤트가 트리거될 때 프리셋 속성에 #url을 추가하고, 이 값은 해당 페이지의 URL Schema입니다. 동시에 SDK가 그 전 페이지의 URL Schema를 획득하여 프리셋 속성 #referrer
에 기록합니다.
@interface MYController : UITableViewController<TDScreenAutoTracker>
@end
@implementation MYController
- (NSDictionary *)getTrackProperties {
return @{@"PageName" : @"ABCD", @"ProductId" : @12345};
}
- (NSString *)getScreenUrl {
return @"APP://test";
/** 다중 인스턴스, appid로 구성
* - (NSDictionary *)getTrackPropertiesWithAppid{
* return @{@"appid1" : @{@"testTrackProperties" : @"ABCD"},
* @"appid2" : @{@"testTrackProperties2" : @"ABCD"},
* };
* }
* -(NSDictionary *)getScreenUrlWithAppid {
* return @{@"appid1" : @"APP://test1",
* @"appid2" : @"APP://test2",
* };
* }
*/
}
@end
- 프리셋 속성:
#url
, 문자열로, 방문 페이지의 URL
#referrer
, 문자열로, 해당 페이지로 들어오기 전 페이지의 URL
# 3.5 클릭 이벤트(Click)
앱의 클릭 이벤트는 컨트롤러를 클릭할 때 수집됩니다.
- 이벤트 이름:ta_app_click
- 프리셋 속성:
#screen_name
문자열 타입, view가 속한 View Controller의 카테고리 명
#element_content
문자열 타입, view의 내용
#element_type
문자열 타입, view의 타입
#element_position
문자열 타입, view의 타입이 UITableView 또는 UICollectionView일 때 존재하며, view가 클릭된 위치 정보를 나타냅니다. (Section):(Row)
페이지 상의 View의 클릭 이벤트에 대해, 다양한 방법으로 다른 속성을 설정하여 분석 가치를 높일 수 있습니다.
# 3.5.1 View의 엘리먼트 ID 설정
페이지 상의 엘리먼트(View)마다 엘리먼트 ID를 설정할 수 있습니다.
self.table1.thinkingAnalyticsViewID = @"testtable1";
// 다중 인스턴스, appid로 설정
// self.table1.thinkingAnalyticsViewIDWithAppid = @{ @"app1" : @"testtableID2",
@"app2" : @"testtableID3" };
그때, table1의 클릭 이벤트에 #element_id
의 프리셋 속성이 기록됩니다.
#element_id
는 문자열 타입으로, 엘리먼트의 커스텀 ID를 나타냅니다.
# 3.5.2 view 클릭 이벤트의 속성 커스텀
대부분의 view는 thinkingAnalyticsViewProperties
를 이용해 커스텀 속성을 설정할 수 있습니다:
self.table1.thinkingAnalyticsViewProperties = @{@"key1":@"value1"};
// 다중 인스턴스, appid로 설정
// self.table1.thinkingAnalyticsViewPropertiesWithAppid = @{@"app1":@{@"tablekey":@"tablevalue"},
@"app2":@{@"tablekey2":@"tablevalue2"}
};
# 3.5.3 UITableView와 UICollectionView 클릭 이벤트의 속성
UITableView
와 UICollectionView
에 대해서는 Protocol
- View Controller의 카테고리 내에서 Protocol
을 구현합니다. - 카테고리 내에서 대리자를 설정합니다.
viewDidLoad
를 이용한 설정을 권장합니다.
self.table1.thinkingAnalyticsDelegate = self;
- table1은 커스텀 속성의 View로 변경할 수 있습니다.
- 그 후에는 View Controller의 타입으로 실현할 수 있습니다.
UITableView
에서의 실현 방법입니다.
// 모든 APPID 인스턴스를 설정하고 UITableView의 커스텀 속성을 설정합니다.
-(NSDictionary *) thinkingAnalytics_tableView:(UITableView *)tableView autoTrackPropertiesAtIndexPath:(NSIndexPath *)indexPath
{
return @{@"testProperty":@"test"};
}
/** 실예, appid로 구성
* -(NSDictionary *) thinkingAnalyticsWithAppid_tableView:(UITableView *)tableView autoTrackPropertiesAtIndexPath:(NSIndexPath *)indexPath {
* return @{@"app1":@{@"autoPro":@"tablevalue"},
* @"app2":@{@"autoPro2":@"tablevalue2"}
* };
* }
*/
UICollectionView
에서의 실현 방법입니다.
// 모든 APPID 인스턴스를 설정하고 UICollectionView의 커스텀 속성을 설정합니다.
-(NSDictionary *) thinkingAnalytics_collectionView:(UICollectionView *)collectionView autoTrackPropertiesAtIndexPath:(NSIndexPath *)indexPath;
{
return @{@"testProperty":@"test"};
}
/** 실예, appid로 구성
* - (NSDictionary *)thinkingAnalyticsWithAppid_collectionView:(UICollectionView *)collectionView autoTrackPropertiesAtIndexPath:(NSIndexPath *)indexPath {
* return @{@"app1":@{@"autoProCOLL":@"tablevalueCOLL"},
* @"app2":@{@"autoProCOLL2":@"tablevalueCOLL2"}
* };
* }
*/
- 마지막으로, 카테고리 내에서
viewWillDisappear
의thinkingAnalyticsDelegate
를 nil로 설정합니다.
-(void)viewWillDisappear:(BOOL)animated
{
[super viewWillDisappear:animated];
self.table1.thinkingAnalyticsDelegate = nil;
}
- table1은 커스텀 속성의 View로 변경 가능하며, 대리 설정 시 함께 설정해주세요.
# 3.6 크래시 이벤트(Crash)
앱에 예상치 못한 오류가 발생할 때, 크래시 이벤트가 수집됩니다.
- 이벤트 이름:ta_app_crash
- 프리셋 속성:
#app_crashed_reason
문자열 타입으로, 크래시 발생 시의 스택 트레이스가 기록됩니다.
# 자동 수집 이벤트 무시
다음 방법으로 특정 페이지나 view의 자동 수집 이벤트를 무시할 수 있습니다.
# 4.1 페이지의 자동 수집 이벤트 무시
특정 페이지의 View Controller 자동 수집 이벤트를 수집하고 싶지 않은 경우(페이지 방문 및 view 클릭) 다음 방법으로 가능합니다.
NSMutableArray *array = [[NSMutableArray alloc] init];
[array addObject:@"IgnoredViewController"];
// 특정 화면 무시
[[ThinkingAnalyticsSDK sharedInstanceWithAppid:APP_ID] ignoreAutoTrackViewControllers:array];
# 4.2 특정 타입 view의 클릭 이벤트 무시
특정 타입 view의 클릭 이벤트를 무시하고 싶다면, 아래의 방법으로 실현 가능합니다.
[TDAnalytics ignoreViewType:[IgnoredClass class]];
ignoredClass
가 무시하고 싶은 view의 타입Dialog
,Checkbox
등
# 4.3 특정 요소 view의 클릭 이벤트를 무시
특정 요소 뷰의 클릭 이벤트를 무시하고 싶다면, 다음 방법으로 실현 가능합니다.
self.table1.thinkingAnalyticsIgnoreView = YES;
// 실예, appid로 구성
// self.table2.thinkingAnalyticsIgnoreViewWithAppid = @{@"appid1" : @YES,@"appid2" : @NO};
table1
는 무시하고 싶은 View를 교체할 수 있습니다.
# 자동 수집 이벤트의 프리셋 속성
다음 프리셋 속성은 자동 수집 이벤트에서 특유의 프리셋 속성입니다.
- 앱 시작 이벤트(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 | 이상 정보 | 문자열 | 크래시 발생 시의 스택 트레이스가 기록됩니다. |
# 자동 수집 이벤트에서 커스텀 속성 설정
enableAutoTrack:properties:
를 사용하여 자동 수집 이벤트 기능을 활성화할 수 있으며, 동시에 커스텀 속성 설정을 진행할 수 있습니다.
[TDAnalytics enableAutoTrack:TDAutoTrackEventTypeAll properties:@{@"auto_key1": @"auto_value1"}];
setAutoTrackProperties:properties:
를 이용해 커스텀 속성의 설정 또는 업데이트를 할 수 있습니다.
[TDAnalytics setAutoTrackProperties:TDAutoTrackEventTypeAll properties:@{@"auto_key2": @"auto_value2"}];
# 자동 수집 이벤트의 콜백 설정
v2.7.4 이후로는 자동 수집 이벤트의 콜백 기능이 지원되기 시작했습니다. enableAutoTrack:callback:
을 사용하여 자동 수집을 활성화하고, 콜백 안에서 속성의 추가와 업데이트를 진행할 수 있습니다.
[TDAnalytics enableAutoTrack:TDAutoTrackEventTypeAll callback:^NSDictionary * _Nonnull(TDAutoTrackEventType eventType, NSDictionary * _Nonnull properties) {
if (eventType == TDAutoTrackEventTypeAppStart) {
return @{@"addkey":@"addvalue"};
}
if (eventType == TDAutoTrackEventTypeAppEnd) {
return @{@"updatekey":@"updatevalue"};
}
return @{};
}];
데이터 저장에 영향을 주지 않도록 콜백에서 시간이 많이 소요되는 작업을 설정하지 말아야 합니다.