Unity SDK Integration Guide

 

New: Video Guide

Watch this video for a detailed view of the integration and testing process. We recommend using both the video and the written guide below.

Before You Begin: SDK Prerequisites

Follow the steps in Integrating a Singular SDK: Planning and Prerequisites.

These steps are prerequisites for any Singular SDK integration.

1. Installing the SDK

1.1. Downloading and Importing the SDK Package

  1. To begin, download the SDK unitypackage file.
  2. Import the unitypackage into your app using Assets > Import Package > Custom package.
  3. 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 Integration > SDK Keys").
    4. META Install Referrer Attribution Support

      Required SDK configuration to enable "Meta Install Referrer" attribution:

      1. Provide your Facebook App Id in the inspection pane of the SingularSDK object.
      Where can I find an app's Facebook App ID?

1.2. Configuration for Android

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

    
    <!--  This permission is needed to use internet connectivity  -->
    <uses-permission android:name="android.permission.INTERNET" />
    
    <!--  This permission is needed to check for an active internet connection  -->
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    
    <!--  This permission is needed to retrieve Google Play Referrer data  -->
    <uses-permission android:name="BIND_GET_INSTALL_REFERRER_SERVICE" />
    
    <!--  This permission is needed to validate Google Install Fraud  -->
    <uses-permission android:name="com.android.vending.CHECK_LICENSE" />
    	
  2. 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'
  3. 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 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 Configuration (Proguard and Eclipse)

Learn how to set up Android using Proguard or 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-12.x.x.aar.
  2. Rename classes.jar to singular_sdk-12.x.x.jar (this is the main SDK jar).
  3. Integrate the above jar and libs/installreferrer-release.jar (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.

1.3. Configuration for iOS

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

  • Security.framework
  • SystemConfiguration.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).

Important: The AdServices.framework is required in your App Build if you plan to utilize Apple Search Ad Campaigns and wish to track attribution.

2. Setting Up a Basic SDK Integration

2.1. Using SKAdNetwork

Starting with Unity SDK version 4.0.17, SKAdNetwork is enabled by default. It is enabled in Managed Mode (in which Singular updates the SKAN conversion value for you using a conversion model you choose in the Singular dashboard).

As long as you are using the latest version of the SDK, you do not need to set anything else or add any code to use SKAdNetwork.

Additional Information

Enabling SKAdNetwork in Older Versions of the SDK

If you are using an older version of the SDK, you need to enable SKAdNetwork in one of the following ways:

  • Go to the SingularSDKObject and set SKANEnabled to True.
  • Call SingularSDK.SkanRegisterAppForAdNetworkAttribution() in your app code.
Using SKAdNetwork in Manual Mode (Advanced)

If you choose to manage the SKAN conversion value manually using your own logic, you need to do the following:

  • Go to the SingularSDKObject and set manualSKANConversionManagement to True.
  • Use the following methods in your code to set and retrieve the conversion value.
SingularSDK.SkanUpdateConversionValue Method 
Description

Update the SKAdNetwork conversion value.

Note: Use this method if you have selected to update the SKAdNetwork conversion value manually. This method will work only if manualSKANConversionManagement is set to True.

Signature public void SkanUpdateConversionValue(int value)
Usage Example
// A sign-up event happened
Singular.Event("SignUp");

// Update the conversion value to 7
SingularSDK.SkanUpdateConversionValue(7);
SingularSDK.SkanGetConversionValue Method 
Description Get the current conversion value tracked by the Singular SDK.
Signature public int? SkanGetConversionValue()
Usage Example
int? value = SingularSDK.SkanGetConversionValue();
SingularSDK.SetConversionValueUpdatedHandler Method 
Description Set a handler to receive notifications when the conversion value is updated.
Signature public void SetConversionValueUpdatedHandler(SingularConversionValueUpdatedHandler handler)
Usage Example
public class Main : MonoBehaviour, SingularConversionValueUpdatedHandler {
  void Awake() {
    SingularSDK.SetConversionValueUpdatedHandler(this);
  }

