설치
SDK 플러그인을 프로젝트의 Plugins 폴더에 추가하고 Unreal Engine 프로젝트에서 활성화하여 Singular Unreal Engine SDK를 설치하세요.
SDK 설치
다음 단계를 따라 Singular SDK를 Unreal Engine 프로젝트에 연동하세요.
- 위에 제공된 링크에서 SDK 아카이브를 다운로드하고 압축을 해제합니다.
- Project루트 폴더에 Plugins 폴더가 없으면 생성합니다.
- 앱의 "Plugins" 폴더 안에 "SingularSDK" 폴더를 생성합니다.
-
압축 해제한 아카이브 파일을 앱의 Plugins 폴더에 있는 "SingularSDK" 폴더로 복사합니다.
- Unreal 프로젝트가 열려 있으면 닫습니다.
- 프로젝트를 다시 엽니다. Missing Modules 프롬프트가 표시되면 Yes를 선택하여 계속합니다.
- 메뉴 "Edit>Plugins"에서 SingularSDK Plugin 을(를) 활성화합니다. Singular을(를) 검색하세요.
-
앱의 Build.cs 파일(Source/ProjectName/<YOUR_APP>.Build.cs)에서 PublicDependencyModuleNames 배열에 SingularSDK 을(를) 종속성으로 추가합니다.
PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "InputCore", "SingularSDK" });
알려진 설치 이슈
첫 빌드 시 Singular 프레임워크 헤더 파일과 관련된 치명적 오류가 발생할 수 있습니다.
알려진 이슈: 첫 빌드 시 다음과 같은 치명적 오류가 발생할 수 있습니다:
Plugins/SingularSDK/Source/SingularSDK/Private/SingularSDKBPLibrary.cpp:14:9: fatal error: 'Singular/Singular.h' file not found
이 문제를 해결하려면 다음 단계를 따르세요:
- "Plugins/SingularSDK/Source/ThirdParty/iOS"에서 Singular.framework.zip 파일의 압축을 해제합니다.
- Singular.framework 폴더를 "/Users/Shared/Epic Games/UE_5.5/Engine/Intermediate/UnzippedFrameworks/Singular"(으)로 이동합니다.
SDK 초기화
앱이 실행될 때마다 Singular SDK를 초기화하여 어트리뷰션 추적, 세션 관리 및 이벤트 보고를 활성화하세요.
SDID 정보
SDID(Singular Device ID)는 Singular가 생성하고 관리하는 기기 수준 식별자입니다. 이 SDK가 앱에서 실행되고 서버에서도 Server-to-Server(S2S) API를 통해 이벤트를 전송하는 하이브리드 연동에서, 동일한 SDID를 서버 측 이벤트에 함께 전송하면 해당 이벤트가 SDK가 추적하는 동일한 기기에 연결됩니다. 이를 통해 Singular는 플랫폼별 광고 식별자에 의존하지 않고 SDK와 S2S 활동을 하나의 기기에 어트리뷰션할 수 있습니다.
기본적으로 활성화된 SDID: 2026년 7월 15일부터 신규 Singular 고객의 경우 SDID(Singular Device ID)가 기본적으로 활성화됩니다. SDK가 초기화 중에 SDID를 자동으로 생성하고 확인하므로 추가 구성이 필요하지 않습니다. 아래 예제는 SDID 수신 콜백을 등록하여 SDK가 SDID를 수신했는지 로그에서 확인할 수 있도록 합니다.
커스텀 SDID는 엔터프라이즈 기능입니다: 커스텀 SDID 설정은 엔터프라이즈 기능이며 기본적으로 활성화되어 있지 않습니다. 계정에 이 기능이 활성화되어 있지 않다면 커스텀 SDID를 설정하지 마세요. 담당 Singular Customer Success Manager에게 문의하세요. 아래 예제는 의도적으로 커스텀 SDID를 설정하지 않습니다.
개인정보 보호 규정 준수: Singular SDK를 구현할 때는 GDPR, CCPA, COPPA 등 비즈니스를 운영하는 지역에서 제정된 개인정보 보호법을 준수해야 합니다. 자세한 내용은 SDK 옵트인 및 옵트아웃 사례를 참조하세요.
SDK를 초기화해야 하는 이유
SDK 초기화는 모든 Singular 어트리뷰션 기능의 전제 조건입니다. 사용자 리텐션 지표를 계산하기 위해 Singular로 전송되는 새 세션을생성합니다.
모범 사례: 게임 모드 생성자와 같이 앱의 라이프사이클에서 가능한 한 빨리 SDK를 초기화하세요.
초기화 방법
USingularSDKBPLibrary::초기화
Initialize 메서드를 호출하여 Singular SDK를 시작하고 사용자 세션을 Singular 서버로 전송합니다.
메서드 서명
static bool Initialize(
FString sdkKey,
FString sdkSecret,
int sessionTimeout = 60,
FString customUserId = TEXT(""),
bool skAdNetworkEnabled = true,
bool manualSkanConversionManagement = false,
int waitForTrackingAuthorizationWithTimeoutInterval = 0,
bool oaidCollection = false,
bool enableLogging = false,
int logLevel = 3,
bool clipboardAttribution = false,
FString facebookAppId = TEXT(""),
FString customSdid = TEXT("")
);
구현 예제
API 자격 증명과 구성 옵션을 사용하여 게임 모드 생성자에서 SDK를 초기화합니다.
// Copyright Epic Games, Inc. All Rights Reserved.
#include "MyProject2GameMode.h"
#include "MyProject2Character.h"
#include "UObject/ConstructorHelpers.h"
#include "SingularSDKBPLibrary.h"
#include "SingularDelegates.h"
#if PLATFORM_IOS
#include "IOS/IOSPlatformMisc.h"
#import <UIKit/UIKit.h>
#endif
AMyProject2GameMode::AMyProject2GameMode()
: Super()
{
#if PLATFORM_IOS
// Log IDFV for iOS testing
NSString *idfv = [[UIDevice currentDevice] identifierForVendor].UUIDString;
if (idfv)
{
FString IDFVString = FString(idfv);
UE_LOG(LogTemp, Log, TEXT("IDFV: %s"), *IDFVString);
}
else
{
UE_LOG(LogTemp, Warning, TEXT("Failed to retrieve IDFV"));
}
#endif
// Register the SDID accessor handler before initialization to confirm the SDK
// received the SDID (SDID is enabled by default for new accounts)
USingularDelegates* SingularDelegates = CreateDefaultSubobject<USingularDelegates>(TEXT("SingularSdidAccessorHandler"));
SingularDelegates->OnSingularSdidReceived.AddDynamic(this, &AMyProject2GameMode::OnSingularSdidReceived);
SingularDelegates->OnSingularDidSetSdid.AddDynamic(this, &AMyProject2GameMode::OnSingularDidSetSdid);
// Initialize Singular SDK
bool Success = USingularSDKBPLibrary::Initialize(
"YOUR_SDK_KEY", // API Key from Singular dashboard
"YOUR_SDK_SECRET", // Secret from Singular dashboard
60, // Session timeout in seconds
TEXT(""), // Custom user ID (optional)
true, // Enable SKAdNetwork for iOS
false, // Manual SKAdNetwork conversion management
30, // Wait 30 seconds for ATT prompt
false, // Disable OAID collection
true, // Enable logging for debugging
3, // Log level (0-5, higher = more verbose)
false, // Clipboard attribution
TEXT(""), // Facebook App ID (optional)
TEXT("") // Custom SDID (optional)
);
if (Success)
{
UE_LOG(LogTemp, Log, TEXT("Singular SDK initialized successfully"));
}
else
{
UE_LOG(LogTemp, Error, TEXT("Failed to initialize Singular SDK"));
}
// Set default pawn class
static ConstructorHelpers::FClassFinder<APawn> PlayerPawnClassFinder(
TEXT("/Game/FirstPerson/Blueprints/BP_FirstPersonCharacter")
);
DefaultPawnClass = PlayerPawnClassFinder.Class;
}
void AMyProject2GameMode::OnSingularSdidReceived(const FString result)
{
UE_LOG(LogTemp, Log, TEXT("Singular SDID received: %s"), *result);
}
void AMyProject2GameMode::OnSingularDidSetSdid(const FString result)
{
UE_LOG(LogTemp, Log, TEXT("Singular SDID set: %s"), *result);
}
게임 모드 헤더(예: AMyProject2GameMode.h)에 해당하는 핸들러 선언을 추가하세요:
UFUNCTION()
void OnSingularSdidReceived(const FString result);
UFUNCTION()
void OnSingularDidSetSdid(const FString result);
구성 파라미터
필수 파라미터
이 파라미터는 SDK 초기화에 필요합니다. Singular 대시보드에서 자격 증명을 받습니다.
- sdkKey: Singular 계정의"개발자 도구 > SDK 연동 > SDK 키"에 있는 Singular SDK 키입니다.
- sdkSecret: Singular 계정의 같은 위치에 있는 Singular SDK 시크릿
중요: SDK 자격 증명을 안전하게 보관하고 공개 버전 관리 리포지토리에 커밋하지 마세요.
선택적 매개변수
다음 선택적 구성 매개변수를 사용하여 SDK 동작을 사용자 지정하세요.
- 세션 타임아웃 (기본값: 60): 사용자 지정 세션 시간 제한을 초 단위로 설정합니다. 이 시간 동안 활동이 없으면 사용자가 앱으로 돌아오면 새 세션이 생성됩니다.
- customUserId (기본값: 비어 있음): 초기화 시 사용자 지정 사용자 식별자를 설정합니다. 사용자 지정 사용자 ID에 대해 자세히 알아보세요.
- skAdNetworkEnabled (기본값: true, iOS만 해당): iOS 어트리뷰션에 대한 SKAdNetwork 지원을 활성화합니다. Singular의 SKAdNetwork 솔루션 소개를 참조하세요.
- manualSkanConversionManagement (기본값: false, iOS만 해당): Singular가 자동으로 처리하지 않고 SKAdNetwork 전환 값을 수동으로 관리하려면 true로 설정합니다.
- waitForTrackingAuthorizationWithTimeoutInterval(기본값: 0, iOS만 해당): 사용자가 ATT(앱 추적 투명성) 프롬프트에 응답하거나 타임아웃이 경과할 때까지 세션/이벤트 전송을 Singular로 지연합니다. ATT 지원에 대해 자세히 알아보세요.
- oaidCollection (기본값: false, Android 전용): Android 디바이스에서 디바이스의 OAID(익명 디바이스 식별자)를 수집하려면 true로 설정합니다.
- enableLogging (기본값: false): 문제 해결을 위해 SDK 디버그 로깅을 활성화합니다. 프로덕션 빌드에서는 비활성화해야 합니다.
-
logLevel(기본값: 3): Android 전용입니다.
android.util.Log수준(2 Verbose ~ 7 Assert)을 사용하며 숫자가 작을수록 더 상세합니다. - clipboardAttribution (기본값: false, iOS만 해당): 유니버설 링크 어트리뷰션에 대해 클립보드에서 읽기를 활성화합니다.
- facebookAppId (기본값: 비어 있음): 페이스북 어트리뷰션 연동을 위한 페이스북 앱 ID를 설정합니다.
- customSdid (기본값: 비어 있음): 자동으로 생성된 식별자를 사용하는 대신 사용자 지정 Singular 디바이스 ID를 설정합니다.