iOS SDK: Tracking Events and Revenue

Avatar
Dora Kishinevsky
Updated
Singular iOS SDK
Download
 Singular iOS SDK version 11.0.1 (see Change Log)
Compatibility iOS 8+
Sample App

Our sample app includes a complete integration of the Singular SDK. Review the code to see how the different parts of the integration come together using 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.

You can send events to Singular using the event and eventWithArgs 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 characters in ASCII. If you use non-ASCII characters, the limit is 32 bytes after the string is converted to UTF-8.
  • The names and values of additional attributes are limited to 500 ASCII characters.
event Method
Description Send a user event to Singular for tracking.
Signature +(void)event:(NSString *)name
Usage Example

Objective-C:

[Singular event:@"login"];

Swift (requires bridging header):

Singular.event("login")
eventWithArgs Method
Description Send a user event to Singular for tracking, with additional information.
Signature +(void)eventWithArgs:(NSString *)name, ...
Usage Example

Objective-C:

// Send an event in which the user viewed a product,
// including the product's serial number and price
[Singular eventWithArgs:@"viewItem",
   @"sku", @"12345",
   @"price", [NSNumber numberWithDouble:123.45], nil];

Swift (requires bridging header):

// Send an event in which the user viewed a product,
// including the product's serial number and price
Singular.event("viewItem", withArgs: ["sku": "12345",
    "price": "12345"])
event Method (with Arguments in NSDictionary format)
Description Send a user event to Singular for tracking, with additional information passed in an NSDictionary object.
Signature + (void) event:(NSString *)name withArgs:(NSDictionary *)args;
Usage Example

Objective-C:

// Send a shopping cart update event to Singular
// with all the items' details in an NSDictionary

// First, build each shopping cart item
NSDictionary *item1 = [NSDictionary 
    dictionaryWithObjectsAndKeys:
   @"UPC-018627610014", @"sku",
   [NSNumber numberWithInt:2], @"qty",
   [NSNumber numberWithDouble:8.99], @"unit_price",
   @"USD", @"currency", nil];
NSDictionary *item2 = [NSDictionary
    dictionaryWithObjectsAndKeys:
   @"UPC-070271003758", @"sku",
   [NSNumber numberWithInt:1], @"qty",
   [NSNumber numberWithDouble:15.99], @"unit_price",
   @"USD", @"currency", nil];
NSDictionary *item3 = [NSDictionary
    dictionaryWithObjectsAndKeys:
   @"ISBN13-978-0-596-51774-8", @"sku",
   [NSNumber numberWithInt:1], @"qty",
   [NSNumber numberWithDouble:29.99], @"unit_price",
   @"USD", @"currency", nil];

// Combine the items into an array (optional)
NSArray *contents = [NSArray arrayWithObjects:item1,
    item2, item3, nil];

// Place the array of items into the shopping cart
// Note: The total is hardcoded here for conciseness, 
// you would normally calculate it
NSDictionary *args = [NSDictionary
    dictionaryWithObjectsAndKeys:contents,
   @"contents",
   [NSNumber numberWithDouble:63.96], @"total",
   @"USD", @"currency",
   @"A556740089", @"member_id", nil];

// Send the event to Singular
[Singular event:@"cart" withArgs:args];

Swift:

// Send a shopping cart update event to Singular
// with all the items' details in an NSDictionary

// First, build each shopping cart item
let item1:[String:Any] = ["sku":"UPC-018627610014","qty":2,
			  "unit_price":8.99, "currency":"USD"]
let item2:[String:Any] = ["sku":"UPC-070271003758","qty":1, 
			  "unit_price":15.99, "currency":"USD"]
let item3:[String:Any] = ["sku":"ISBN13-978-0-596-51774-8","qty":1,
			  "unit_price":29.99, "currency":"USD"]

// Combine the items into an array (optional)
let contents = [item1, item2, item3]

// Place the array of items into the shopping cart
// Note: The total is hardcoded here for conciseness, 
// you would normally calculate it
let args:[String:Any] = ["contents":contents, "total":63.96,
   "currency":"USD", "member_id":"A556740089"]

// Send the event to Singular
Singular.event("cart", withArgs:args)

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.