  void OnConversionValueUpdated(int value) {
    // Use the conversion value
  }
}

Displaying an ATT (App Tracking Transparency) Prompt

Starting with iOS 14.5, apps are required to ask for user consent (using the App Tracking Transparency framework) before they can access and share some user data that is helpful for tracking purposes, including the device's IDFA.

Singular highly benefits from having the IDFA to identify devices and perform install attribution (although there are ways to perform attribution without the IDFA). We strongly recommend you ask for the user's consent to get the IDFA.

Delaying Initialization to Wait for ATT Response

By default, the Singular SDK sends a user session when it is initialized. When a session is sent from a new device, it immediately triggers Singular's attribution process - which is performed based only on the data available to Singular at that point. Therefore, asking for consent and retrieving the IDFA before the Singular SDK sends the first session is essential.

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

2.3. Handling Deep Links

Deep links are links that lead into specific content inside an app. When a user clicks a deep link on a device that has the app installed, the app opens and shows a specific product or experience.

Singular tracking links can include deep linking as well as deferred deep linking (see our Deep Linking FAQ and the Singular Links FAQ for more information).

The instructions below will show you how to:

  1. Access the tracking link that led to your app being opened,
  2. Read the deep link destination, and
  3. Show the appropriate content.

Notes:

Setting Up Deep Linking Prerequisites

  1. Prerequisites for iOS and Android: Follow the instructions in Singular Links Prerequisites for iOS and/or Android.

  2. Additional Setup for Unity: In the app's AndroidManifest.xml file, change the activity name property from the default UnityPlayerActivity:

    <activity android:name="com.unity3d.player.UnityPlayerActivity"

    to:

    <activity android:name="com.singular.unitybridge.SingularUnityActivity"

    or:

    Note: If you've implemented a custom activity, call this method in the onNewIntent in your activity:

    @Override
    protected void onNewIntent(Intent intent) {
        setIntent(intent);
    
        // Call this method from your custom activity in onNewIntent
        SingularUnityBridge.onNewIntent(intent);
    }

Adding a Deep Links Handler

The Singular SDK provides a handler mechanism to read the details of the tracking link that led to the app being opened.

To use the handler:

  1. Implement the SingularLinkHandler interface.
  2. Call the SetSingularLinkHandler method at any point in the class to register the class as the handler for deep links.
  3. When you call SetSingularLinkHandler, the Singular SDK fetches the tracking link and calls the OnSingularLinkResolved method, passing the tracking link details to it. Override this method to read the link details and process them.

The following sample code shows the three steps:

public class Main : SingularLinkHandler {
    // ...
    void Awake () {
      // Register the class as the Singular Link handler.
      // You can call this method at any point in the app's run. It will fetch the tracking link details and call OnSingularLnkResolved.
      SingularSDK.SetSingularLinkHandler(this);
    }
    
    public void OnSingularLinkResolved(SingularLinkParams linkParams) {
      // The deep link destination, as configured in the Manage Links page
      string deeplink = linkParams.Deeplink;
      
      // The passthrough parameters added to the link, if any.
      string passthrough = linkParams.Passthrough;
      
      // Whether the link configured as a deferred deep link.
      bool isLinkDeferred = linkParams.IsDeferred;
      
      // Add code here to process the deeplink
    }
    
    // ...

Method Reference

SetSingularLinkHandler
SetSingularLinkHandler Method
Description Register a handler that retrieves the details of the tracking link that led to the opening of the app.
Signature
public void SetSingularLinkHandler(SingularLinkHandler 
handler)
Usage Example
public class Main : MonoBehaviour, SingularLinkHandler {
    void Awake () {
        SingularSDK.SetSingularLinkHandler(this)
    }
}
OnSingularLinkResolved
OnSingularLinkResolved Method
Description Callback method for SetSingularLinkHandler. Read the tracking link details and process them.
Signature
public void OnSingularLinkResolved(SingularLinkParams
linkParams)

Note: The SingularLinkParams object contains the following values:

