Android SDK: Tracking Events and Revenue

Avatar
Dora Kishinevsky
Updated
Singular Android SDK
Download
 Singular Android SDK version 12.0.5 (see Change Log)
Compatibility

Android 4.0.1 (Ice Cream Sandwich) and higher

  • The SDK uses the device's Android Advertising ID for devices that use Play Store version 4. For older devices, the SDK uses the Android ID.
  • The latest version of the SDK has not been tested with Android versions older than 4.0.1.
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. 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.

You can send events to Singular using the event and eventJSON methods.

Note:

  • We highly recommend passing event names and attributes in English to guarantee compatibility with third-party partners and analytics solutions if you plan to use them.
  • Event names are limited to 32 ASCII characters. Strings in non-ASCII characters have to be under 32 bytes once converted to UTF-8.
  • Attributes and values are limited to 500 ASCII characters.
Singular.event Method
Description Report a user event to Singular with or without additional information.
Signature

Singular.event(String eventName)
Singular.event(String eventName, Object... args)

Note: 'args' is one or more key-value pairs (see the example below). The key is a string and the value can be any type that's allowed as a JSONObject value (i.e., JSONObject, JSONArray, String, Boolean, Integer, Long, Double or NULL).

The 'args' list must contain an even number of elements or the event will be rejected by Singular.
Usage Example 
// Send a login event with no arguments
Singular.event("Login");

// Send an event called "Purchase_Complete" with 
// arguments for quantity, product, and price
Singular.event("Purchase_Complete", "quantity", 3, 
    "product", "cotton shirt", "price", 42.34);
Singular.eventJSON Method
Description Report a user event to Singular with additional information in JSONObject format.
Signature

Singular.eventJSON(String name, JSONObject args)

Note: 'args' is a JSONObject containing one or more key-value pairs. The key is a string and the value can be any type that's allowed as a JSONObject value.
Usage Example 
import org.json.*
try {
  JSONArray contents = new JSONArray();
  JSONObject item1 = new JSONObject();

  item1.put("sku", "UPC-018627610014");
  item1.put("qty", 2);
  item1.put("unit_price", 8.99);
  item1.put("currency", "USD");
  contents.put(item1);

  JSONObject item2 = new JSONObject();
  item2.put("sku", "UPC-070271003758");
  item2.put("qty", 1);
  item2.put("unit_price", 15.99);
  item2.put("currency", "USD");
  contents.put(item2);

  JSONObject args = new JSONObject();
  args.put("contents", contents);
  args.put("total", 63.96);
  args.put("currency", "USD");
  args.put("member_id", "A556740089");

  // Record the event with Singular
  Singular.eventJSON("Purchase_Complete", args);
}
catch(JSONException e) {
  android.util.Log.e("Now", "JSON Exception in cart");
}

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

When reporting revenue events to Singular, we recommend passing the purchase object received from the billing library. This has two advantages:

  1. Singular gets all the details of the transaction, which enriches your Singular reports.
  2. Singular gets the transaction receipt from Google which can be used to validate the transaction in the context of fighting in-app fraud.

Use the revenue and customRevenue methods to report events. CustomRevenue allows you to pass a custom event name, so that you'll be able to view revenue in Singular reports broken down by the different types of revenue events.

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

 

Singular.revenue Method
Description Send a revenue event to Singular with optional additional information.
Signature

Singular.revenue(String currency, double amount, Object purchase)

Note:

  • When passing an object, it has to be of type Purchase or Singular will not contain the receipt information.
  • Pass currency as a three-letter ISO 4217 currency code, such as “USD”, “EUR”, or “INR".
Usage Example 
// Send a revenue event to Singular + the purchase object
// that was received from the Google Billing Library 
Singular.revenue("USD", 5.50, purchase);
Singular.customRevenue Method
Description Send a revenue event to Singular with an event name and optional additional information.
Signature

Singular.customRevenue(String eventName, String currency, double amount, Object purchase)

Note:

  • When passing an object, it has to be of type Purchase or Singular will not contain the receipt information.
  • Pass currency as a three-letter ISO 4217 currency code, such as “USD”, “EUR”, or “INR".
Usage Example 
// Send a revenue event to Singular, passing the event 
// name and the purchase object
Singular.customRevenue("MyCustomRevenue", "USD", 
    5.50, purchase)

Reporting Revenue without the Purchase Object

While we strongly recommend reporting revenue events the way described above, you can also use revenue and customRevenue without passing the purchase object. Instead, you pass the currency and amount of the transaction, and optional product details.

Note that when reporting revenue events this way, Singular does not get the purchase receipt and cannot validate the transaction.

Read more...
Singular.revenue Method (Without Purchase Object)

Description

Send a revenue event to Singular with optional additional information.

Signature

Singular.revenue(String currency, double amount, String productSKU, String productName, String productCategory, int productQuantity, double productPrice)

Singular.revenue(String currency, double amount)

Note: Pass currency as a three-letter ISO 4217 currency code, such as “USD”, “EUR”, or “INR".

Usage Example

 
// Send a revenue event to Singular with product details
Singular.revenue("EUR", 5.00, "SKU1928375", 
"Reservation Fee", "Fee" , 1, 5.00);

// Send a revenue event to Singular with no product details
Singular.revenue("USD", 5.50);
Singular.customRevenue Method (Without Purchase Object)
Description Send a revenue event to Singular with an event name and optional additional information.
Signature

Singular.customRevenue(String eventName, String currency, double amount, String productSKU, String productName, String productCategory, int productQuantity, double productPrice)
Singular.customRevenue(String currency, double amount)

Note: Pass currency as a three-letter ISO 4217 currency code, such as “USD”, “EUR”, or “INR".
  
// Send a revenue event to Singular with the event name
// and product details
Singular.customRevenue("MyCustomRevenue", "EUR", 5.00, 
"SKU1928375", "Reservation Fee", "Fee" , 1, 5.00);

// Send a revenue event to Singular with the event name
Singular.customRevenue("MyCustomRevenue", "USD", 5.50);
Integration Guides
  1. Basic Integration
  2. Tracking Events and Revenue
  3. Implementing Deep Links
  4. Advanced Options