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

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.

USingularSDKBPLibrary::SetCustomUserId("custom_user_id");

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.