Integrate App Analytics for iOS

Follow these steps to integrate the ironSource App Analytics SDK within your application.

Add the App Analytics SDK to your application

CocoaPods

CocoaPods is a dependency manager for Objective-C and Swift; it automates and simplifies the SDK integration process. See the CocoaPods Guide on Getting Started and Using CocoaPods for more information.

To integrate our SDK with Cocoapods, enter the following line in your podfile:

pod 'IronSourceAnalyticsSDK', '0.2.0.0'Light theme
Dark theme
Copy to clipboard

Click here for manual download and integration

Initialize the SDK

Initialize Analytics by using the application key

// Example of initialization
// All settings APIs code goes here

// ironSource App Analytics init API
[IronSourceAnalytics initWithAppKey:YOUR_APP_KEY];Light theme
Dark theme
Copy to clipboard

// Example of initialization
// All settings APIs code goes here

// ironSource App Analytics init API
IronSourceAnalytics.initWithAppKey(YOUR_APP_KEY)Light theme
Dark theme
Copy to clipboard

Parameters

NSString *YOUR_APP_KEY – The application key received from ironSource platform upon app registration

Type restrictions

App Analytics SDK has variable type restrictions that apply throughout all of the SDK (unless specified otherwise) as followed:

Strings: Up to 20 characters, including underscore, space, and period
Int: Positive number between 0 (included) and 1000000 (excluded)
Float: Positive number between 0 (included) and 1000 (excluded)

Variables that are sent with values that break this format will not be included in the App Analytics platform

Update application settings

Important! Some of the APIs rely on your use of the Settings API prior to init, otherwise they won’t work and you won’t see the users’ data in the ironSource platform

In-app purchase settings

This API declares the different packages, categories, and locations of your offers, and enables you to analyze your in-app store performance and get insights on how to improve your revenue.

Use this API prior to init

// Example of adding the packages available in the application
NSArray * iapOffersIDs = [NSArray arrayWithObjects:@"coins_bundle_123", nil];
    [IronSourceAnalytics setIAPSettings:ISAnalyticsPurchasingTypePURCHASE_ITEMS withValues:iapOffersIDs];
// Example of adding the categories of the packages available in the application
NSArray * iapOfferingCategories = [NSArray arrayWithObjects:@"holiday_promotion", nil];
[IronSourceAnalytics setIAPSettings:ISAnalyticsPurchasingTypeITEM_CATEGORIES withValues:iapOfferingCategories];
// Example of adding the locations in the application for purchasing
NSArray * iapOfferingLocations = [NSArray arrayWithObjects:@"out_of_coins_popup", nil];
[IronSourceAnalytics setIAPSettings:ISAnalyticsPurchasingTypePURCHASE_PLACEMENTS withValues:iapOfferingLocations];
// init the ironSource App Analytics SDK
Light theme
Dark theme
Copy to clipboard

// Example of adding the packages available in the application
 let iapOffersIDs : [String] = ["coins_bundle_123"]        
IronSourceAnalytics.setIAPSettings(ISAnalyticsPurchasingType.PURCHASE_ITEMS, withValues: iapOffersIDs)
// Example of adding the categories of the packages available in the application
let iapOfferingCategories : [String] = ["holiday_promotion"]        
IronSourceAnalytics.setIAPSettings(ISAnalyticsPurchasingType.ITEM_CATEGORIES, withValues: iapOfferingCategories)
// Example of adding the locations in the application for purchasing
let iapOfferingLocations : [String] = ["out_of_coins_popup"]     
IronSourceAnalytics.setIAPSettings(ISAnalyticsPurchasingType.PURCHASE_PLACEMENTS, withValues: iapOfferingLocations)
// init the ironSource App Analytics SDK
Light theme
Dark theme
Copy to clipboard

See the full API here

Ad revenue data registration

Registration to ad revenue callback streams the ad impression data on all ads displayed in your application, and enables you to analyze your in-app ads performance and get insights on how to improve your app monetization.

* ironSource analytics only supports the ironSource impression data format.

Click here to learn more on ironSource impression data

