본문으로 건너뛰기

시스템 속성

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

1. 모든 이벤트에 포함되는 시스템 속성​

다음 시스템 속성은 iOS SDK의 모든 이벤트(자동 수집 이벤트 포함)에 포함되는 시스템 속성입니다

속성 이름한국어 이름속성 타입수집 시점설명
#ipIP 주소텍스트

서버 측 수집

유저의 IP 주소로, AE는 이를 기반으로 유저의 지리적 위치 정보를 가져옵니다
#country국가텍스트서버 측 수집유저가 있는 국가로, IP 주소를 기반으로 생성됩니다
#country_code국가 코드

텍스트

서버 측 수집

유저가 있는 국가의 국가 코드(ISO 3166-1 alpha-2, 즉 영문 대문자 2자리)로, IP 주소를 기반으로 생성됩니다
#province성(Province)텍스트서버 측 수집유저가 있는 성/주로, IP 주소를 기반으로 생성됩니다
#city도시텍스트서버 측 수집유저가 있는 도시로, IP 주소를 기반으로 생성됩니다
#os_versionOS 버전텍스트초기화 시 1회 수집OS 버전 번호 표시(예: 15.6.1)
#manufacturer디바이스 제조사텍스트초기화 시 1회 수집유저 디바이스의 제조사(예: Apple)
#os운영 체제텍스트초기화 시 1회 수집예: iOS 등

#device_id

디바이스 ID

텍스트초기화 시 1회 수집유저의 디바이스 ID로, iOS에서는 유저의 IDFV 또는 UUID를 사용합니다
#device_type디바이스 타입텍스트초기화 시 1회 수집디바이스 타입(예: iPhone, iPad)
#screen_height화면 높이숫자초기화 시 1회 수집유저 디바이스의 화면 높이(예: 667 등)
#screen_width화면 너비숫자초기화 시 1회 수집유저 디바이스의 화면 너비(예: 375 등)
#device_model디바이스 모델텍스트초기화 시 1회 수집유저 디바이스의 모델(예: iPhone12,8 등)
#app_versionAPP 버전텍스트초기화 시 1회 수집APP의 버전
#bundle_id앱 고유 식별자텍스트초기화 시 1회 수집앱 패키지 이름

#lib

SDK 타입

텍스트

이벤트 발생 시 수집

연동한 SDK의 타입(예: Android, iOS 등)
#lib_versionSDK 버전텍스트이벤트 발생 시 수집연동한 SDK의 버전

#network_type

네트워크 상태텍스트초기화 시 1회 수집, 네트워크 상태 변경 시 수집이벤트를 업로드할 때의 네트워크 상태(예: WIFI, 3G, 4G 등)

#carrier

네트워크 통신사텍스트

초기화 시 1회 수집

유저 디바이스의 네트워크 통신사(예: China Mobile, China Telecom 등). iOS 16.4 이후 시스템 버전에서는 이 필드를 수집하지 않습니다

#zone_offset

시간대 오프셋

숫자이벤트 발생 시 수집데이터 시간과 UTC 시간의 차이(시간 단위)

#install_time

앱 설치 시간

시간

초기화 시 1회 수집

유저가 앱을 설치한 시간으로, 값은 시스템에서 가져옵니다

#simulator에뮬레이터 여부불리언초기화 시 1회 수집디바이스가 에뮬레이터인지 여부 true/false

#ram

디바이스 메모리 상태

텍스트

이벤트 발생 시 수집

유저 디바이스의 현재 남은 메모리와 전체 메모리, 단위 GB, 예: 1.4/2.4

#disk

디바이스 저장 공간 상태텍스트이벤트 발생 시 수집유저 디바이스의 현재 남은 저장 공간과 전체 저장 공간, 단위 GB, 예: 30/200

#fps

디바이스 FPS

숫자

이벤트 발생 시 수집

유저 디바이스의 현재 초당 프레임 수, 예: 60. (v3.2.0 이후 버전의 SDK는 기본적으로 이 필드를 수집하지 않음)

#system_language

시스템 언어텍스트이벤트 발생 시 수집유저 디바이스의 시스템 언어(ISO 639-1, 즉 영문 소문자 2자리), 예: zh, en 등
#relaunched_in_background앱 백그라운드 여부불리언이벤트 발생 시 수집

APP이 백그라운드에서 시작되면 수집된 이벤트에서 이 속성은 YES입니다.

APP이 정상적으로 시작되면 수집된 이벤트에 이 속성이 포함되지 않습니다.

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

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

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

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

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

#start_reason

앱 시작 출처

텍스트APP 시작 사유를 나타내며, 내용은 JSON 문자열입니다. 현재 deeplink, 푸시, 3dtouch 시작 사유 수집을 지원합니다. 데이터 예시: {url:"thinkingdata://","data":{}}

#background_duration

백그라운드 체류 시간

숫자

두 번의 start 이벤트가 발생한 구간 동안 앱이 백그라운드에 머문 시간으로, 단위는 초입니다
  • APP 종료 이벤트(ta_app_end)의 시스템 속성
속성 이름한국어 이름속성 타입설명
#duration이벤트 시간숫자이번 APP 방문(시작부터 종료까지)의 시간을 나타내며, 단위는 초입니다
  • APP 페이지 조회 이벤트(ta_app_view)의 시스템 속성
속성 이름한국어 이름속성 타입설명

#title

페이지 제목

