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.
Signature
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 Keys.  
sdkSecret    

sessionTimeout

  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

Optional: Setting the Custom User ID

The Singular SDK can send a custom user ID from your app to Singular. This can be a username, email address, randomly generated string, or whichever identifier you use as a user ID. Singular will specify the user ID in user-level data exports as well as internal BI postbacks (if you configure any), so you'll be able to filter and group user event information by it.

  • To set the user ID to Singular when you initialize the SDK, use the customUserId parameter in the Initialize method (see example above). This ensures that Singular associates the User ID with any sessions and user events sent from the device, right from the first session.
  • To set the user ID later on in the app's run, or change a user ID that has been set before, use the SetCustomUserId method. Any sessions and user events sent from that point onward will be associated with the new custom user ID.
  • To unset the user ID, use the UnsetCustomUserId method. Any sessions and user events sent from that point onward will not be associated with any user ID.

Note: The user ID persists until you unset it by calling UnsetCustomUserId or until the app is uninstalled. Closing/restarting the app does not unset the user ID.

SingularSDK SetCustomUserId Method
Description Send the user ID to Singular.
Signature public void SetCustomUserId(FString customUserId)
Usage Example
USingularSDKBPLibrary::SetCustomUserId("custom_user_id");
SingularSDK UnsetCustomUserId Method
Description Unset the user ID that has been sent to Singular.
Signature public void UnsetCustomUserId()
Usage Example
USingularSDKBPLibrary::UnsetCustomUserId();

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.