// Example of ad revenue usage. Registration pre-init to the relevant mediation callback and pass the impression level revenue data to analytics API
// ironSource mediation Ad revenue callback registration and passing the data to analytics
[IronSource addImpressionDataDelegate:self];
- (void)impressionDataDidSucceed:(ISImpressionData *)impressionData {
    [IronSourceAnalytics updateImpressionData:ISAnalyticsMediationNameIRONSOURCE withImpressionData:impressionData.all_data];
}
// init the ironSource App Analytics SDKLight theme
Dark theme
Copy to clipboard

// Example of ad revenue usage. Registration pre-init to the relevant mediation callback and pass the impression level revenue data to analytics API
// ironSource mediation Ad revenue callback registration and passing the data to analytics
IronSource.addImpressionDataDelegate(self)
func impressionDataDidSucceed(_ impressionData: ISImpressionData!) {
    IronSourceAnalytics.updateImpressionData(mediationName:ISAnalyticsMediationName.IRONSOURCE, impressionData:impressionData.all_Data)
}
 
// init the ironSource App Analytics SDKLight theme
Dark theme
Copy to clipboard

See the full API here

Resources settings

This API declares the different types, locations and user actions, related to the user’s resources, and enables you to analyze your users’ resource balances, spend/receive trends and get insights on how to improve your app economy.

Use this API prior to init

// Example of adding the resources types available in the application
// Add all currencies available in the application
NSArray * appCurrencies = [NSArray arrayWithObjects:@"Coins", nil];

[IronSourceAnalytics setAppResourcesWithResourceType:ISAnalyticsResourceTypeCURRENCIES withValues:appCurrencies];
// Example of adding the locations where users can spend or gain app resources
NSArray * resourcesPlacements = [NSArray arrayWithObjects:@"store", nil];

[IronSourceAnalytics setAppResourcesWithResourceType:ISAnalyticsResourceTypePLACEMENTS withValues:placementsArr];
// Example of adding the actions that lead to spend or gain app resources
NSArray * userActions = [NSArray arrayWithObjects:@"purchased_in_shop", nil];

[IronSourceAnalytics setAppResourcesWithResourceType:ISAnalyticsResourceTypeUSERACTIONS withValues:userActions];
// init the ironSource App Analytics SDKLight theme
Dark theme
Copy to clipboard

// Example of adding the resources types available in the application
// Add all currencies available in the application
let appCurrencies : [String] = ["Coins"]
IronSourceAnalytics.setAppResourcesWith(ISAnalyticsResourceType.CURRENCIES, withValues: iapOfferingLocations)
// Example of adding the locations where users can spend or gain app resources
let resourcesPlacements : [String] = ["store"]
IronSourceAnalytics.setAppResourcesWith(ISAnalyticsResourceType.PLACEMENTS, withValues: resourcesPlacements)
// Example of adding the actions that lead to spend or gain app resources
let userActions : [String] = ["purchased_in_shop"]
IronSourceAnalytics.setAppResourcesWith(ISAnalyticsResourceType.USERACTIONS, withValues: userActions)
// init the ironSource App Analytics SDKLight theme
Dark theme
Copy to clipboard

See the full API here

User ID settings

This API provides the User ID settings API prior to init. It will allow ironSource analytics to add the user id to all user activities & session information

// Example of setting the user ID, given that currentID is the application internal API to get the current user ID
[IronSourceAnalytics setUserId:YOUR_USER_ID];
// init the ironSource App Analytics SDKLight theme
Dark theme
Copy to clipboard

// Example of setting the user ID, given that currentID is the application internal API to get the current user ID
IronSourceAnalytics.setUserId(YOUR_USER_ID)
// init the ironSource App Analytics SDKLight theme
Dark theme
Copy to clipboard

Parameters

NSString * YOUR_USER_ID – The user identification in a string format

Important! User ID is limited to 64 characters, must be alphanumeric, and may include ‘.’ or ‘_’ characters and spaces

User Information settings

This API sets user information such as gender, age, and login type. This will enable you to analyze your app’s KPIs with the users’ attributes and get insights on how to segment your users.

Use this API prior to init

// Example of using the user information settings API
ISAnalyticsMetaData *userGender = [[ISAnalyticsMetaData alloc] initWithGender: ISAnalyticsUserInfoGenderFEMALE];
 
