설치

프로젝트의 플러그인 폴더에 SDK 플러그인을 추가하고 언리얼 엔진 프로젝트에서 활성화하여 Singular 언리얼 엔진 SDK를 설치합니다.

SDK 설치

언리얼 엔진 프로젝트에 Singular SDK를 연동하려면 다음 단계를 따르세요.

위에 제공된 링크에서 SDK 아카이브를 다운로드하고 압축을 풉니다.
Project 루트 폴더에 Plugins 폴더가 없는 경우 생성합니다.
앱의 "Plugins" 폴더에 "SingularSDK" 폴더를 생성합니다.
압축을 푼 아카이브 파일을 앱의 Plugins폴더에 있는 "SingularSDK"" 폴더에 복사합니다.
현재 열려 있는 경우 언리얼 프로젝트를 닫습니다.
프로젝트를 다시 엽니다. 누락된 모듈 메시지가 표시되면 예를 선택하여 계속합니다.
메뉴에서 SingularSDK Plugin 을 활성화합니다: "Edit>Plugins". Singular를 검색합니다.
앱의 Build.cs 파일(Source/ProjectName/<YOUR_APP>.Build.cs)에서 PublicDependencyModuleNames배열에 종속성으로 SingularSDK 을 추가합니다.
C++
```
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를 초기화하여 어트리뷰션 추적, 세션 관리 및 이벤트 보고를 활성화하세요.

개인정보 보호 규정 준수: 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 = 0,
    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"

#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

    // 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;
}

구성 파라미터

필수 파라미터

이 파라미터는 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를 설정합니다.

언리얼 엔진 SDK - 기본 연동

설치

SDK 설치

알려진 설치 문제

SDK 초기화

SDK를 초기화해야 하는 이유

초기화 방법

USingularSDKBPLibrary::초기화

메서드 서명

구현 예제

구성 파라미터

필수 파라미터

선택적 매개변수