Unity SDK: Tracking Events and Revenue

Follow
Avatar
Dora Kishinevsky
Updated
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
  1. Basic Integration
  2. Tracking Events and Revenue
  3. Implementing Deep Links
  4. Adding SKAdNetwork Support
  5. Advanced Options

 

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

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 to you in reports, log export, and postbacks.

Use one of the following methods to report revenue events to Singular.

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

Option 1 (Recommended): SingularSDK.InAppPurchase

You can track revenue events by leveraging Unity IAP (In-App Purchases). This gives two important advantages: 

  1. Singular gets all the available information about the purchase for richer reporting.
  2. 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);

Option 2: Revenue and CustomRevenue

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

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)
Integration Guides
  1. Basic Integration
  2. Tracking Events and Revenue
  3. Implementing Deep Links
  4. Adding SKAdNetwork Support
  5. Advanced Options