  • Deeplink - The deep link destination, as configured in the Manage Links page in the Singular platform.
  • Passthrough - Passthrough parameters added to the link, if any.
  • IsDeferred - Is the link configured as a deferred deep link.
Usage Example
public void OnSingularLinkResolved(SingularLinkParams
linkParams){ // Read the tracking link details and log them Debug.Log("deeplink: " + linkParams.Deeplink); Debug.Log("passthrough: " + linkParams.Passthrough); Debug.Log("is_deferred: " + linkParams.IsDeferred); }

Handling Deep Links with Legacy Links

If you are an older Singular customer, you may be using legacy tracking links (Singular's older tracking link mechanism) rather than the newer Singular Links. Legacy links are managed in the Create Link and View Links pages, and they also provide deep linking and deferred deep linking functionality.

If your organization uses legacy links, you need to implement a handler for deep links called SingularDeferredDeepLinkHandler instead of the SingularLinksHandler described above. The implementation is very similar.

2.4. Initializing the SDK

Note: Remember to remain compliant with the various privacy laws enacted in regions where you are doing business, including GDPR, CCPA, COPPA, and others, 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.
Signature
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.

2.5. Configuring the Session Timeout (Optional)

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.

2.6. Sending the User ID to Singular (Optional)

You may send your internal User ID to Singular using a Singular SDK method.

Note: If you use Singular's Cross-Device solution, you must collect the User ID across all platforms.

  • The User ID can be any identifier and should not expose PII (Personally Identifiable Information). For example, you should not use a User's email address, username, or phone number. Singular recommends using a hashed value unique only to your first-party data.
  • The User ID value passed to Singular should also be the same internal User ID you capture across all platforms (Web/Mobile/PC/Console/Offline).
  • Singular will include the User ID in user-level exports, ETL, and Internal BI postbacks (if configured). The User ID is first-party data, and Singular does not share it with other parties.
  • The User ID value, when set with the Singular SDK Method, will persist until it is unset using the UnsetCustomUserId method or until the app is uninstalled. Closing or restarting the app does not unset the User ID.

To set the User ID, use the SetCustomUserId method. To unset it (for example, if the User "logs out" of the account), call UnsetCustomUserId.

Note: If multiple Users use a single device, we recommend implementing a logout flow to set and unset the User ID for each login and logout.

If you already know the user ID when the app opens, call SetCustomUserId before initializing the Singular SDK. This way, Singular can have the User ID from the first Session. However, the User ID is typically unavailable until the User registers or performs a login. In that case, call SetCustomUserId after the registration flow is complete.

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.
Signature public void UnsetCustomUserId()
Usage Example
SingularSDK.UnsetCustomUserId();

Optional: Custom User ID Device Mapping

Important: This advanced Enterprise feature is only available in exceptional cases. Please consult with one of Singular’s Solution Engineers before implementing it.

Singular can receive additional mobile event tracking data via a server-to-server integration. To utilize this feature, you must map the User ID to Singular’s Mobile Device tracking identifier.

Note: Call this method as soon as possible after initializing the Singular SDK or once you have the User ID.

SingularSDK.SetDeviceCustomUserId Method
Description Sets the Custom User Id the same as login and maps it to Singular’s tracking identifier.
Signature public void SetDeviceCustomUserId(string customUserId)
Usage Example
SingularSDK.SetDeviceCustomUserId('CustomUserId');

3. Tracking Events and Revenue

3.1. Tracking Events

Singular can collect data about in-app events to help analyze the performance of your campaigns and measure KPIs. For example, your organization may want to collect data about user logins, registrations, tutorial completions, or leveling up in a gaming app.

Singular supports a variety of standard events. These commonly used events are often supported by ad networks for reporting and optimization. Another advantage is that when you use standard event names, Singular recognizes them automatically and adds them to the Events list without you having to define them manually. We recommend using standard events whenever possible.

The list of events sent to Singular (with the accompanying attributes) should be compiled by the UA/marketing/business team based on your organization's marketing KPIs. The business team can follow the guide at How to Track In-App Events: Guide For Singular Attribution Customers.

With each event you track, you can pass various attributes. See the recommended standard attributes per event.

In your code, send standard events to Singular using the event or eventWithArgs methods.

Note: For standard events, use the event's Unity name as it appears in the Unity SDK List of Standard Events and Attributes, e.g., sngLogin.

For custom events, events that your organization wants to measure that do not match any of Singular's standard events, use any custom name (maximum of 32 characters). We recommend using names in English for compatibility with any ad network partners that may receive the event from Singular for optimization purposes.

SingularSDK.Event Method
Description Send user events to Singular for tracking.
Signature
public static void Event(string name)
public static void Event(string name, params object[] args)
public static void Event(Dictionary<string, object> args,
string name)

Note: When passing dictionaries, dictionary values must have one of these types: string, int, long, float, double, null, ArrayList, Dictionary<String,object>

Usage Example

// Send the standard event Login
SingularSDK.Event(sngLogin);
  
// An example custom event passing two key value pairs
SingularSDK.Event("Myevent", "Key1", "Value1", "Key2", 1234);
// An example JSONEvent passing a dictionary SingularSDK.Event(new Dictionary<string, object>() { {"Key1", "Value1"}, {"Key2", new Dictionary<string, object>() { {"SubKey1", "SubValue1"}, {"SubKey2", "SubValue2"} } }}, "JSONEvent");

3.2. Tracking Revenue

Singular can collect data about revenue gained through the app in order to help analyze the performance and ROI of your campaigns. Singular will make the data available in reports, log export, and postbacks.

Notes: Any revenue reported in a different currency will be auto-converted to your organization's preferred currency as set in your Singular account.

You can track revenue events using Unity's built-in IAP (In-App Purchases) object. This way, Singular gets all the available information about the purchase for richer reporting. Singular also gets the purchase receipt, which Singular uses in the back end to validate the purchase and rule out attribution fraud.

SingularSDK.InAppPurchase Method
Description Send an IAP product to Singular to track the purchase event.
Signature
public static void InAppPurchase(Product product,
Dictionary<string, object> attributes, bool isRestored = false)
public static void InAppPurchase(string eventName,
Product product, Dictionary<string, object> attributes,
bool isRestored = false)
public static void InAppPurchase(IEnumerable<Product> products, Dictionary<string, object> attributes, bool isRestored = false)
public static void InAppPurchase(string eventName,
IEnumerable<Product> products, Dictionary<string, object>
attributes, bool isRestored = false)

Notes:

  • product is the product object received from IAP: UnityEngine.Purchasing.Product
  • attributes: Use this parameter to pass additional information to Singular. If you don't have any attributes to pass, just pass null.
  • isRestored: Indicate whether the transaction is restored. Default: false.
Usage Example
// IAP with a single product and no extra attributes
SingularSDK.InAppPurchase(myProduct, null);
// IAP with a single product and attributes
var attr = new Dictionary<string, object>() {
["my_first_attribute"] = "value1",
["my_second_attribute"] = "value2"};
 
SingularSDK.InAppPurchase(myProduct, attr);

// IAP with with a single product, 
// no extra attributes and a custom event name

SingularSDK.InAppPurchase("MyCustomProduct",
myProduct, null);

// IAP with list of products, no extra attributes
SingularSDK.InAppPurchase(myProductList, null);

// IAP with with list of products, no extra attributes
// and a custom event name

SingularSDK.InAppPurchase("MyCustomProducts",
myProductList, null);
Alternative Way to Track Revenue: Revenue and CustomRevenue Methods

If you cannot use Unity IAP, the Singular SDK provides two methods for passing information about a purchase to Singular "manually":

  • Use Revenue to pass information about a purchase to Singular by detailing the transaction currency, the transaction amount, and other optional details.
  • CustomRevenue is very similar but also allows you to give the event a custom name.

Note: If you use Revenue/CustomRevenue instead of InAppPurchase, Singular will not be able to verify the purchase receipt.

SingularSDK.Revenue Method
Description Send a revenue event to Singular.
Signature
public static void Revenue(string currency, double amount)

public static void Revenue(string currency,
double amount, string productSKU, string productName,
string productCategory, int productQuantity, double productPrice)
Note: Pass currency as a three-letter ISO 4217 currency code, such as "USD", "EUR", "INR".
Usage Example
// Send a revenue event with no product details
SingularSDK.Revenue("USD", 9.99);

// Send a revenue event with product details
SingularSDK.Revenue("USD", 50.50, "abc123", "myProductName", 
"myProductCategory", 2, 25.50)
SingularSDK.CustomRevenue Method
Description Send a revenue event with a custom name to Singular.
Signature
public static void CustomRevenue(string eventName, 
string currency, double amount) public static void CustomRevenue(string eventName,
string currency, double amount, string productSKU,
string productName, string productCategory, int productQuantity,
double productPrice)
Note: Pass currency as a three-letter ISO 4217 currency code, such as "USD", "EUR", "INR".
Usage Example
// Send a revenue event with a custom name
SingularSDK.CustomRevenue("MyCustomRevenue", "USD", 9.99);

// Send a revenue event with a custom name + product details
SingularSDK.CustomRevenue("MyCustomRevenue", "USD", 50.50, 
"abc123", "myProductName", "myProductCategory", 2, 25.50)

3.3. Hybrid Event Tracking (Advanced)

Singular recommends sending all events and revenue through the Singular SDK integrated into your app. However, Singular can collect events and revenue from other sources.

Any event NOT sent from the Singular SDK must comply with Singular's Server-to-Server Event documentation requirements and provide the matching device identifier to correctly attribute an event.

Important:

Discrepancies will occur if device identifiers used on Server-to-Server event requests do not have a matching device identifier in Singular. Be aware of the following possibilities:

  • If an event request is received "before" the Singular SDK has recorded the device identifier, from an App Session, then the event request will be considered the "first session" for the unknown device, and Singular will attribute the device as an organic attribution.
  • If the Singular SDK did record a device identifier, but the Singular SDK identifier differs from the device identifier specified in the Server-to-Server Event request then the event will be attributed incorrectly.

Hybrid Event Tracking Guides

Sending Events from an Internal Server

Singular can collect data about revenue from your Server to help analyze the performance and ROI of your campaigns.

Requirements:

  • From an in-app Registration or Login Event, capture and pass the device identifiers and store this data with the User ID on your server. Because device identifiers may change for a user, be sure to update the identifiers when a user generates an app session. This guarantees the server-side event will be attributed to the correct device.
  • Server-side events are platform specific and should only be sent with the device identifier matching the device platform (e.g., IDFA or IDFV for iOS devices).
  • You can use the Singular Internal BI postback mechanism to push an event in real time to your internal endpoint so that you can update the data set on the server side. See the Internal BI Postback FAQ.
  • Review the "Tracking Revenue" section in the Server-to-Server Integration guide for details.
Sending Events from a Revenue Provider
Third-party providers like RevenueCat or adapty can provide Purchase and Subscription Revenue to Singular.

Follow the links below for details on how to enable these partners.

Sending Events from Segment

To enable Segment to send events to Singular, in parallel with the Singular SDK, you must add a "Cloud-Mode" Destination in Segment. Follow our guide HERE.

4. Advanced Options

4.1. Creating Short Referrer Links

Note: This functionality is available in SDK version 4.0.16+.

Use short links to transform long, parameter-filled Singular Links into shorter and more secure links that are convenient for sharing.

Typically, you will want to create short links dynamically so that your app's users can share them with friends to invite them to use the app.

To create a short link, you need:

  • A Singular Link that leads to your app download (see the Singular Links FAQ).
  • Any parameters you want to add to the link dynamically (see Tracking Link Parameters for the list of options).
  • The name and ID of the referring user, if you want to be able to track new app installs back to the user who shared the link.

Use the createReferrerShortLink method to create a short link as in the example below.

void callback(string shortLinkURL, string error){
    // Add your share logic here if shortLinkURL is not null
    // If there was an error, add logic to retry/abort/modify the params
// passed to the function, based on the cause of the error } SingularSDK.createReferrerShortLink( "https://sample.sng.link/B4tbm/v8fp?_dl=https%3A%2F%2Fabc.com", "John Doe", // Referrer Name "342", // Referrer ID new Dictionary<string, string>() { // a Dictionary object containing any parameters you want to add {"channel", "sms"} }, callback );

4.2. Adding Ad Revenue Attribution Support

Note: Starting in version 3.0.0, Singular added the option to set up ad revenue attribution through the Singular SDK.

Ad revenue attribution can still be set up the old way, using API calls, without updating the Singular SDK in your apps. However, if you want to measure ad revenue for SKAdNetwork campaigns, you have to set up ad revenue attribution through the SDK.

To add ad revenue attribution support in the Singular SDK:

  1. Update to the latest version of the Singular SDK.
  2. Add the appropriate code snippet to your Singular SDK integration, depending on the mediation platform you use for ad revenue data.

Note: Pass currency as a three-letter ISO 4217 currency code, e.g., "USD," "EUR", "INR".

AdMob
    1. Note: This feature needs to be enabled in your Admob account.

      See https://support.google.com/admob/answer/11322405#getstarted

Note: The Google AdMob Unity SDK has changed!

To learn more about the latest migration for current and previous versions of the Google AdMob Unity SDK. See the Google documentation here: Google AdMob Mobile Ads SDK (Unity) Migration

Admob Unity SDK v8.0.0+ (C#) Admob Unity SDK Legacy (C#)

The following code is for Admob Unity SDK v8.0.0+

Listen to rewarded ad events as documented in the Google AdMob documentation HERE

private void RegisterEventHandlers(RewardedAd ad)
{
    // Raised when the ad is estimated to have earned money.
    ad.OnAdPaid += (AdValue adValue) =>
    {
        // Construct and Send Singular AdMon Event
        SingularAdData data = new SingularAdData(
           "Admob",
            adValue.CurrencyCode,
            adValue.Value/1000000f);
        Singular.AdRevenue(data);
    };
}
AppLovinMax
  1. Retrieve the object received from AppLovin MAX's event, OnInterstitialAdRevenuePaidEvent
C#
MaxSdkBase.AdInfo impressionData;
string adUnitId;
double revenue = MaxSdk.GetAdInfo(adUnitId).Revenue;

SingularAdData data = new SingularAdData(
"AppLovin",
"USD",
revenue); Singular.AdRevenue(data);
IronSource
  1. Retrieve the object received from IronSource's event, OnImpressionSuccess
  2. Ensure that the ARM SDK Postbacks Flag in IronSource is turned on
  3. See https://developers.is.com/ironsource-mobile/general/ad-revenue-measurement-postbacks/#step-1
C#
IronSourceImpressionData impressionData;
SingularAdData data = new SingularAdData(
"IronSource",
"USD",
impressionData.revenue); Singular.AdRevenue(data);
TradPlus
  1. Retrieve the object received from TradplusAds event: AddGlobalAdImpression
  2. Add Singular to the TradPlusAdImpression Callback
C#
TradplusAds.Instance().AddGlobalAdImpression(OnGlobalAdImpression);

void OnGlobalAdImpression(Dictionary<string, object="object"> adInfo) {
   double revenue = 0;
   double.TryParse(
adInfo["ecpm"].ToString(),
NumberStyles.Float| NumberStyles.AllowThousands,
CultureInfo.InvariantCulture, out revenue); if(revenue != 0) revenue = revenue / 1000; SingularAdData data = new SingularAdData(
"TradPlus",
"USD",
revenue); SingularSDK.AdRevenue(data); }
Other (Generic)
  1. Initialize the SingularAdData object with the relevant data
  2. Report the data to Singular
C#
SingularAdData data = new SingularAdData(
   YOUR_AD_PLATFORM,
   CURRENCY_CODE,
   9.90);

SingularSDK.AdRevenue(data);

4.3. Tracking Uninstalls

Note: Uninstall tracking is only available to Enterprise customers.

Android Uninstall Tracking

To enable uninstall tracking for your Android app, first configure the app in the Singular platform as detailed in Setting Up Uninstall Tracking. Then follow the instructions below.

Note: Google deprecated the GCM APIs on April 2018. Use FCM for uninstall tracking.

Enabling Uninstall Tracking Using Firebase Cloud Messaging (FCM):

1. Integrate with FCM:

To track uninstalls, you can use the services of the Firebase Cloud Messaging (FCM) platform. If you are not already using FCM, follow Google's instructions on how to Set up a Firebase Cloud Messaging client app on Android.

FCM Requirements (source)

FCM clients require devices running Android 4.1 or higher that also have the Google Play Store app installed, or an emulator running Android 4.1 with Google APIs. Note that you are not limited to deploying your Android apps through Google Play Store.

Users/devices who are not running on supported versions of Android will not be available for Singular uninstall tracking.

2. Update the AndroidManifest.xml File:

Update your AndroidManifest.xml file to add the necessary intent filter for your app (replace MyFirebaseMessagingService with your class that implements the Firebase Service):

<service android:name=".java.MyFirebaseMessagingService" android:exported="false">
  <intent-filter>
    <action android:name="com.google.firebase.MESSAGING_EVENT" />
  </intent-filter> 
</service>

3. Register and Send the FCM Device Token:

After retrieving the FCM token, pass it as a parameter to the 'RegisterTokenForUninstall' method:

SingularSDK.RegisterTokenForUninstall(String fcmDeviceToken);

Note that the 'RegisterTokenForUninstall' method should be called before the 'SingularSDK.InitializeSingularSDK()' method.

iOS Uninstall Tracking

Uninstall tracking on iOS is based on Apple push-notification technology. If your app doesn't currently support push notifications, see Apple's guide. If your app already supports push notifications, all you need to do is pass the device token returned from APNS using the RegisterTokenForUninstall method, after the SDK is initialized. 

SingularSDK.RegisterTokenForUninstall Method
Description Pass the device token returned from APNS. Note that the APNS token is usually binary data in the native form, but you need to pass it as a string.
Signature
public static void RegisterTokenForUninstall
(string APNSToken)
Usage Example
// pass the APNS token as a hex-string 
  SingularSDK.RegisterTokenForUninstall("ba85ab31a7c7
f5c2f012587f29fb0e596d4b67e7b7b2838fa1a8582c1f7dbdee");

4.4. Adding Global Properties

The Singular SDK lets you define custom additional properties to send to the Singular servers with every session and event sent from the app. These properties can represent any information you want about the user, the app mode or status, or anything else. Once you set these properties, they are available as dimensions in your reports and you can use them to break down your data.

For example, if you have a gaming app, you can define a property called "Level" and set it initially to "0". Any session and event sent from the app will be sent with "Level": "0". Once the user levels up you reset the property to "1" and so on. You can then get your reports, including sessions, event counts, and revenue data, broken down by user level.

  • You can define up to 5 global properties.
  • They persist between app runs (with the latest value you gave them) until you unset them or the user uninstalls the app.
  • Each property name and value can be up to 200 characters long. If you pass a longer property name or value, it will be truncated to 200 characters.
  • Global properties are accessible and available in user-level exports and postbacks. In the future, aggregate reporting support will be added. Let your Singular customer success manager know if you have any questions or are interested in updates to global properties support!

Setting Global Properties Before Initialization

You can use the SetGlobalProperty method to set global properties through SingularSDK before initializing the SDK. Turn off the 'Initialize On awake' flag if you want your global properties to be included in the session. 

Note that since global properties and their values persist between app runs, the property that you are setting may already be set to a different value. Use the overrideExisting parameter to tell the SDK whether to override an existing property with the new value or not.

Setting Global Properties After Initialization

Use the following methods to set, unset, and retrieve global properties at any time in the app's run.

SingularSDK.SetGlobalProperty Method
Description

Set a global property to a given value.

Notes:

  • If the property does not exist yet, and there are already 5 other global properties, the property will not be added.
  • If the property has already been set, the overrideExisting parameter determines whether the existing value will be overridden.
  • The method returns true if the property was set successfully or false otherwise.
Signature public static bool SetGlobalProperty(string key, string value, bool overrideExisting)
Usage Example
bool result = SingularSDK.SetGlobalProperty("key", "value", false);
SingularSDK.GetGlobalProperties Method
Description Retrieve all the global properties and their current values as a Map.
Signature public static Dictionary<string, string> GetGlobalProperties()
Usage Example
Dictionary<string, string> props = SingularSDK.GetGlobalProperties();
SingularSDK.UnsetGlobalProperty Method
Description Remove a global property.
Signature public static void UnsetGlobalProperty(string key)
Usage Example
SingularSDK.UnsetGlobalProperty(“test_key”);
SingularSDK.ClearGlobalProperties Method
Description Remove all global properties.
Signature public static void ClearGlobalProperties()
Usage Example
SingularSDK.clearGlobalProperties();

4.5. Collecting the Install Referrer on Older Android Devices

In Android, the install referrer is Singular's most accurate tool to determine attribution, in addition to helping Singular detect and analyze fraud attempts. It is an identifier provided by the Google Play Store that points to the ad that the user clicked on before installing the app.

On devices that have the latest version of the Google Play Store, the Singular SDK collects the install referrer value automatically (since Singular is integrated with the latest Google Play Referrer API).

To collect the install referrer on older devices, follow the instructions in the Android SDK guide.

5. Complying with Data Privacy Laws

5.1. LimitDataSharing

Singular provides privacy-safeguarding functionality to help you cooperate with any partners who may be complying with consumer privacy laws such as GDPR and CCPA (California Consumer Privacy Act). These partners want to be notified if the end-user has consented to share their private information.

LimitDataSharing

If you have implemented a way to ask users for consent to share their information, use the limitDataSharing method to notify Singular of the user's choice:

  • Use limitDataSharing:NO to indicate that the user consented (opted in) to share their information.
  • Use limitDataSharing:YES if the user did not consent.

Singular uses LimitDataSharing in "User Privacy Postbacks" as well as passing this information on to partners who require it in order to comply with relevant regulations. See "User Privacy and Limit Data Sharing" for more information.

Note: The use of the method is optional, but there may be attribution information that the partner will share with Singular only if specifically notified that the user has opted in.

SingularSDK.LimitDataSharing Method
Signature SingularSDK.LimitDataSharing(bool shouldLimitDataSharing)
Description Notify Singular of user consent (opt-in) for sharing private data.
Usage Example
// User has opted in to sharing data
SingularSDK.LimitDataSharing(false);

5.2. Additional Methods for GDPR Compliance

The Singular SDK provides several methods to help you comply with GDPR policies and let Singular know about user consent or non-consent for tracking.

SingularSDK.TrackingOptIn Method
Description Notify Singular of user consent (opt-in) for tracking.
Usage Example
SingularSDK.TrackingOptIn();
SingularSDK.StopAllTracking Method
Description Stop all tracking activities for this user on this app.
Note: Calling this method effectively disables the SDK, even after the app restarts (the state is persistent)! The only way to re-enable tracking is by calling resumeAllTracking().
Usage Example
SingularSDK.StopAllTracking();
SingularSDK.ResumeAllTracking Method
Description Resume tracking for this user on this app.
Usage Example
SingularSDK.ResumeAllTracking();
SingularSDK.IsAllTrackingStopped Method
Description Check the tracking status for this user on this app. Returns true if tracking has been stopped using StopAllTracking() and not resumed.
Usage Example
SingularSDK.IsAllTrackingStopped();