Singular Unity SDK |
|
---|---|
Download |
Singular Unity SDK version 4.0.14 (see Change Log) |
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 |
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.
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:
- Use the Eclipse aar plugin: gradle-eclipse-aar-plugin.
- Or integrate the AAR manually:
- Unzip singular_sdk-9.x.x.aar.
- Rename classes.jar to singular_sdk-9.x.x.jar (this is the main SDK jar).
- Integrate the above jar and libs/installreferrer-release.jar (this is the Google Referrer API library) into your eclipse project any way you prefer.
- 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:
- Add an object to your Main scene and call it SingularSDKObject.
- Drag and drop the SingularSDK script onto it.
- 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:
- Disable the Initialize on Awake option in the inspection pane of the SingularSDK object.
- 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. |
Signature |
|
Usage Example |
|
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 |
|
Usage Example |
|
SingularSDK.UnsetCustomUserId Method | |
---|---|
Description | Unset the user ID that has been sent to Singular in the last CustomUserId call. |
Signature |
|
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).