To report revenue events to Singular, use the iapComplete SDK method. This method sends an IAP (Apple's In-App Purchase) revenue event to Singular, and passes:

  • All the transaction details, which Singular will use to enrich your reports with data.
  • The transaction receipt, which can be used to validate the transaction and to analyze and prevent fraud attempts.

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

iapComplete Method
Description Send a revenue event to Singular with the transaction receipt.
Signature (void)iapComplete:(id)transaction
(void)iapComplete:(id)transaction withName:(NSString *)name;
Usage Example

Objective-C:

SKPaymentTransaction* transaction = ...;

// Send a transaction event to Singular
[Singular iapComplete:transaction];

// Send a transaction event to Singular
// with a custom name for the event
[Singular iapComplete:transaction
    withName:@"MyCustomRevenue"];

Swift:

let transaction:SKPaymentTransaction = ...

// Send a transaction event to Singular
Singular.iapComplete(transaction)

// Send a transaction event to Singular
// with a custom name for the event
Singular.iapComplete(transaction, withName:"MyCustomRevenue")

Alternative Revenue Event Reporting

While Singular recommends using iapComplete, we also provide two other methods to report revenue events to Singular - revenue and customRevenue.

Read more...

These methods let you specify the transaction amount and currency manually, as well as optional additional details, such as the product serial number and quantity. customRevenue also lets you pass a custom event name.

Note that if you use these methods, Singular does not get the transaction receipt and cannot validate the transaction.

revenue Method
Description Send a revenue event to Singular with the revenue amount and currency, and optional additional details.
Signature (void)revenue:(NSString *)currency amount:(double)amount;
(void)revenue:(NSString *)currency amount:(double)amount productSKU:(NSString *)productSKU productName:(NSString *)productName productCategory:(NSString *)productCategory productQuantity:(int)productQuantity productPrice:(double)productPrice;

Note: Pass currency as a three-letter ISO 4217 currency code, e.g, “USD,” “EUR”, “INR”.
Usage Example

Objective-C:

// Revenue with no product details
[Singular revenue:@"USD" amount:1.99];

// Revenue with product details
[Singular revenue:@"EUR" amount:5.00 productSKU:@"SKU1928375"
productName:@"Reservation Fee" productCategory:@"Fee" 
productQuantity:1 productPrice:5.00];

Swift:

// Revenue with no product details
Singular.revenue("USD",amount:1.99)

// Revenue with product details
Singular.revenue("EUR",amount:5.00, productSKU:"SKU1928375", 
productName:"Reservation Fee",productCategory:"Fee", 
productQuantity:1, productPrice:5.00)
customRevenue Method
Description Send a revenue event to Singular with an event name as well as the revenue amount and currency, and optional additional details.
Signature (void)customRevenue:(NSString *)eventName currency:(NSString *)currency amount:(double)amount;
(void)customRevenue:(NSString *)eventName currency:(NSString *)currency amount:(double)amount productSKU:(NSString *)productSKU productName:(NSString *)productName productCategory:(NSString *)productCategory productQuantity:(int)productQuantity productPrice:(double)productPrice;

Note: Pass currency as a three-letter ISO 4217 currency code, e.g, “USD,” “EUR”, “INR”.
Usage Example

Objective-C:

// Revenue with a custom name and no product details
[Singular customRevenue:@"MyCustomRevenue" currency:@"USD"
amount:1.99];

// Revenue with a custom name and product details
[Singular customRevenue:@"MyCustomRevenue" currency:@"EUR"
amount:5.00 productSKU:@"SKU1928375"
productName:@"Reservation Fee" productCategory:@"Fee" 
productQuantity:1 productPrice:5.00];

Swift:

// Revenue with a custom name and no product details
Singular.customRevenue("MyCustomRevenue", currency:"USD", 
amount:1.99)

// Revenue with a custom name and product details
Singular.customRevenue("MyCustomRevenue", currency:"EUR", 
amount:5.00, productSKU:"SKU1928375", 
productName:"Reservation Fee", productCategory:"Fee", 
productQuantity:1, productPrice:5.00)
Integration Guides
  1. Basic Integration
  2. Tracking Events and Revenue
  3. Implementing Deep Links
  4. Adding SKAdNetwork Support
  5. Advanced Options
Was this article helpful?