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

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:

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

#include "SingularSDKBPLibrary.h"
  
  [...]
  
  USingularSDKBPLibrary::Initialize("SDK KEY", "SDK SECRET");
  

Method Parameters

Sending the User ID to Singular (Optional)

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

• 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.

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.

USingularSDKBPLibrary::SetCustomUserId("custom_user_id");

USingularSDKBPLibrary::UnsetCustomUserId();

USingularSDKBPLibrary::SetDeviceCustomUserId("custom_user_id");

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.