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.

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

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

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:

public void InitializeSingularSDK()

// SDK Key and SDK Secret are set on the 
// game object associated with SingularSDK 
SingularSDK.InitializeSingularSDK();

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.

public void SetCustomUserId(string customUserId)

SingularSDK.SetCustomUserId("custom_user_id");

public void UnsetCustomUserId()

SingularSDK.UnsetCustomUserId();

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