본문으로 건너뛰기

Unreal

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

연동하기 전에 먼저 연동 전 준비를 읽어 주십시오.

TDAnalytics는 Unreal Engine에 내장된 Analytics 서비스를 구현하며, C++ 코드에서 인터페이스를 직접 호출하여 데이터를 전송하는 방식도 지원합니다. 현재 Android, iOS, Windows, macOS 플랫폼을 지원하며, Unreal Engine 4.26+ 및 5.+ 버전을 지원합니다.

최신 버전: v3.0.3

업데이트 시간: 2025-10-11

리소스 다운로드: 소스 코드, SDK 다운로드

주의

이 문서는 v2.0.0 이상 버전에 적용됩니다. 과거 버전은 Unreal 연동 가이드(V1), SDK 다운로드(v1.6.0)를 참고하십시오

1. SDK 통합​

1.1 TDAnalytics 플러그인 통합​

Unreal SDK를 다운로드하고 압축을 푼 후 TDAnalytics를 프로젝트의 Plugins 디렉터리에 넣습니다. Plugins 디렉터리가 없으면 먼저 프로젝트 루트 디렉터리에 Plugins 디렉터리를 만든 다음 TDAnalytics 디렉터리를 그 안에 넣습니다.

1.2 TDAnalytics 플러그인 활성화​

TDAnalytics 플러그인을 활성화하려면 다음 단계를 진행해야 합니다:

  • Unreal Editor를 재시작합니다

  • 편집 > 플러그인을 열고 프로젝트 Analytics 카테고리에서 TDAnalytics를 활성화합니다

  • Blueprint를 사용하는 경우 내장 Analytics 카테고리에서 Analytics Blueprint Library를 활성화하십시오

  • Unreal Editor를 다시 재시작합니다

  • 편집 > 프로젝트 세팅을 열고 플러그인 카테고리에서 TDAnalytics 파라미터를 설정합니다:

    • Server Url: 필수. 수신 측 주소로, https 주소를 사용해야 합니다
    • App ID: 필수. 프로젝트의 APP ID로, AE 백엔드의 프로젝트 관리 페이지에서 확인할 수 있습니다
    • TimeZone: 선택 사항입니다. 시간대 정렬이 필요한 경우 "UTC01:00"과 같은 표준 TimeZone ID를 입력하십시오. 시간대 정렬이 필요하지 않으면 입력하지 않아도 됩니다
    • Enable Encrypt: 데이터 암호화 활성화 여부입니다. 기본값은 false이며, 활성화하면 데이터를 암호화한 후 AE로 업로드합니다
    • EncryptPublicKey: 선택 사항입니다. 암호화 공개 키이며, 입력하지 않으면 기본 설정을 사용합니다
    • EncryptVersion: 선택 사항입니다. 키 버전이며, 입력하지 않으면 기본 설정을 사용합니다
    • SymmetricEncryption: 선택 사항입니다. 대칭 키이며, 입력하지 않으면 기본 설정을 사용합니다
    • AsymmetricEncryption: 선택 사항입니다. 비대칭 키이며, 입력하지 않으면 기본 설정을 사용합니다

주의: Windows/MacOS에서는 아직 시간대 정렬을 지원하지 않습니다.

  • Config 디렉터리의 DefaultEngine.ini 파일에 다음 내용을 추가합니다:
[Analytics]
ProviderModuleName=TDAnalytics
  • C++ 코드에서 TDAnalytics 인터페이스를 직접 사용하려면 프로젝트의 *.Build.cs 파일에 다음 내용을 추가해야 합니다:
PrivateDependencyModuleNames.AddRange(new string[] { "TDAnalytics" });
PrivateIncludePathModuleNames.AddRange(new string[] { "TDAnalytics" });

또한 SDK를 사용할 파일에서 TDAnalytics.h 헤더 파일을 참조합니다:

#include "TDAnalytics.h"

2. 초기화​

다음은 SDK 초기화 예시 코드입니다.

// SDK 초기화
UTDAnalytics::Initialize();

초기화가 완료되면 SDK로 이벤트를 전송할 수 있습니다.

3. 자주 사용하는 기능​