ISAnalyticsMetaData *userIAP = [[ISAnalyticsMetaData alloc] initWithMetaDataKey:ISAnalyticsMetaDataKey.IAP_USER boolValue:true];
 
ISAnalyticsMetaData *userSubscribed = [[ISAnalyticsMetaData alloc] initWithMetaDataKey:ISAnalyticsMetaDataKey.IS_SUBSCRIBED boolValue:true];
 
NSDateFormatter * dateFormatter = [[NSDateFormatter alloc] init] ;
[dateFormatter setDateFormat:@"yyyy-MM-dd"] ;
NSDate *date = [dateFormatter dateFromString:@"2020-01-23"] ;
ISAnalyticsMetaData *userCreationDate = [[ISAnalyticsMetaData alloc] initWithMetaDataKey:ISAnalyticsMetaDataKey.CREATION_DATE dateValue:date];
 
ISAnalyticsMetaData *userFirstLogin = [[ISAnalyticsMetaData alloc] initWithMetaDataKey:ISAnalyticsMetaDataKey.FIRST_LOGIN dateValue:date];
 
ISAnalyticsMetaData *userAchievement = [[ISAnalyticsMetaData alloc] initWithMetaDataKey:ISAnalyticsMetaDataKey.ACHIEVEMENT strValue:@"success"];
 
ISAnalyticsMetaData *userAge = [[ISAnalyticsMetaData alloc] initWithMetaDataKey:ISAnalyticsMetaDataKey.AGE intValue:30];
 
ISAnalyticsMetaData *userLoginType = [[ISAnalyticsMetaData alloc] initWithLoginType:ISAnalyticsUserInfoLoginTypeFACEBOOK];
    
NSArray * userInfo = [NSArray arrayWithObjects:userGender, userIAP, userCreationDate, userSubscribed, userFirstLogin, userAchievement, userAge, userLoginType, nil];
   
// Second, pass the information
[IronSourceAnalytics setUserInfo:userInfo];
// init the ironSource App Analytics SDKLight theme
Dark theme
Copy to clipboard

// Example of using the user information settings API
let userGender : ISAnalyticsMetaData = ISAnalyticsMetaData(gender: ISAnalyticsUserInfoGender.FEMALE)
 
let userIAP : ISAnalyticsMetaData = ISAnalyticsMetaData(metaDataKey: ISAnalyticsMetaDataKey.IAP_USER, boolValue: true)
 
let userSubscribed : ISAnalyticsMetaData = ISAnalyticsMetaData(metaDataKey: ISAnalyticsMetaDataKey.IS_SUBSCRIBED, boolValue: true)
 
let dateFormatter = DateFormatter()
dateFormatter.dateFormat = "yyyy-MM-dd"
guard let date = dateFormatter.date(from: "2020-01-23") else {
  return
}
let userCreationDate = ISAnalyticsMetaData(metaDataKey: ISAnalyticsMetaDataKey.CREATION_DATE, dateValue: date)
 
let userFirstLogin = ISAnalyticsMetaData(metaDataKey: ISAnalyticsMetaDataKey.FIRST_LOGIN, dateValue: date)
 
let userAchievement : ISAnalyticsMetaData = ISAnalyticsMetaData(metaDataKey: ISAnalyticsMetaDataKey.ACHIEVEMENT, strValue: "success")
 
let userAge : ISAnalyticsMetaData = ISAnalyticsMetaData(metaDataKey: ISAnalyticsMetaDataKey.AGE, intValue: 30)
 
let userLoginType : ISAnalyticsMetaData = ISAnalyticsMetaData(loginType: ISAnalyticsUserInfoLoginType.FACEBOOK)
    
let userInfo : [ISAnalyticsMetaData] = [userGender, userIAP, userSubscribed, userAge, userLoginType]
   
// Second, pass the information
IronSourceAnalytics.setUserInfo(userInfo)
// init the ironSource App Analytics SDKLight theme
Dark theme
Copy to clipboard

See the full API here

User privacy settings

This API sets users’ privacy attributes such as data sharing and consent approval, in order to analyze your users and distinguish between different consent status of users.

Use this API prior to init

