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

    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.onImpressionSuccessEvent += ImpressionSuccessEventIronSourceAnalytics;

    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