본문으로 건너뛰기

자동 수집

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

1. 자동 수집 이벤트 활성화​

팁

Harmony 플랫폼에서는 이 기능이 일시적으로 비활성화되어 있습니다

EnableAutoTrack을 호출하고 TDAutoTrackEventType을 전달하여 지정한 이벤트의 자동 수집 기능을 활성화할 수 있습니다.

public enum TDAutoTrackEventType
{
    None = 0,
    AppStart = 1 << 0,
    AppEnd = 1 << 1,
    AppCrash = 1 << 4,
    AppInstall = 1 << 5,
    AppSceneLoad = 1 << 6,
    AppSceneUnload = 1 << 7,
    All = AppStart | AppEnd | AppInstall | AppCrash | AppSceneLoad | AppSceneUnload
}

자동 수집 이벤트에 대한 설명은 다음과 같습니다:

  • AppStart: 게임이 포그라운드로 전환될 때 ta_app_start가 트리거되어 전송됩니다. 시스템 속성 #resume_from_background는 이번 시작이 재시작인지 여부를 나타냅니다.
팁

참고: 위챗 미니 게임의 AppStart 이벤트는 show 이벤트로 바뀌며, 이벤트 이름은 ta_mg_show이고 start_reason 속성이 추가됩니다

  • AppEnd: 게임이 백그라운드로 전환될 때 ta_app_end가 트리거되어 전송됩니다. 시스템 속성 #duration 필드는 이번에 게임이 포그라운드에 머문 시간을 나타내며, 단위는 초입니다.
팁

참고: 위챗 미니 게임의 AppEnd 이벤트는 hide 이벤트로 바뀌며, 이벤트 이름은 ta_mg_hide입니다

  • AppCrash: 처리되지 않은 예외가 발생하면 ta_app_crash가 트리거되어 전송됩니다. 현재 Android 플랫폼에서는 가상 머신의 처리되지 않은 예외를 처리하고, iOS 플랫폼에서는 Unix 시그널 예외와 NSException 예외를 처리합니다.
  • AppInstall: 앱을 처음 설치한 후 열 때 ta_app_install이 트리거되어 전송됩니다. 삭제 후 재설치 여부는 구분하지 않습니다. 이 이벤트는 설치 후 한 번만 전송되며, 이후 업데이트 시에는 다시 전송되지 않습니다.
팁

참고: 위챗 미니 게임의 AppInstall 이벤트는 launch 이벤트로 바뀌며, 이벤트 이름은 ta_mg_launch이고 start_reason 속성이 추가됩니다

  • AppSceneLoad: 게임 씬(Scene)이 로드될 때 ta_scene_loaded가 트리거되어 전송됩니다
  • AppSceneUnload: 게임 씬(Scene)이 언로드될 때 ta_scene_unloaded가 트리거되어 전송됩니다

TDAutoTrackEventType.All을 전달하여 현재 지원하는 모든 자동 수집 이벤트를 활성화할 수 있으며, 프로젝트 요구에 따라 일부 자동 수집 이벤트만 활성화할 수도 있습니다.

// 모든 자동 수집 이벤트 활성화
TDAnalytics.EnableAutoTrack(TDAutoTrackEventType.All);

// 시작 및 종료 이벤트 자동 수집 활성화
TDAnalytics.EnableAutoTrack(TDAutoTrackEventType.AppStart | TDAutoTrackEventType.AppEnd);

주의: 커스텀 게스트 ID 또는 공통 이벤트 속성을 설정해야 하는 경우 자동 수집 이벤트를 활성화하기 전에 완료해야 합니다. 자동 수집 이벤트는 현재 동적 공통 속성을 지원하지 않습니다.

AppCrash와 관련하여 iOS와 Android 플랫폼에서 Objective-C와 Java 예외만 수집하고 C# 예외는 수집하지 않으려면, v2.3.1 이상 버전에서 Resources 디렉터리에 ta_public_config.xml을 추가하여 스위치를 설정할 수 있습니다. 예시는 다음과 같습니다:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <!-- ThinkingAnalytics disable C# Exception -->
    <bool name="DisableCSharpException">true</bool>
