Unity SDK: Basic Integration

Singular Unity SDK
Singular Unity SDK version 4.0.14 (see Change Log)

Unity 4.7.2+

Sample App Review our sample app for an example of a complete SDK integration based on best practices.
Integration Guides
  1. Basic Integration
  2. Tracking Events and Revenue
  3. Implementing Deep Links
  4. Adding SKAdNetwork Support
  5. Advanced Options


Configuring Android and iOS Prerequisites

Android Prerequisites

In your AndroidManifest.xml file, add the following permissions:

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.INTERNET" />

If you have disabled transitive dependencies for the Singular SDK, add the following to your app's build.gradle.

implementation 'com.android.installreferrer:installreferrer:2.2'
implementation 'com.google.android.gms:play-services-appset:16.0.0'

Google Play Services (Mobile Ads)

The Singular SDK requires the Google Mobile Ads API, part of the Google Play Services APIs 17.0.0+.

If you've already integrated Google Play Services into your app, the requirement is fulfilled.

If you haven't, you can integrate just Google Mobile Ads individually, by including the following dependency in your app's build.gradle file:

implementation 'com.google.android.gms:play-services-ads-identifier:17.0.0+'

For more information, see Google's guide to setting up Google Play Services.

Android Setup (Proguard and Eclipse) ▼

If you are using Proguard, add the following lines of code to your proguard-unity.txt file:

-keep class com.singular.sdk.** { *; }
-keep public class com.android.installreferrer.** { *; }
-keep public class com.singular.unitybridge.** { *; }

If you are building with Eclipse, use one of the following methods to integrate the AAR into your Eclipse project:

  1. Unzip singular_sdk-9.x.x.aar.
  2. Rename classes.jar to singular_sdk-9.x.x.jar (this is the main SDK jar).
  3. Integrate the above jar and libs/installreferrer-release.jar (this is the Google Referrer API library) into your eclipse project any way you prefer.
  4. Copy the BIND_GET_INSTALL_REFERRER_SERVICE permission from the AndroidManifest.xml contained in the AAR to your AndroidManifest.xml.

iOS Prerequisites

Link the following libraries/frameworks to your Unity XCode project:

  • Security.framework
  • SystemConfiguration.framework
  • iAD.framework
  • AdSupport.framework
  • WebKit.framework
  • libsqlite3.0.tbd
  • libz.tbd
  • StoreKit.framework
  • AdServices.framework (Must be added, but mark it as Optional since it's only available for devices with iOS 14.3 and higher).

Downloading and Importing the SDK Package

To begin, download the SDK unitypackage file.

Import the unitypackage into your app using Assets > Import Package > Custom package.

Adding the SDK Object

In the Unity platform:

  1. Add an object to your Main scene and call it SingularSDKObject.
  2. Drag and drop the SingularSDK script onto it.
  3. In the inspection pane, paste in your Singular SDK Key and SDK Secret (to retrieve them, log into your Singular account and go to Developer Tools > SDK Keys).

Setting Up the Basic Integration

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.

By default, SingularSDK.cs initializes the SDK automatically when the scene is created, through the Awake method.

Manual Initialization

If you prefer to initialize the SDK manually at a later point in the app's run, do the following:

  1. Disable the Initialize on Awake option in the inspection pane of the SingularSDK object.
  2. Use the SingularSDK.InitializeSingularSDK static method to initialize the SDK:
SingularSDK.InitializeSingularSDK Method
Description Initialize the Singular SDK if it hasn't been initialized on Awake.
public void InitializeSingularSDK()
Usage Example
// SDK Key and SDK Secret are set on the 
// game object associated with SingularSDK SingularSDK.InitializeSingularSDK();

Note on Thread Safety: The Singular Unity SDK should always be called from the same thread, the same way you call other Unity methods.

Optional: Configuring the Session Timeout

By default, if the app runs in the background for 60 seconds or more before returning to the foreground, the Singular SDK registers a new session. You can change the default timeout value by modifying the Session Timeout Sec property of your SingularSDKObject.

Optional: Setting the User ID

The Singular SDK can send a 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 use the user ID in user-level data exports as well as internal BI postbacks (if you configure any).

To send the user ID to Singular, call the SetCustomUserId method. To unset the ID (for example, If the user logs out of their account), call UnsetCustomUserId.


  • 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.
  • If you already have the user ID available when the app opens, and you want it to be available to Singular from the very first session, make sure to set it before initializing the Singular SDK.
SingularSDK.SetCustomUserId Method 
Description Send the user ID to Singular.
public void SetCustomUserId(string customUserId)
Usage Example
SingularSDK.UnsetCustomUserId Method  
Description Unset the user ID that has been sent to Singular in the last CustomUserId call.
public void UnsetCustomUserId()
Usage Example

Handling AppTrackingTransparency Consent

Starting with iOS 14.5, your app is required to ask for user consent (using the App Tracking Transparency framework) before you can access some user data, including the device's IDFA.

Singular highly benefits from having the IDFA to identify devices and perform install attribution. We strongly recommend that you try to get the IDFA for Singular if possible.

This also means you need to make the SDK wait before sending a user session to Singular. By default, the Singular SDK fires a user session when it's initialized. When a session is fired from a new device, it immediately triggers Singular's attribution process - which is performed based only on the data that is available to Singular at that point. Therefore, it's important to ask for consent and retrieve the IDFA before the Singular SDK fires a session.

To delay the firing of a user session, configure the waitForTrackingAuthorizationWithTimeoutInterval option in the SingularSDKObject. This sets the maximum time (in seconds) that the Singular SDK will wait for the user to authorize/deny AppTrackingTransparency Consent before logging events to Singular's servers. The default value for this option is 0 (no wait).