본문으로 건너뛰기

시스템 속성

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

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

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

속성 이름한국어 이름속성 타입수집 시점설명

#ip

IP 주소

텍스트

서버 측 수집

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

#country_code

국가 코드텍스트

서버 측 수집

유저가 있는 국가의 국가 코드(ISO 3166-1 alpha-2, 즉 영문 대문자 2자리)로, IP 주소를 기반으로 생성됩니다
#province성(Province)텍스트서버 측 수집유저가 있는 성/주로, IP 주소를 기반으로 생성됩니다
#city도시텍스트서버 측 수집유저가 있는 도시로, IP 주소를 기반으로 생성됩니다
#os_versionOS 버전텍스트초기화 시 1회 수집iOS 11.2.2, Android 8.0.0 등

#manufacturer

디바이스 제조사텍스트초기화 시 1회 수집유저 디바이스의 제조사(예: Apple, vivo 등)
#os운영 체제텍스트초기화 시 1회 수집예: Android, iOS 등
#device_id디바이스 ID텍스트초기화 시 1회 수집유저의 디바이스 ID. iOS는 유저의 IDFV 또는 UUID, Android는 androidID를 사용
#screen_height화면 높이숫자초기화 시 1회 수집유저 디바이스의 화면 높이(예: 1920 등)
#screen_width화면 너비숫자초기화 시 1회 수집유저 디바이스의 화면 너비(예: 1080 등)
#device_model디바이스 모델텍스트초기화 시 1회 수집유저 디바이스의 모델(예: iPhone 8 등)
#device_type디바이스 타입텍스트초기화 시 1회 수집디바이스 타입(예: "Tablet", "Phone")
#app_versionAPP 버전텍스트초기화 시 1회 수집APP의 버전
#bundle_id앱 고유 식별자텍스트초기화 시 1회 수집앱 패키지명 또는 프로세스명

#lib

SDK 타입텍스트

초기화 시 1회 수집

연동한 SDK의 타입(예: Android, iOS 등)
#lib_versionSDK 버전텍스트초기화 시 1회 수집연동한 SDK의 버전
#network_type네트워크 상태텍스트초기화 시 1회 수집, 네트워크 상태 변경 시 수집이벤트를 업로드할 때의 네트워크 상태(예: WIFI, 3G, 4G 등)

#carrier

네트워크 통신사텍스트

초기화 시 1회 수집

유저 디바이스의 네트워크 통신사(예: China Mobile, China Telecom 등)

#zone_offset

시간대 오프셋

숫자

이벤트 발생 시 수집

데이터 시간과 UTC 시간의 차이(시간 단위)
#install_time앱 설치 시간시간초기화 시 1회 수집유저가 앱을 설치한 시간으로, 값은 시스템에서 가져옵니다
#simulator에뮬레이터 여부불리언초기화 시 1회 수집디바이스가 에뮬레이터인지 여부 true/false

#ram

디바이스 메모리 상태

텍스트

이벤트 발생 시 수집

유저 디바이스의 현재 남은 메모리와 전체 메모리, 단위 GB, 예: 1.4/2.4(3.2.0 이상 버전에서는 기본적으로 수집하지 않음)

#disk

디바이스 저장 공간 상태텍스트이벤트 발생 시 수집

유저 디바이스의 현재 남은 저장 공간과 전체 저장 공간,

단위 GB, 예: 30/200(3.2.0 이상 버전에서는 기본적으로 수집하지 않음)

#fps

디바이스 프레임 레이트

숫자

이벤트 발생 시 수집

유저 디바이스의 현재 초당 프레임 수, 예: 60(3.2.0 이상 버전에서는 기본적으로 수집하지 않음)

#system_language

시스템 언어텍스트초기화 시 1회 수집유저 디바이스의 시스템 언어(ISO 639-1, 즉 영문 소문자 2자리), 예: zh, en 등

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

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

  • 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의 제목으로, 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예외 정보텍스트문자 타입이며 크래시 발생 시의 스택 트레이스를 기록

3. 기타 시스템 속성​

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

속성 이름한국어 이름속성 타입설명

#duration

이벤트 시간

숫자

타이머 기능 timeEvent를 호출해야 하며, 이벤트 소요 시간을 기록합니다. 단위는 초입니다

#background_duration