자주 사용하는 기능을 사용하기 전에 먼저 유저 식별 규칙을 이해하는 것을 권장합니다. SDK는 기본적으로 난수를 생성하여 게스트 ID로 사용하고, 게스트 ID를 로컬에 영구 저장합니다. 유저가 로그인하기 전에는 게스트 ID가 신원 식별 ID로 사용됩니다. 참고: 게스트 ID는 유저가 앱을 재설치하거나 디바이스를 변경하면 바뀝니다.

3.1 계정 ID 설정​

유저가 로그인할 때 Login을 호출하여 유저의 계정 ID를 설정할 수 있습니다. AE 플랫폼은 계정 ID를 신원 식별 ID로 사용하며, 설정한 계정 ID는 Logout을 호출하기 전까지 계속 유지됩니다. Login을 여러 번 호출하면 이전 계정 ID를 덮어씁니다.

// 유저의 로그인 고유 식별자로, 전송 데이터의 #account_id에 해당합니다. 이때 #account_id의 값은 TA입니다
UTDAnalytics::Login("TA");

Login은 여러 번 호출할 수 있습니다. 호출할 때마다 전달된 계정 ID가 이전에 저장된 ID와 같은지 확인하여, 같으면 호출을 무시하고 다르면 이전 ID를 덮어씁니다.

이 메서드는 로그인 이벤트를 전송하지 않습니다

3.2 공통 이벤트 속성 설정​

공통 이벤트 속성은 모든 이벤트에 포함되는 속성입니다. SetSuperProperties를 호출하여 공통 이벤트 속성을 설정할 수 있으며, 이벤트를 보내기 전에 먼저 공통 이벤트 속성을 설정하는 것을 권장합니다. 유저의 회원 등급, 유입 채널 등 일부 중요한 속성은 모든 이벤트에 설정해야 하므로, 이러한 속성은 공통 이벤트 속성으로 설정할 수 있습니다.

    TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
    Properties->SetStringField("channel", "ta");//문자열
    Properties->SetNumberField("age", 1);//숫자
    Properties->SetBoolField("isSuccess", true);//불리언
    FDateTime DateTime = FDateTime::Now();
    Properties->SetStringField("birthday", FDateTime::FromUnixTimestamp(DateTime.ToUnixTimestamp()).ToString(TEXT("%Y-%m-%d %H:%M:%S.")) += *FString::Printf(TEXT("%03d"), DateTime.GetMillisecond()));//시간

    TSharedPtr<FJsonObject> ItemProperties = MakeShareable(new FJsonObject);
    ItemProperties->SetStringField("itemChannel", "item");
    Properties->SetObjectField("object", ItemProperties);//객체

    TArray< TSharedPtr<FJsonValue> > DataObjectArray;
    TSharedPtr<FJsonObject> ArrayItemProperties = MakeShareable(new FJsonObject);
    ArrayItemProperties->SetStringField("arrayItemChannel", "array_item");
    TSharedPtr<FJsonValueObject> DataObjectValue = MakeShareable(new FJsonValueObject(ArrayItemProperties));
    DataObjectArray.Add(DataObjectValue);
    Properties->SetArrayField("object_arr", DataObjectArray);//객체 그룹

    TArray< TSharedPtr<FJsonValue> > DataArray;
    TSharedPtr<FJsonValueString> DataValue = MakeShareable(new FJsonValueString("data_value"));
    DataArray.Add(DataValue);
    Properties->SetArrayField("arr", DataArray);//배열

    UTDAnalytics::SetSuperProperties(Properties, AppID);
  • Key는 해당 속성의 이름으로 문자열 타입입니다. 영문자로 시작해야 하며 숫자, 영문자, 밑줄 "_"을 포함할 수 있고, 최대 길이는 50자입니다. 대소문자를 구분하지 않으며 AE에서 모두 소문자로 변환합니다
  • Value는 해당 속성의 값으로 문자열, 숫자, 불리언, 시간, 객체, 객체 그룹, 배열을 지원합니다

이벤트 속성과 유저 속성의 요구 사항은 공통 이벤트 속성과 같습니다

3.3 자동 수집 활성화​

다음은 설치, 시작, 종료 이벤트를 활성화하는 예시 코드입니다(PC에서는 자동 수집을 지원하지 않습니다). SDK의 자동 수집 기능을 자세히 알아보려면 자동 수집 이벤트를 참고하십시오

// 자동 수집 활성화
UTDAnalytics::EnableAutoTrack();

3.4 이벤트 전송​