// Example of using the user privacy settings API, prior to SDK initialization
[IronSourceAnalytics setUserPrivacy:ISAnalyticsPrivacyRestrictionRESTRICTED_DATA isRestricted:true withReason:ISAnalyticsReasonCOPPA];
// init the ironSource App Analytics SDKLight theme
Dark theme
Copy to clipboard

// Example of using the user privacy settings API, prior to SDK initialization
IronSourceAnalytics.setUserPrivacy(ISAnalyticsPrivacyRestriction.RESTRICTED_DATA, isRestricted: true, with: ISAnalyticsReason.COPPA)
// init the ironSource App Analytics SDKLight theme
Dark theme
Copy to clipboard

See the full API here

Update users’ in-app activities

Use these APIs following the initialization to analyze users activities

In-app purchases activity API

This API passes the purchased item, its actual pricing, offer’s locations and more, in order to analyze your in-app purchase performance and get insights on how to improve your revenue

// Example of using the user in-app purchase activity
// Here goes the analytics SDK initialization code, including the in-app purchase settings API
// The in-app purchase update of the user
ISAnalyticsInAppPurchase *coinsBundle123 = [[[[[[ISAnalyticsInAppPurchase alloc] initWithPurchasedItem:@"coins_bundle_123"]fromCategory:@"holiday_promotion"]paid:15.99]purchasedPlacement:@"out_of_coins_popup"]currency:@"USD"];
 
[IronSourceAnalytics updateUserPurchase:coinsBundle123];Light theme
Dark theme
Copy to clipboard

// Example of using the user in-app purchase activity
// Here goes the analytics SDK initialization code, including the in-app purchase settings API
// The in-app purchase update of the user
var coinsBundle123 = ISAnalyticsInAppPurchase(purchasedItem: "coins_bundle_123")
.paid(15.99)
.fromCategory("holiday_promotion")
.currency("USD")
.purchasedPlacement("purchased_in_shop")
IronSourceAnalytics.updateUserPurchase(coinsBundle123)Light theme
Dark theme
Copy to clipboard

See the full API here

Resources usage API

This API passes resources updates made by the user, and includes currency spend or receive, in order to analyze your users’ resource balances, spend/receive trends and get insights on how to improve your app economy

// Example of resource spent by user:
ISAnalyticsResourceUpdate *coins1 = [[[[[ISAnalyticsResourceUpdate alloc] initWithCurrency:@"coins"]consumed:30]placement:@"store"]userAction:@"purchased_in_shop"]balance:0];
 
[IronSourceAnalytics updateUserResources:coins1];
// Example of resource received by user:
ISAnalyticsResourceUpdate *coins2 = [[[[[ISAnalyticsResourceUpdate alloc] initWithCurrency:@"coins"]gained:99]placement:@"level_2_end"]userAction:@"level_completed"]balance:99];
 
[IronSourceAnalytics updateUserResources:coins2];Light theme
Dark theme
Copy to clipboard

// Example of resource spent by user:
var coins1 = ISAnalyticsResourceUpdate(currency: "coins").consumed(30).placement("store").userAction("purchased_in_shop").balance(0)
 
 
IronSourceAnalytics.updateUserResources(coins1)
 
// Example of resource received by user:
var coins2 = ISAnalyticsResourceUpdate(currency: "coins").gained(99).placement("level_2_end").userAction("level_completed").balance(99)
        
IronSourceAnalytics.updateUserResources(coins2)Light theme
Dark theme
Copy to clipboard

See the full API here

Users’ progression and activity updates API

Level progression API

This API passes progression related actions made by the user, and includes level up, level fail and level start, in order to analyze your users’ progression and behavior along the app and get insights on how to improve your user experience and level difficulties

// Examples of using the user progression API:
// Start a level
ISAnalyticsUserProgress *userProgress_start = [[[[ISAnalyticsUserProgress alloc] initWithLevel1:@"level_1"]score:0]state:ISAnalyticsProgressStateBEGIN]attempt:1];
 
[IronSourceAnalytics updateProgress:userProgress_start];
// Complete with score
ISAnalyticsUserProgress *userProgress_score = [[[[ISAnalyticsUserProgress alloc] initWithLevel1:@"level_1"]score:99]state:ISAnalyticsProgressStateCOMPLETE]attempt:1];
 
