CONTACT USCONTACT US

Integrate App Analytics for Unity

⚡ Before you start

ironSource App Analytics supports Unity version 2017.2 +, and for iOS Cocoapods must be applied

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

Add the App Analytics SDK to your application

To integrate the App Analytics SDK, use the external dependency manager resolve

Download the App Analytics SDK

  1. Download the latest App Analytics Unity package here
  2. Open your Unity project and import the Unity package
  3. Double-click on the extracted file, the different files will be populated automatically as shown:
  4. Add 
    using IronSourceAnalyticsSDK;
    to your cs file where integrating IronSourceAnalytics

  5. Download Google’s External Dependency Manager from: https://github.com/googlesamples/unity-jar-resolver

    Android

    To apply your changes, make sure you use the “Resolve” process. This will download all relevant artifacts, according to your choices.

    Manual Resolve

    Go to: Assets → External Dependency Manager → Android Resolver → Resolve

    For Main Template Gradle users 

    Instead of downloading the Android artifacts into your project, the artifacts will be added to your gradle file during the compilation. 

    To enable this process, follow these steps: 

    1. Go to: Assets → External Dependency Manager → Android Resolver → Settings
    2. Select “Patch mainTemplate.gradle”
    3. Save your changes, by pressing “OK”

    iOS

    Make sure that Cocoapods is installed:

    Go to: Assets → Play Service Resolver → iOS Resolver → Install Cocoapods

    Use App Analytics integration settings UI

    Create ironSource Analytics’s GameObject, go to: Window -> IronSourceAnalytics -> Create ironSource App Analytics GameObject.

    Then, add the ironSource Analytics GameObject to your starting scene. This is required to handle ironSource App Analytics on game’s launch using the integration settings tool.

    Important! If you already integrated the ironSource App Analytics SDK and you want to use the integration settings tool, remove the following APIs from your code if they are set in the UI:
    • Init using app key – IronSourceAnalytics.init(YOUR_APP_KEY).
    • IAP settings – IronSourceAnalytics.setIAPSettings(ISAnalyticsPurchasingType purchasingType, string[] values)
    • App Resources – setAppResources(ISAnalyticsResourceType resourceType, params string[] values)

    Init using integration settings UI

    To init ironSource App Analytics SDK using the settings you’ve added, call IronSourceAnalytics.initWithUISettings() API manually from your own GameObject.

    Important! Make sure to call the init only after you called other pre-init APIs that you implemented

    Add your app settings using integration settings UI

    Add app key

    Open integration settings tool and place your appkey for each platform separately under Setup tab.

    Add IAP Settings

    Open integration settings tool and add your IAP settings in each section(purchase item, categories and placements).

    Note: Adding an invalid value will prompt an error log in the console, and the value will be replaced by the default

    Add App Resources

    Open integration settings tool and add your App Resources in each section(currencies, placements and user actions).

    Note: Adding an invalid value will prompt an error log in the console, and the value will be replaced by the default

    Initialize the SDK 

    Initialize the App Analytics SDK by using the application key

    // Example of initialization
// All pre-init code goes here
//...
// ironSource App Analytics SDK init API
IronSourceAnalytics.init(YOUR_APP_KEY);

    Parameters

    • string 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
string[] iapOffersIDs = new string[1];
iapOffersIDs[0] = "coins_bundle_123";
IronSourceAnalytics.setIAPSettings(ISAnalyticsPurchasingType.PURCHASE_ITEMS, iapOffersIDs);

// Example of adding the categories of the packages available in the application
string[] iapOfferingCategories = new string[1];
iapOfferingCategories[0] = "holiday_promotion";
IronSourceAnalytics.setIAPSettings(ISAnalyticsPurchasingType.ITEM_CATEGORIES, iapOfferingCategories);

// Example of adding the locations in the application for purchasing
string[] iapOfferingLocations = new string[1];
iapOfferingLocations[0] = "out_of_coins_popup";
IronSourceAnalytics.setIAPSettings(ISAnalyticsPurchasingType.PURCHASE_PLACEMENTS, iapOfferingLocations);
// init the ironSource App Analytics SDK

    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. 

    Register to your mediation ad revenue callback prior to init

    * ironSource App 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 App Analytics API
IronSourceEvents.onImpressionDataReadyEvent += ImpressionDataAdReadyEventIronSourceAnalytics;

    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
string[] appCurrencies = new string[1];
         appCurrencies[0] = "Coins";
IronSourceAnalytics.setAppResources(ISAnalyticsResourceType.CURRENCIES, appCurrencies);