Track을 호출하여 이벤트를 전송할 수 있습니다. 앞서 정리한 트래킹 문서에 따라 이벤트 속성과 전송 조건을 설정하는 것을 권장합니다. 여기서는 유저가 어떤 상품을 구매하는 경우를 예로 듭니다:

TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
Properties->SetStringField("product_name", "상품명");//문자열
// 속성이 있는 이벤트 전송
UTDAnalytics::Track("product_buy", Properties);

이벤트 이름은 문자열 타입이며, 영문자로 시작해야 하고 숫자, 영문자, 밑줄 "_"을 포함할 수 있으며, 최대 길이는 50자입니다.

3.5 유저 속성 설정​

일반적인 유저 속성은 UserSet을 호출하여 설정할 수 있습니다. 이 인터페이스로 업로드한 속성은 기존 속성 값을 덮어씁니다. 이전에 해당 유저 속성이 없었다면 유저 속성을 새로 생성하며, 타입은 전달한 속성의 타입과 같습니다. 여기서는 사용자 이름 설정을 예로 듭니다.

 //이때 "username"은 "TA"입니다
TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
Properties->SetStringField("username", "TA");//문자열
UTDAnalytics::UserSet(Properties);
//이때 "username"은 "AE"입니다
TSharedPtr<FJsonObject> NewProperties = MakeShareable(new FJsonObject);
NewProperties->SetStringField("username", "AE");//문자열
UTDAnalytics::UserSet(NewProperties);

4. 모범 사례​

다음 예시 코드에는 위의 모든 작업이 포함되어 있으며, 다음 단계에 따라 사용하는 것을 권장합니다.

#include "TDAnalytics.h"
if (isPrivacyPolicyAccepted) { // 유저가 '개인정보 처리방침'에 동의함
   //SDK 초기화
   UTDAnalytics::Initialize();
   // 자동 수집 이벤트 활성화
   UTDAnalytics::EnableAutoTrack();
   //유저가 로그인한 경우 유저의 계정 ID를 고유 식별자로 설정할 수 있습니다
   UTDAnalytics::Login("TA");
   //공통 이벤트 속성 설정
   TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
   Properties->SetStringField("channel", "ta");//문자열
   Properties->SetNumberField("age", 1);//숫자
   Properties->SetBoolField("isSuccess", true);//불리언
   FDateTime DateTime = FDateTime::Now();
   Properties->SetStringField("birthday", FDateTime::FromUnixTimestamp(DateTime.ToUnixTimestamp()).ToString(TEXT("%Y-%m-%d %H:%M:%S.")) += *FString::Printf(TEXT("%03d"), DateTime.GetMillisecond()));//시간

   TSharedPtr<FJsonObject> ItemProperties = MakeShareable(new FJsonObject);
   ItemProperties->SetStringField("itemChannel", "item");
   Properties->SetObjectField("object", ItemProperties);//객체

   TArray< TSharedPtr<FJsonValue> > DataObjectArray;
   TSharedPtr<FJsonObject> ArrayItemProperties = MakeShareable(new FJsonObject);
   ArrayItemProperties->SetStringField("arrayItemChannel", "array_item");
   TSharedPtr<FJsonValueObject> DataObjectValue = MakeShareable(new FJsonValueObject(ArrayItemProperties));
   DataObjectArray.Add(DataObjectValue);
   Properties->SetArrayField("object_arr", DataObjectArray);//객체 그룹

   TArray< TSharedPtr<FJsonValue> > DataArray;
   TSharedPtr<FJsonValueString> DataValue = MakeShareable(new FJsonValueString("data_value"));
   DataArray.Add(DataValue);
   Properties->SetArrayField("arr", DataArray);//배열
   UTDAnalytics::SetSuperProperties(Properties, AppID);
   //이벤트 전송
   TSharedPtr<FJsonObject> EventProperties = MakeShareable(new FJsonObject);
   EventProperties->SetStringField("product_name", "상품명");//문자열
   UTDAnalytics::Track("product_buy", EventProperties);
   //유저 속성 설정
   TSharedPtr<FJsonObject> UserProperties = MakeShareable(new FJsonObject);
   UserProperties->SetStringField("username", "TA");//문자열
   UTDAnalytics::UserSet(UserProperties);
}
이 문서가 도움이 되었나요?
이 페이지의 내용