Unity SDK: Basic Integration

Singular Unity SDK
Download
Singular Unity SDK version 2.1.0
Compatibility

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 code under the <application> tag to support getting the install referrer:

<receiver android:exported="true" android:name="com.singular.sdk.SingularInstallReceiver" android:permission="android.permission.INSTALL_PACKAGES">
    <intent-filter>      
        <action android:name="com.android.vending.INSTALL_REFERRER"></action>      
    </intent-filter>
</receiver>

Also add the following permissions:

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

Google Play Services (Mobile Ads)

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

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:

compile 'com.google.android.gms:play-services-ads:11.6.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

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 API Key and API Secret.

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 Singular.InitializeSingularSDK static method to initialize the SDK:
SingularSDK.InitializeSingularSDK Method
Description Initialize the Singular SDK if it hasn't been initialized on Awake.
Signature
public void InitializeSingularSDK()
Usage Example
// API Key and API 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.

Notes:

  • 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.
Signature
public void SetCustomUserId(string customUserId)
Usage Example
SingularSDK.SetCustomUserId("custom_user_id");
SingularSDK.UnsetCustomUserId Method  
Description Unset the user ID that has been sent to Singular in the last CustomUserId call.
Signature
public void UnsetCustomUserId()
Usage Example
SingularSDK.UnsetCustomUserId();
Integration Guides
  1. Basic Integration
  2. Tracking Events and Revenue
  3. Implementing Deep Links
  4. Adding SKAdNetwork Support
  5. Advanced Options

 

Was this article helpful?