Installation

Install the Singular Unreal Engine SDK by adding the SDK plugin to your project's Plugins folder and enabling it in your Unreal Engine project.

Install the SDK

Follow these steps to integrate the Singular SDK into your Unreal Engine project.

1. Download and extract the SDK archive from the link provided above.
2. In the Project root folder, create a Plugins folder if it does not exist.
3. Create a folder "SingularSDK" in your app's "Plugins" folder.

4. Copy the extracted archive files into the "SingularSDK" folder in your app's Plugins folder.

   

5. Close your Unreal Project if it is currently open.
6. Reopen your Project. If prompted with a Missing Modules prompt, choose Yes to continue.
   
7. Enable the SingularSDK Plugin from the Menu: "Edit>Plugins". Search for Singular.
   

8. Add SingularSDK as a dependency to the PublicDependencyModuleNames array in your app's Build.cs file (Source/ProjectName/<YOUR_APP>.Build.cs).

   C++

   PublicDependencyModuleNames.AddRange(new string[] { 
       "Core", 
       "CoreUObject",
       "Engine", 
       "InputCore", 
       "SingularSDK" 
   });

Known Installation Issue

During the first build, you may encounter a fatal error regarding the Singular framework header file.

KNOWN ISSUE: During the first build you may experience the following fatal error:

Plugins/SingularSDK/Source/SingularSDK/Private/SingularSDKBPLibrary.cpp:14:9: fatal error: 'Singular/Singular.h' file not found

To work around this issue follow these steps:

• Extract the Singular.framework.zip file from "Plugins/SingularSDK/Source/ThirdParty/iOS"
• Move the Singular.framework folder to "/Users/Shared/Epic Games/UE_5.5/Engine/Intermediate/UnzippedFrameworks/Singular"

SDK Initialization

Initialize the Singular SDK every time your app launches to enable attribution tracking, session management, and event reporting.

About the SDID

The Singular Device ID (SDID) is a device-level identifier that Singular generates and manages. In a hybrid integration, where this SDK runs in your app and your server also sends events through the Server-to-Server (S2S) API, sending the same SDID on those server-side events ties them to the same device the SDK is tracking. This lets Singular attribute SDK and S2S activity to a single device without relying on platform-specific advertising identifiers.

Why Initialize the SDK

SDK initialization is a prerequisite to all Singular attribution functionality. It creates a new session sent to Singular for calculating user retention metrics.

Initialize Method

USingularSDKBPLibrary::Initialize

Call the Initialize method to start the Singular SDK and send a user session to Singular servers.

Method Signature

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("")
);

Implementation Example

Initialize the SDK in your game mode constructor with API credentials and configuration options.

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

Configuration Parameters

Required Parameters

These parameters are required for SDK initialization. Obtain your credentials from the Singular dashboard.

• sdkKey: Your Singular SDK Key from "Developer Tools > SDK Integration > SDK Keys" in your Singular account
• sdkSecret: Your Singular SDK Secret from the same location in your Singular account

Optional Parameters

Customize SDK behavior with these optional configuration parameters.

• sessionTimeout (Default: 60): Set a custom session timeout in seconds. After this period of inactivity, a new session is created when the user returns to the app.
• customUserId (Default: empty): Set a custom user identifier at initialization. Learn more about Custom User IDs.
• skAdNetworkEnabled (Default: true, iOS only): Enable SKAdNetwork support for iOS attribution. See Introduction to Singular's SKAdNetwork Solution.
• manualSkanConversionManagement (Default: false, iOS only): Set to true to manually manage SKAdNetwork conversion values instead of letting Singular handle them automatically.
• waitForTrackingAuthorizationWithTimeoutInterval (Default: 0, iOS only): Delay sending session/events to Singular until the user responds to the ATT (App Tracking Transparency) prompt or the timeout elapses. Learn more about ATT support.
• oaidCollection (Default: false, Android only): Set to true to collect the device's OAID (Open Anonymous Device Identifier) on Android devices.
• enableLogging (Default: false): Enable SDK debug logging for troubleshooting. Should be disabled in production builds.
• logLevel (Default: 0): Set logging verbosity level (0-5). Higher values produce more detailed logs.
• clipboardAttribution (Default: false, iOS only): Enable reading from clipboard for Universal Links attribution.
• facebookAppId (Default: empty): Set your Facebook App ID for Facebook attribution integration.
• customSdid (Default: empty): Set a custom Singular Device ID instead of using the automatically generated identifier.