백그라운드 체류 시간

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

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

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

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

   //속성 객체 가져오기
   TDPresetProperties presetProperties = TDAnalytics.getPresetProperties();

   //이벤트 시스템 속성 생성
   JSONObject properties = presetProperties.toEventPresetProperties();
   /*
   {
        "#carrier": "T-Mobile",
        "#os": "Android",
        "#device_id": "dd4a508df0dbff08",
        "#screen_height": 2560,
        "#bundle_id": "cn.thinkingdata.android.demo",
        "#device_model": "sdk_gphone64_arm64",
        "#screen_width": 1440,
        "#system_language": "en",
        "#install_time": "2022-08-19 17:31:52.398",
        "#simulator": true,
        "#manufacturer": "Google",
        "#os_version": "12",
        "#app_version": "1.0",
        "#network_type": "3G",
        "#zone_offset": 8,
        "#ram": "0.8\/1.9",
        "#disk": "0.1\/0.8",
        "#fps": 60
    }
   */

    //특정 시스템 속성 가져오기
    String bundle_id = presetProperties.bundleId;//패키지명
    String os =  presetProperties.os;//os 타입(예: Android)
    String system_language = presetProperties.systemLanguage;//휴대폰 시스템 언어 타입
    int screen_width = presetProperties.screenWidth;//화면 너비
    int screen_height = presetProperties.screenHeight;//화면 높이
    String device_model = presetProperties.deviceModel;//디바이스 모델
    String device_id = presetProperties.deviceId;//디바이스 고유 식별자
    String carrier = presetProperties.carrier;//휴대폰 SIM 카드 통신사 정보(듀얼 SIM인 경우 기본 SIM의 통신사 정보를 가져옴)
    String manufacture = presetProperties.manufacture;//휴대폰 제조사(예: HuaWei)
    String network_type = presetProperties.networkType;//네트워크 타입
    String os_version = presetProperties.osVersion;//시스템 버전 번호
    String app_version = presetProperties.appVersion;//app 버전 번호
    double zone_offset = presetProperties.zoneOffset;//시간대 오프셋 값
    String ram = presetProperties.ram;//메모리 사용량
    String disk = presetProperties.disk;//디스크 사용량
    int fps = presetProperties.fps;//fps
    String installTime = presetProperties.installTime;//앱 설치 시간
    boolean isSimulator = presetProperties.isSimulator;//디바이스가 에뮬레이터인지 여부

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

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

일부 시나리오에서는 규정 준수, 실제 비즈니스 요구 등을 고려하여 특정 시스템 속성의 수집을 금지해야 할 수 있습니다. 프로젝트 디렉터리의 res/values 디렉터리에 ta_public_config.xml 파일을 추가하여 수집을 비활성화할 속성 배열을 설정할 수 있습니다.

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <!-- ThinkingAnalytics DisablePresetProperties start -->
    <string-array name="TDDisPresetProperties">
<!--        <item>#disk</item>-->
<!--        <item>#fps</item>-->
<!--        <item>#ram</item>-->
<!--        <item>#app_version</item>-->
<!--        <item>#os_version</item>-->
<!--        <item>#manufacturer</item>-->
<!--        <item>#device_model</item>-->
<!--        <item>#screen_height</item>-->
<!--        <item>#screen_width</item>-->
<!--        <item>#carrier</item>-->
<!--        <item>#device_id</item>-->
<!--        <item>#system_language</item>-->
<!--        <item>#lib</item>-->
<!--        <item>#lib_version</item>-->
<!--        <item>#os</item>-->
<!--        <item>#bundle_id</item>-->
<!--        <item>#install_time</item>-->
<!--        <item>#start_reason</item>-->
<!--        <item>#simulator</item>-->
<!--        <item>#network_type</item>-->
<!--        <item>#zone_offset</item>-->
<!--        <item>#start_reason</item>-->
<!--        <item>#resume_from_background</item>-->
<!--        <item>#title</item>-->
<!--        <item>#screen_name</item>-->
<!--        <item>#url</item>-->
<!--        <item>#referrer</item>-->
<!--        <item>#element_type</item>-->
<!--        <item>#element_id</item>-->
<!--        <item>#element_position</item>-->
<!--        <item>#element_content</item>-->
<!--        <item>#element_selector</item>-->
<!--        <item>#app_crashed_reason</item>-->
<!--        <item>#background_duration</item>-->
<!--        <item>#duration</item>-->
    </string-array>
    <!-- ThinkingAnalytics DisablePresetProperties end -->
</resources>

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

Android ID 속성은 코드 수준의 완전한 격리를 지원합니다. 즉, 격리 후에는 앱에 해당 속성을 가져오는 관련 코드가 더 이상 포함되지 않습니다. 자세한 내용은 자동 수집 플러그인 설정 섹션을 참고하십시오

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