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.
• Verify if you use Google EDM4U, the Google External Dependency Manager for Unity.
  What is Google EDM4U? Learn more [HERE].
  

1. Installing the SDK

1.1. Downloading and Importing the SDK Package

1.2. Configuration for Android

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

1.3. Tips for iOS

pod repo update
pod update

// Printing Identifier for Vendor (IDFV) to Xcode Console for use in Singular SDK Console
NSLog(@"Singular === IDFV: %@", [[[UIDevice currentDevice] identifierForVendor] UUIDString]);

2. SDK Integration

2.1. Create the SingularSDKObject

Add the SingularSDKObject to the Hierarchy

Configure the SingularSDKObject Settings

1. In the Inspection pane for the SingularSDKObject, paste your Singular SDK Key and SDK Secret into the respective fields. To retrieve the SDK Key and Secret, log into your Singular account and go to "Developer Tools > SDK Integration > SDK Keys").
   
   
   
   IMPORTANT: DO NOT USE the Singular Reporting API Key or your SDK data will not be received. Follow the instructions above to retrieve the proper key and secret.
   
   
   

   If the Singular SDK Key and Secret are incorrectly applied, data will not be sent to Singular.
   Test your implementation using the Singular SDK Console to verify correct behavior.

Other Inspection Pane Options:

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

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

Additional Information

// A sign-up event happened
Singular.Event("SignUp");

// Update the conversion value to 7
SingularSDK.SkanUpdateConversionValue(7);

int? value = SingularSDK.SkanGetConversionValue();

public class Main : MonoBehaviour, SingularConversionValueUpdatedHandler {
  void Awake() {
    SingularSDK.SetConversionValueUpdatedHandler(this);
  }

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

2.3. Handling iOS App Tracking Transparency(ATT) Consent

Are you displaying the App Tracking Transparency(ATT) Prompt?

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

Singular and Ad Networks greatly benefit from having the IDFA to identify devices and perform install attribution (although there are ways to do this without the IDFA). We strongly recommend asking for the user's consent to get the IDFA.

Delaying the Singular SDK Initialization is recommended until the User responds to the ATT prompt.

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 configure the waitForTrackingAuthorizationWithTimeoutInterval adjust the configuration option in the SingularSDKObject Inspection pane. This sets the maximum time (in seconds) for the Singular SDK to wait for the User to authorize/deny AppTrackingTransparency Consent before logging events to Singular's servers.

2.4. Handling Deep Links

Deep links are URLs that direct users to specific content within an app. When a user clicks a deep link on a device with the app already installed, the app opens and displays a particular product or experience.

Singular tracking links can incorporate both deep linking and deferred deep linking. For more details, you can refer to our Deep Linking FAQ and the Singular Links FAQ.

Expand the sections below for details on platform support and handler code:

using System.Collections;
using System.Collections.Generic;
using UnityEngine;
using Singular;

public class SingularMain : MonoBehaviour, SingularLinkHandler
{
    // Start is called before the first frame update
    void Start()
    {
        
    }
    
    void Awake () {
        Debug.Log("Singular === 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) {
        Debug.Log("Singular === OnSingularLinkResolved");
        
        // 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
        Debug.Log("Singular === deeplink: "+deeplink);
        Debug.Log("Singular === passthrough: "+passthrough);
        Debug.Log("Singular === isLinkDeferred: "+isLinkDeferred);      
    }
}

public void SetSingularLinkHandler(SingularLinkHandler 
handler)

public class Main : MonoBehaviour, SingularLinkHandler {
    void Awake () {
        SingularSDK.SetSingularLinkHandler(this)
    }
}

public void OnSingularLinkResolved(SingularLinkParams
linkParams)

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);
}

public class Main : SingularDeferredDeepLinkHandler {
              
// ...
                
void Awake () {
    // Register the class as the deep link handler.
    // You can call this method at any point in the app's run.
    SingularSDK.SetDeferredDeepLinkHandler(this);
}
                
public void OnDeferredDeepLink(string deeplink) {
    // Code to handle the deep link goes here.
    // In this example, the deep link is just logged.
    Debug.Log ("Deep link received:" + deeplink);
}
                
// ...

2.5. 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 sends a new session to Singular, which 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();

2.6. 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.7. Sending the User ID to Singular (Optional)

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

• 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.
• When set with the Singular SDK Method, the User ID value persists 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.

If you already know the user ID when the app opens, call SetCustomUserId before initializing the Singular SDK. This way, Singular can get 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("custom_user_id");

SingularSDK.UnsetCustomUserId();

SingularSDK.SetDeviceCustomUserId('CustomUserId');

3. Tracking Events and Revenue

3.1. Tracking Events (Non Revenue)

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. Ad networks often support these commonly used events 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 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.

Send standard events to Singular using the event or eventWithArgs methods in your code.

SingularSDK.Event(Events.sngLogin);

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)