// Add all activities where it is possible to spend or gain app resources
string[] resourcesPlacements = new string[1];
         resourcesPlacements[0] = "store";
IronSourceAnalytics.setAppResources(ISAnalyticsResourceType.PLACEMENTS, resourcesPlacements);

// Add all places where users can spend or gain app resources
string[] userActions = new string[1];
         userActions[0] = "purchased_in_shop";
IronSourceAnalytics.setAppResources(ISAnalyticsResourceType.USERACTIONS, userActions);
// init the ironSource App Analytics SDK

    See the full API here

    User ID settings

    This API provides the User ID settings API prior to init. It will allow ironSource App 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.setAppUserId(YOUR_USER_ID);
// init the ironSource App Analytics SDK

    Parameters

    • string YOUR_USER_ID – The application 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

    using System.Collections.Generic;
// Example of using the user information settings API, prior to sdk initialization
HashSet<ISAnalyticsMetaData> metaDataSet = new HashSet<ISAnalyticsMetaData>
{
    new ISAnalyticsMetaData(ISAnalyticsMetaDataKey.ACHIEVEMENT, "success"),
    new ISAnalyticsMetaData(ISAnalyticsMetaDataKey.FIRST_LOGIN, DateTime.Now),
    new ISAnalyticsMetaData(ISAnalyticsMetaDataKey.CREATION_DATE, DateTime.Now),
    new ISAnalyticsMetaData(ISAnalyticsMetaData.GENDER.FEMALE),
    new ISAnalyticsMetaData(ISAnalyticsMetaData.LOGIN_TYPE_VALUE.FACEBOOK),
    new ISAnalyticsMetaData(ISAnalyticsMetaDataKey.IAP_USER, true),
    new ISAnalyticsMetaData(ISAnalyticsMetaDataKey.IS_SUBSCRIBED, true),
    new ISAnalyticsMetaData(ISAnalyticsMetaDataKey.AGE, 30)
};
IronSourceAnalytics.setUserInfo(metaDataSet);
// init the ironSource App Analytics SDK

    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(ISAnalyticsPrivacyRestriction.RESTRICTED_DATA, true, ISAnalyticsReason.COPPA);
// init the ironSource App Analytics SDK

    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 analytics SDK init code, including the pre-init in-app purchase settings
// The in-app purchase update of the user
ISAnalyticsInAppPurchase coinsBundle123 = new ISAnalyticsInAppPurchase("coins_bundle_123").fromCategory("holiday_promotion").paid(15.99f).purchasedPlacement("out_of_coins_popup").currency("USD");
IronSourceAnalytics.updateUserPurchase(coinsBundle123);

    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 = new ISAnalyticsResourceUpdate("Coins").consumed(30).placement("store").userAction("purchased_in_shop").balance(0);
IronSourceAnalytics.updateUserResources(coins1);
// Example of resource received by user:
ISAnalyticsResourceUpdate coins2 = new ISAnalyticsResourceUpdate("Coins").gained(99).placement("level_2_end").userAction("level_completed").balance(99);
IronSourceAnalytics.updateUserResources(coins2);

    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 = new ISAnalyticsUserProgress("level_1").state(ISAnalyticsProgressState.BEGIN).score(0).attempt(1);
IronSourceAnalytics.updateProgress(userProgress_start);
// Complete with score
ISAnalyticsUserProgress userProgress_score = new ISAnalyticsUserProgress("level_1").state(ISAnalyticsProgressState.COMPLETE).score(99).attempt(1);
IronSourceAnalytics.updateProgress(userProgress_score);
// Complete without score
ISAnalyticsUserProgress userProgress_no_score = new ISAnalyticsUserProgress("level_1").state(ISAnalyticsProgressState.COMPLETE).score(0).attempt(1);
IronSourceAnalytics.updateProgress(userProgress_no_score);
// Failed a level
ISAnalyticsUserProgress userProgress_fail = new ISAnalyticsUserProgress("level_1").state(ISAnalyticsProgressState.FAILED).score(0).attempt(1);
IronSourceAnalytics.updateProgress(userProgress_fail);

    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 = new ISAnalyticsUserActivity("clan_window").attribute("join_clan");
IronSourceAnalytics.updateCustomActivity(clanActivity);

    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

    // ironSource mediation Ad revenue callback registration and passing the data to analytics
private void ImpressionSuccessEventIronSourceAnalytics(IronSourceImpressionData impressionData)
      {
           IronSourceAnalytics.updateImpressionData(ISAnalyticsMediationName.IRONSOURCE, impressionData.allData);
      }

    See the full API here