</resources>

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

v2.2.4부터 EnableAutoTrack을 호출하여 자동 수집을 활성화하면서 수집할 커스텀 속성을 함께 전달할 수 있습니다.

// 자동 수집 이벤트를 활성화하고 커스텀 속성 설정
TDAnalytics.EnableAutoTrack(TDAutoTrackEventType.All, new Dictionary<string, object>() {
    {"custom_key", "custom_value"}
});

SetAutoTrackProperties를 호출하여 특정 자동 수집 이벤트의 커스텀 속성을 지정할 수도 있습니다.

주의: SetAutoTrackProperties는 자동 수집 이벤트의 수집을 활성화하지 않으므로 EnableAutoTrack 메서드와 함께 사용해야 합니다.

// 단일 자동 수집 이벤트의 커스텀 속성 설정
TDAnalytics.SetAutoTrackProperties(TDAutoTrackEventType.AppStart, new Dictionary<string, object>() 
{
    {"start_key", "start_value"}
});

// 여러 자동 수집 이벤트의 커스텀 속성 설정
TDAnalytics.SetAutoTrackProperties(TDAutoTrackEventType.AppInstall | TDAutoTrackEventType.AppStart, new Dictionary<string, object>() 
{
    {"install_crash_key", "install_crash_value"}
});

// 모든 자동 수집 이벤트 활성화
TDAnalytics.EnableAutoTrack(TDAutoTrackEventType.All);

3. 자동 수집 이벤트 콜백 설정​

v2.4.0부터 자동 수집 이벤트 콜백 설정을 지원하므로 커스텀 속성을 실시간으로 설정하거나 해당 이벤트의 트리거 시점에 커스텀 코드를 실행할 수 있습니다. 자동 수집 이벤트 콜백을 설정하려면 먼저 클래스를 새로 만들어 TDAutoTrackEventHandler 인터페이스를 구현하고 public Dictionary<string, object> GetAutoTrackEventProperties(int type, Dictionary<string, object>properties) 메서드를 재정의합니다. 이 메서드의 반환값이 설정할 자동 수집 이벤트 속성입니다. 그런 다음 EnableAutoTrack을 호출하여 자동 수집 이벤트 콜백 객체를 전달합니다. 예시는 다음과 같습니다:

// 1.자동 수집 이벤트 콜백 구현
public class AutoTrackECB : TDAutoTrackEventHandler
{
    public Dictionary<string, object> GetAutoTrackEventProperties(int type, Dictionary<string, object>properties)
    {
        return new Dictionary<string, object>() 
        {
            {"AutoTrackEventProperty", DateTime.Today}
        };
    }
}
// 2.자동 수집을 활성화하고 이벤트 콜백 설정
TDAnalytics.EnableAutoTrack(TDAutoTrackEventType.All, new AutoTrackECB());

4. 씬 자동 수집 이벤트 활성화​

v2.4.1부터 씬의 로드 및 언로드 이벤트 자동 수집을 지원합니다.

씬 로드, 언로드 델리게이트 이벤트를 등록하여 씬 자동 수집 이벤트를 활성화합니다.

MonoBehaviour 스크립트의 OnEnable 메서드에서 호출하는 것을 권장합니다.

    private void OnEnable()
    {
        // 씬 로드, 언로드 이벤트 수신
        SceneManager.sceneLoaded += TDAnalytics.OnSceneLoaded;
        SceneManager.sceneUnloaded += TDAnalytics.OnSceneUnloaded;
    }

v2.5.1부터 EnableAutoTrack 메서드를 호출하여 씬 자동 수집 이벤트를 활성화할 수 있습니다

// 모든 자동 수집 이벤트 활성화
TDAnalytics.EnableAutoTrack(TDAutoTrackEventType.All);

// 씬 로드 및 언로드 이벤트 자동 수집 활성화
TDAnalytics.EnableAutoTrack(TDAutoTrackEventType.AppSceneLoad | TDAutoTrackEventType.AppSceneUnload);
이 문서가 도움이 되었나요?
이 페이지의 내용