// 1) Send the standard event Login
SingularSDK.Event(Events.sngLogin);

// 2) An example custom event passing two key value pairs
SingularSDK.Event("myEventName", "Key1", "Value1", "Key2", 1234);

// 3) An example JSON Event passing a dictionary
// Create a dictionary for attributes
Dictionary<string, object> attributes = new Dictionary<string, object>();

// Add attributes
attributes["key1"] = "value1";
attributes["key2"] = "value2";
attributes["key3"] = "value3";
// Add more attributes as needed

SingularSDK.Event(attributes, "myEventName");

3.2. Tracking Revenue

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

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.

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)

// 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);

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)

public static void Revenue(string currency, double amount, Dictionary<string, object> attributes)

// Send a revenue event with no product details
SingularSDK.Revenue("USD", 1.99);

// Send a revenue event with product details
SingularSDK.Revenue("USD", 4.99, "coin_package_abc123", "Coin Pack 5", "Bundles", 1, 4.99);

// Send a revenue event with JSON Dictionary for attributes
Dictionary<string, object> attributes = new Dictionary<string, object>();

// Add attributes
attributes["productSKU"] = "coin_package_abc123";
attributes["productName"] = "Coin Pack 5";
attributes["productCategory"] = "Bundles";
attributes["productQuantity"] = 2;
attributes["productPrice"] = 4.99;

SingularSDK.Revenue("USD", 9.98, attributes);

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)

public static void CustomRevenue(string eventName, string currency, double amount, Dictionary<string, object> attributes)

// 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);

// Send a revenue event with a custom name + JSON Dictionary for attributes
// Create a dictionary for attributes
Dictionary<string, object> attributes = new Dictionary<string, object>();

// Add attributes
attributes["productSKU"] = "coin_package_abc123";
attributes["productName"] = "Coin Pack 5";
attributes["productCategory"] = "Bundles";
attributes["productQuantity"] = 2;
attributes["productPrice"] = 4.99;
// Add more attributes as needed

SingularSDK.CustomRevenue("MyCustomRevenue", "USD", 9.98, attributes);

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.

Hybrid Event Tracking Guides

4. Advanced Options

4.1. Creating Short Referrer Links

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).
• You can add any parameters you want to the link dynamically (see Tracking Link Parameters for the list of options).
• If you want to track new app installs back to the user who shared the link, you must provide the Referrer Name and Referrer ID of the referring user.

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

4.3. Tracking Uninstalls

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.

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.

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

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 support push notifications, see Apple's guide. If your app already supports push notifications, you must pass the device token returned from APNS using the RegisterTokenForUninstall method after the SDK is initialized. 

public static void RegisterTokenForUninstall
(string APNSToken)

// pass the APNS token as a hex-string 
  SingularSDK.RegisterTokenForUninstall("ba85ab31a7c7
f5c2f012587f29fb0e596d4b67e7b7b2838fa1a8582c1f7dbdee");

4.4. Adding Global Properties

With every session and event sent from the app, the Singular SDK lets you define custom additional properties to send to the Singular servers. These properties can represent any information you want about the user, the app mode, 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.

Setting Global Properties Before Initialization

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

Since global properties and their values persist between app runs, the property 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.

Setting Global Properties After Initialization

You can use the following methods to set, unset, and retrieve global properties at any time during the app's run.

bool result = SingularSDK.SetGlobalProperty("key", "value", false);

Dictionary<string, string> props = SingularSDK.GetGlobalProperties();

SingularSDK.UnsetGlobalProperty(“test_key”);

SingularSDK.clearGlobalProperties();

4.5. Collecting the Install Referrer on Older Android Devices

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

On devices with the latest Google Play Store version, the Singular SDK automatically collects the install referrer value (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" and passes this information on to partners who require it to comply with relevant regulations. See "User Privacy and Limit Data Sharing" for more information.

// 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();

SingularSDK.StopAllTracking();

SingularSDK.ResumeAllTracking();

SingularSDK.IsAllTrackingStopped();