Unreal Engine SDK: Basic Integration

Adding the SDK to Your Project

To add the Singular SDK to your project:

  1. The SDK archive you downloaded contains a SingularSDK folder that contains the SDK plugin. Copy the SingularSDK folder into your app's Plugins folder.
  2. Add SingularSDK as a dependency to the PublicDependencyModuleNames array in your app's Build.cs file (<YOUR_APP>.Build.cs):

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

Initializing the SDK

Note: Remember to remain compliant with the various privacy laws enacted in regions where doing business, including but not limited to GDPR, CCPA and COPPA when implementing the Singular SDKs. For more information, see SDK Opt-In and Opt-Out Practices.

The SDK initialization code should be called every time your app is opened. It is a prerequisite to all Singular attribution functionality and it also sends a new session to Singular that is used to calculate user retention. We recommend initializing the SDK as early as possible in your app's run.

To initialize the SDK, call the Initialize method in the SingularSDKBPLibrary class:

Initialize Method
Description Initialize the Singular SDK and send a user session to the Singular servers.
static bool Initialize(FString sdkKey, FString sdkSecret,
       int sessionTimeout = 60,
       FString customUserId = TEXT(""),
       bool skAdNetworkEnabled = false,
       bool manualSkanConversionManagement = false,
       int waitForTrackingAuthorizationWithTimeoutInterval = 0,
       bool oaidCollection = false);
Usage Example
#include "SingularSDKBPLibrary.h"
  USingularSDKBPLibrary::Initialize("SDK KEY", "SDK SECRET");

Method Parameters

Parameter Required? Description Default
sdkKey   To obtain these keys, log into your Singular account and go to "Developer Tools > SDK Integration > SDK Keys".  


  Set a custom session timeout (in seconds). 60
customUserId   Send the user ID to Singular. Learn more below  
waitForTrackingAuthorization WithTimeoutInterval   (iOS) Delay sending a session/events to Singular until the user agrees or refuses to share their device identifier data. Learn more below False
skAdNetworkEnabled   (iOS) Set to True to have Singular track the user's conversion value. See Introduction to Singular's SKAdNetwork Solution for more information. False
manualSkanConversion Management   (iOS) Set to True if you want to manage your SKAdNetwork conversion value manually (you set and update it yourself in the code). See Introduction to Singular's SKAdNetwork Solution for more information.  False
oaidCollection   (Android) Set to true to collect the device's OAID. False

Sending the User ID to Singular (Optional)

You may send your internal User ID to Singular using a Singular SDK method.

Note: If you use Singular's Cross-Device solution, you must collect the User ID across all platforms.

  • The User ID can be any identifier and should not expose PII (Personally Identifiable Information). For example, you should not use a User's email address, username, or phone number. Singular recommends using a hashed value unique only to your first-party data.
  • The User ID value passed to Singular should also be the same internal User ID you capture across all platforms (Web/Mobile/PC/Console/Offline).
  • Singular will include the User ID in user-level exports, ETL, and Internal BI postbacks (if configured). The User ID is first-party data, and Singular does not share it with other parties.
  • The User ID value, when set with the Singular SDK Method, will persist until it is unset using the UnsetCustomUserId method or until the app is uninstalled. Closing or restarting the app does not unset the User ID.

To set the User ID, use the SetCustomUserId method. To unset it (for example, if the User "logs out" of the account), call UnsetCustomUserId.

Note: If multiple Users use a single device, we recommend implementing a logout flow to set and unset the User ID for each login and logout.

If you already know the user ID when the app opens, call SetCustomUserId before initializing the Singular SDK. This way, Singular can have the User ID from the first Session. However, the User ID is typically unavailable until the User registers or performs a login. In that case, call SetCustomUserId after the registration flow is complete.

SingularSDK SetCustomUserId Method
Description Send the user ID to Singular.
Signature static void SetCustomUserId(FString customUserId)
Usage Example
SingularSDK UnsetCustomUserId Method
Description Unset the user ID that has been sent to Singular.
Signature static void UnsetCustomUserId()
Usage Example

Optional: Custom User ID Device Mapping

Important: This advanced Enterprise feature is only available in exceptional cases. Please consult with one of Singular’s Solution Engineers before implementing it.

Singular can receive additional mobile event tracking data via a server-to-server integration. To utilize this feature, you must map the User ID to Singular’s Mobile Device tracking identifier.

Note: Call this method as soon as possible after initializing the Singular SDK or once you have the User ID.

SingularSDK SetCustomUserId Method
Description Sets the Custom User Id the same as login and maps it to Singular’s tracking identifier.
Signature static void SetDeviceCustomUserId(FString customUserId)
Usage Example

Optional: Supporting iOS 14+ App Tracking Transparency

In iOS 14+, apps have to ask for user consent before sharing user data, including using the device's IDFA value (see App Tracking Transparency). Singular strongly benefits from having the IDFA to identify devices and perform install attribution. Therefore, you should ask for user consent before the Singular SDK starts sending a user session and user events to the Singular servers.

Once the SDK sends a session, it triggers Singular's install attribution process, based only on the data that is available to Singular at that point.

To delay the SDK from sending a user session and user events, initialize the Singular SDK with the waitForTrackingAuthorizationWithTimeoutInterval parameter. If you do so:

  1. The SDK will be initialized and start recording a session and user events but will not send them to the Singular server yet.
  2. As soon as App Tracking Transparency consent is granted/denied, or the set timeout elapses, the SDK will send the session and any queued events to the Singular server (with or without the IDFA).
  3. Singular will then start the attribution process, taking advantage of the IDFA if it is available.

For more information, see Preparing for iOS 14.