Singular iOS SDK
Download	Singular iOS SDK version 10.1.2
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	Basic Integration Tracking Events and Revenue Implementing Deep Links Adding SKAdNetwork Support 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];

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

Alternative Revenue Event Reporting

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

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];`
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];`

Integration Guides

iOS SDK: Tracking Events and Revenue

Tracking Events

Tracking Revenue

Alternative Revenue Event Reporting