[IronSourceAnalytics updateProgress:userProgress_score];
// Complete without score
ISAnalyticsUserProgress *userProgress_no_score = [[[[ISAnalyticsUserProgress alloc] initWithLevel1:@"level_1"]score:0]state:ISAnalyticsProgressStateCOMPLETE]attempt:1];
[IronSourceAnalytics updateProgress:userProgress_no_score];
// Failed a level
ISAnalyticsUserProgress *userProgress_fail = [[[[ISAnalyticsUserProgress alloc] initWithLevel1:@"level_1"]score:0]state:ISAnalyticsProgressStateFAILED]attempt:1];
 
[IronSourceAnalytics updateProgress:userProgress_fail];Light theme
Dark theme
Copy to clipboard

// Examples of using the user progression API:
// Start a level
var userProgress_start = ISAnalyticsUserProgress(level1: "level_1").score(0).state(ISAnalyticsProgressState.BEGIN).score(1)
 
IronSourceAnalytics.updateProgress(userProgress_start)
// Complete with score
var userProgress_score = ISAnalyticsUserProgress(level1: "level_1").score(99).state(ISAnalyticsProgressState.COMPLETE).score(1)
 
IronSourceAnalytics.updateProgress(userProgress_score)
// Complete without score
var userProgress_no_score = ISAnalyticsUserProgress(level1: "level_1").score(0).state(ISAnalyticsProgressState.COMPLETE).score(1)
 
IronSourceAnalytics.updateProgress(userProgress_no_score)
// Failed a level
var userProgress_fail = ISAnalyticsUserProgress(level1: "level_1").score(0).state(ISAnalyticsProgressState.FAILED).score(1)
 
IronSourceAnalytics.updateProgress(userProgress_fail)Light theme
Dark theme
Copy to clipboard

Important! The value of the variable “attempt” starts from 1 (not from 0)

See the full API here

Custom activity API

This API passes custom events that enable you to analyze your users’ feature adoptions, flows between screens, and other tailor made events for your app such as clan activity and more

// Examples of using the user progression API:
// 
ISAnalyticsUserActivity *clanActivity = [[ISAnalyticsUserActivity alloc] initWithName:@"clan_window"]property:@"join_clan"];
 
[IronSourceAnalytics updateCustomActivity:clanActivity];Light theme
Dark theme
Copy to clipboard

// Examples of using the user progression API:
var clanActivity = ISAnalyticsUserActivity(name: "clan_window").property("join_clan")
        
IronSourceAnalytics.updateCustomActivity(clanActivity)Light theme
Dark theme
Copy to clipboard

See the full API here

Ad revenue update API

This API updates any ad revenue information received via the impression data callback of your mediation.

* ironSource App Analytics only supports ironSource impression data

// Examples of using the API:
- (void)impressionDataDidSucceed:(ISImpressionData *)impressionData {
    [IronSourceAnalytics updateImpressionData:ISAnalyticsMediationNameIRONSOURCE          withImpressionData:impressionData.all_data];
}Light theme
Dark theme
Copy to clipboard

// Examples of using the API:
func impressionDataDidSucceed(_ impressionData: ISImpressionData!) {
    IronSourceAnalytics.updateImpressionData(mediationName:          ISAnalyticsMediationName.IRONSOURCE, impressionData:impressionData.all_Data)
}Light theme
Dark theme
Copy to clipboard

See the full API here

Manual Download integration of the analytics SDK

Download iOS SDK Version 0.1.0.0
After you download the SDK; unzip it and add IronSourceAnalytics.framework into your Xcode Project.
Go to “Build Phases” section and add the following to “Link Binary With Libraries”:
- libsqlite3.tbd
- UIKit
- CoreTelephony
Enable “Always Embed Swift Standard Libraries”
Go To “General”, “Frameworks, Libraries, and Embedded Content” and set IronSourceAnalytics.framework as “Embed & Sign”
Requires Swift 5.0

Add

#import <IronSourceAnalytics/IronSourceAnalytics.h> //to your m fileLight theme
Dark theme
Copy to clipboard

import IronSourceAnalytics //to your swift fileLight theme
Dark theme
Copy to clipboard