언리얼 엔진 SDK - 기본 연동


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 서버로 전송합니다.

메서드 서명

C++
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 = 0,
    bool clipboardAttribution = false,
    FString facebookAppId = TEXT(""),
    FString customSdid = TEXT("")
);

구현 예제

API 자격 증명과 구성 옵션을 사용하여 게임 모드 생성자에서 SDK를 초기화합니다.

C++
// 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);
}

Add the matching handler declarations to your game mode header (for example, 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 (기본값: 0): 로깅 상세도 수준(0-5)을 설정합니다. 값이 높을수록 더 자세한 로그를 생성합니다.
  • clipboardAttribution (기본값: false, iOS만 해당): 유니버설 링크 어트리뷰션에 대해 클립보드에서 읽기를 활성화합니다.
  • facebookAppId (기본값: 비어 있음): 페이스북 어트리뷰션 연동을 위한 페이스북 앱 ID를 설정합니다.
  • customSdid (기본값: 비어 있음): 자동으로 생성된 식별자를 사용하는 대신 사용자 지정 Singular 디바이스 ID를 설정합니다.