텍스트View Controller의 제목으로, controller.navigationItem.title 속성 값을 사용합니다
#screen_name페이지 이름텍스트View Controller의 클래스 이름

#url

페이지 주소

텍스트현재 페이지의 주소이며, getScreenUrl을 호출하여 url을 설정해야 합니다

#referrer

이전 주소

텍스트이동 전 페이지의 주소이며, 이동 전 페이지에서 getScreenUrl을 호출하여 url을 설정해야 합니다
  • APP 컨트롤 클릭 이벤트(ta_app_click)의 시스템 속성
속성 이름한국어 이름속성 타입설명
#title페이지 제목

텍스트

View Controller의 제목으로, controller.navigationItem.title 속성 값을 사용합니다
#screen_name페이지 이름텍스트View Controller의 클래스 이름

#element_id

요소 ID

텍스트컨트롤의 ID로, thinkingAnalyticsViewID로 설정해야 합니다
#element_type요소 유형텍스트컨트롤의 유형
#element_selector요소 선택자텍스트컨트롤의 viewPath를 이어 붙인 값

#element_position

요소 위치컨트롤의 위치 정보로, 컨트롤 타입이 UITableView 또는 UICollectionView인 경우에만 존재하며 컨트롤이 클릭된 위치를 나타냅니다. 값은 그룹 번호(Section):행 번호(Row)입니다
#element_content요소 내용텍스트컨트롤의 내용
  • APP 크래시 이벤트(ta_app_crash)의 시스템 속성
속성 이름표시 이름속성 타입설명
#app_crashed_reason예외 정보텍스트문자 타입이며 크래시 발생 시의 스택 트레이스를 기록

3. 기타 시스템 속성​

위에서 언급한 시스템 속성 외에도 일부 시스템 속성은 해당 인터페이스를 호출해야 기록됩니다.

속성 이름표시 이름속성 타입설명

#duration

이벤트 지속 시간

숫자타이머 기능 인터페이스 timeEvent를 호출해야 하며, 이벤트 소요 시간을 기록합니다. 단위는 초입니다
#background_duration

백그라운드 체류 시간

숫자타이머 기능 인터페이스 timeEvent를 호출해야 하며, 이벤트 발생 구간 동안 앱이 백그라운드에 머문 시간을 기록합니다. 단위는 초입니다

4. 시스템 속성 가져오기​

v2.7.0 이상 버전에서는 getPresetProperties 메서드를 호출하여 시스템 속성을 가져올 수 있습니다.

서버 측 트래킹에 App 측의 일부 시스템 속성이 필요한 경우 이 메서드로 App 측의 시스템 속성을 가져와 서버 측에 전달할 수 있습니다.

//속성 객체 가져오기
TDPresetProperties *presetProperties = [TDAnalytics getPresetProperties];

//이벤트 시스템 속성 생성
NSDictionary *properties = [presetProperties toEventPresetProperties];
/*
   {
        "#carrier": "中国电信",
        "#os": "iOS",
        "#device_id": "A8B1C00B-A6AC-4856-8538-0FBC642C1BAD",
        "#screen_height": 2264,
        "#bundle_id": "com.sw.thinkingdatademo",
        "#manufacturer": "Apple",
        "#device_model": "iPhone7",
        "#screen_width": 1080,
        "#system_language": "zh",
        "#os_version": "10",
        "#network_type": "WIFI",
        "#zone_offset": 8,
    }
*/

//특정 시스템 속성 가져오기
NSString *bundle_id = presetProperties.bundle_id;//패키지명
NSString *os = presetProperties.os;//OS 타입(예: iOS)
NSString *system_language = presetProperties.system_language;//휴대폰 시스템 언어 타입
NSNumber *screen_width = presetProperties.screen_width;//화면 너비
NSNumber *screen_height = presetProperties.screen_height;//화면 높이
NSString *device_model = presetProperties.device_model;//디바이스 모델
NSString *device_id = presetProperties.device_id;//디바이스 고유 식별자
NSString *carrier = presetProperties.carrier;//휴대폰 SIM 카드 통신사 정보. 듀얼 SIM 듀얼 스탠바이인 경우 기본 SIM의 통신사 정보를 가져옴
NSString *manufacture = presetProperties.manufacturer;//휴대폰 제조사(예: Apple)
NSString *network_type = presetProperties.network_type;//네트워크 타입
NSString *os_version = presetProperties.os_version;//시스템 버전 번호
NSNumber *zone_offset = presetProperties.zone_offset;//시간대 오프셋

IP, 국가, 도시 정보는 서버 측에서 해석하여 생성하며, 클라이언트에서는 이러한 속성을 가져오는 인터페이스를 제공하지 않습니다

5. 시스템 속성 수집 비활성화​

일부 시나리오에서는 규정 준수, 실제 비즈니스 요구 등을 고려하여 특정 시스템 속성의 수집을 금지해야 할 수 있습니다. 프로젝트의 info.plist 파일에 TDDisPresetProperties 필드(타입은 Array)를 추가하면, 추가한 필드에 해당하는 시스템 속성은 업로드되지 않습니다. 예를 들어 @"#fps", @"#ram", @"#disk", @"#start_reason", @"#simulator" 등의 시스템 속성을 차단하려면 아래 그림과 같이 설정합니다:

디바이스 ID 수집을 차단한 상태에서 최초 이벤트를 사용해야 하는 경우 반드시 first_check_id 속성을 입력하십시오

이 문서가 도움이 되었나요?
이 페이지의 내용