menu
Is this helpful?

# Unreal

::: 팁

구현하기 전에 데이터 엑세스 준비를 확인하십시오.

TDAnalytics는 Unreal의 빌트인 Analytics 서비스를 구현하며, C++ 코드 호출 인터페이스를 통해 직접 데이터를 전송하는 것도 지원합니다. 현재 Android, iOS, Windows, 및 MacOS 플랫폼을 지원합니다.

:::

최신 버전: v2.0.1

업데이트 시간: 2023-11-24

리소스: Source Code (opens new window) SDK 다운로드 (opens new window)

# 1. SDK 구현

# 1.1 TDAnalytics 플러그인 구현

Unreal SDK를 다운로드하여 압축을 풀고, TDAnalytics을 프로젝트의 Plugins 디렉토리에 설치합니다. Plugins 디렉토리가 존재하지 않는 경우는, 먼저 프로젝트의 루트 디렉토리 아래에 Plugins 디렉토리를 만들고 나서, TDAnalytics 디렉토리를 거기에 설치합니다.

# 1.2 TDAnalytics 플러그인 활성화

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

  • Unreal Editor를 재시작
  • Edit > Plugins, Analytics 카테고리 아래에서, TDAnalytics를 활성화
  • Blueprint를 사용하는 경우, 빌트인 Analytics 카테고리에서 Analytics Blueprint Library를 활성화
  • Unreal Editor를 재시작
  • Edit > Project, 플러그인 카테고리에서 TDAnalytics의 파라미터 설정:
    • Server Url: 필수. 수신 주소로 https 타입의 주소를 사용해야 합니다.
    • App ID: 필수. 프로젝트의 APP ID는, TE 백그라운드 프로젝트 관리 페이지에서 확인할 수 있습니다.
    • TimeZone: 선택사항. 타임존을 사용하는 경우 'Asia/Shanghai', 'UTC' 등의 표준 타임존 ID를 입력해 주십시오. 타임존을 맞출 필요가 없는 경우 입력하지 않아도 됩니다.
    • Enable Encrypt: 데이터 암호화를 활성화할지 여부. 기본값은 false입니다. 활성화한 후, 데이터는 암호화되어 TE에 업로드됩니다.
    • EncryptPublicKey: 선택사항. 입력하지 않은 경우, 공개 키 암호화에 기본 설정이 사용됩니다.
    • EncryptVersion: 선택사항. 입력되지 않은 경우, 기본 구성 및 키 버전이 사용됩니다.
    • SymmetricEncryption: 선택사항. 입력되지 않은 경우, 기본 구성, 대칭 키가 사용됩니다.
    • AsymmetricEncryption: 선택사항. 입력되지 않은 경우, 기본 구성, 비대칭 키가 사용됩니다.

주의: Windows/MacOS는 시간대 조정을 지원하지 않습니다.

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

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

#include "TDAnalytics.h"

# 2. 초기 설정

다음은 SDK 초기 설정의 코드 예시입니다:

UTDAnalytics::Initialize();

초기 설정이 완료되면, SDK를 사용하여 이벤트를 전송할 수 있습니다.

# 3. 주요 기능

주요 기능을 사용하기 전에, 유저 식별 규칙을 확인하십시오.

SDK는 게스트 ID를 자동으로 생성하고, 로컬에 저장됩니다; 유저가 로그인하기 전까지, 게스트 ID를 신분 식별 ID로 사용됩니다.

주의: 게스트 ID는 유저가 앱을 재설치할 때 리셋됩니다.

# 3.1 계정 ID 설정

유저가 로그인할 때, login을 호출하여 유저의 계정 ID를 설정할 수 있습니다. TE 플랫폼은 계정 ID를 신분 식별 ID로서 logout을 호출할 때까지 유지합니다. login을 여러 번 호출하면, 이전의 계정 ID가 덮어씌워집니다.

// 유저의 고유 로그인 식별자, 데이터 추적에서 #account_id에 해당합니다. #Account_id는 현재 TE입니다.
UTDAnalytics::Login("TE");

이 방법으로는 로그인 이벤트가 전송되지 않습니다

# 3.2 공통 이벤트 속성 설정

공통 이벤트 속성은 모든 이벤트에 포함되는 속성입니다. setSuperProperties를 호출하여 설정할 수 있습니다. 이벤트를 전송하기 전에, 공통 이벤트 속성을 설정해 주세요.

예를 들어: 플레이어의 레벨, 전투력, 소유 자원 등의 속성

TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
Properties->SetStringField("channel", "TE");//문자열
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자까지 가능합니다. TE시스템은 일괄적으로 소문자로 통일됩니다.
  • Value는 해당 속성의 값으로, String, Number, Boolean, Time, Object, Array, List Object를 지원합니다.

이벤트 속성, 유저 속성은 공통 이벤트 속성과 일치해야 합니다.

# 3.3 자동 수집 이벤트의 On/Off

클라이언트 SDK는 일부 이벤트를 자동으로 수집할 수 있으며, 실제 업무 상황에 따라 on/off를 설정하십시오.

UTDAnalytics::EnableAutoTrack();

# 3.4 이벤트 전송

track을 호출하여 이벤트를 전송합니다. 데이터 플랜을 준비한 상태에서 전송해 주세요. 아래는 모델 코드입니다. 예: 아이템 구매

TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
Properties->SetStringField("product_name", "product name");
UTDAnalytics::Track("product_buy", Properties);

이벤트 이름은 문자열 타입이며, 영문자와 숫자, "_"를 포함하여 최대 50자까지 입력할 수 있습니다.

# 3.5 유저 속성 설정

일반적인 유저 속성에 대해서는, UserSet을 사용하여 설정할 수 있으며, UserSet은 기존 값에 덮어씌워집니다. 해당 속성에 값이 없는 경우, 새로운 속성이 생성됩니다. 아래는 코드 예제입니다.

//유저 이름이 현재 TA입니다
TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
Properties->SetStringField("username", "TA");
UTDAnalytics::UserSet(Properties);

//유저 이름이 현재 TE입니다
TSharedPtr<FJsonObject> NewProperties = MakeShareable(new FJsonObject);
NewProperties->SetStringField("username", "TE");
UTDAnalytics::UserSet(NewProperties);

# 4. 코드 예시 (Example Code)

아래의 코드 예시에 모든 작업이 포함되어 있으며, 아래 순서대로 사용하는 것을 권장합니다:

#include "TDAnalytics.h"
if (개인정보 처리방침이 승인되었다면) {
   
   UTDAnalytics::Initialize();
   
   //유저가 로그인한 경우, 유저의 계정 ID를 고유 식별자로 설정할 수 있습니다
   UTDAnalytics::Login("TE");
   
    //Super Properties를 설정한 후, 각 이벤트는 Super Properties를 가지게 됩니다
   TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
   Properties->SetStringField("channel", "TE");//문자열
   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);
   //자동 추적 활성화
   UTDAnalytics::EnableAutoTrack();
   //이벤트 업로드
   TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
   Properties->SetStringField("product_name", "제품 이름");
   UTDAnalytics::Track("product_buy", Properties);
   //유저 속성 설정
   TSharedPtr<FJsonObject> UserProperties = MakeShareable(new FJsonObject);
   UserProperties->SetStringField("username", "TE");
   UTDAnalytics::UserSet(Proper);
}