Integrate App Analytics for Android

Before you start We support Android Operating Systems Version 4.4 (API level 19) and up.

As of App Analytics  SDK 0.3.0.0 we added Kotlin Support. The current Kotlin version is 1.4.10.

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

Add the App Analytics SDK to your application

Gradle dependencies and manual download mechanisms are supported to integrate the App Analytics SDK

Gradle integration

  1. Add the following to your app’s build.gradle file inside repositories section:
    repositories {
        maven {
            url 'https://android-sdk.is.com/'
       }}

  2. Then add the following to the dependencies section:
    dependencies {
        implementation 'com.ironsource:analyticssdk:0.2.0.0' 
    }
    

Click here for manual download and integration

Initialize the SDK 

Initialize App Analytics SDK by using the application key

// Example of initialization
// All settings APIs code goes here
//...
// ironSource App Analytics init API
IronSourceAnalytics.init(this, YOUR_APP_KEY);

Parameters

  • Context context – Either the application context or the current activity
  • 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
ArrayList<String> iapOffersIDs = new ArrayList<>();
iapOffersIDs.add("coins_bundle_123");

IronSourceAnalytics.setIAPSettings(ISAnalyticsPurchasingType.PURCHASE_ITEMS, iapOffersIDs);
// Example of adding the categories of the packages available in the application
ArrayList<String> iapOfferingCategories = new ArrayList<>();
iapOfferingCategories.add("holiday_promotion");

IronSourceAnalytics.setIAPSettings(ISAnalyticsPurchasingType.ITEM_CATEGORIES, iapOfferingCategories);
// Example of adding the locations in the application for purchasing
ArrayList<String> iapOfferingLocations = new ArrayList<>();
iapOfferingLocations.add("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 analytics API
// ironSource mediation Ad revenue callback registration and passing the data to analytics
public static void addImpressionDataListener(ImpressionDataListener listener)

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

import java.util.ArrayList;

// Example of adding the resources types available in the application
// Add all currencies available in the application
List<String> appCurrencies = new ArrayList<>();
appCurrencies.add("Coins");
IronSourceAnalytics.setAppResources(ISAnalyticsResourceType.CURRENCIES, appCurrencies);

// Example of adding the locations where users can spend or gain app resources
List<String> resourcesPlacements = new ArrayList<>();
resourcesPlacements.add("store");
IronSourceAnalytics.setAppResources(ISAnalyticsResourceType.PLACEMENTS, resourcesPlacements);

// Example of adding the actions that lead to spend or gain app resources
List<String> userActions = new ArrayList<>();
userActions.add("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("UserId");
// init the ironSource App Analytics SDK

Parameters

  • String appUserID – 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
ArrayList<ISAnalyticsMetadata> metadataList = new ArrayList<>();
metadataList.add(new ISAnalyticsMetadata(ISAnalyticsMetadataKey.ACHIEVEMENT, "success"));
metadataList.add(new ISAnalyticsMetadata(ISAnalyticsMetadata.GENDER.FEMALE));
metadataList.add(new ISAnalyticsMetadata(ISAnalyticsMetadataKey.IAP_USER,true));
metadataList.add(new ISAnalyticsMetadata(ISAnalyticsMetadataKey.IS_SUBSCRIBED,true));
metadataList.add(new ISAnalyticsMetadata(
ISAnalyticsMetadata.LOGIN_TYPE_VALUE.FACEBOOK));
metadataList.add(new ISAnalyticsMetadata(ISAnalyticsMetadataKey.AGE, 30));
metadataList.add(new ISAnalyticsMetadata(ISAnalyticsMetadataKey.FIRST_LOGIN,new Date()));
metadataList.add(new ISAnalyticsMetadata(ISAnalyticsMetadataKey.CREATION_DATE, new Date()));
// Second, pass the information
IronSourceAnalytics.setUserInfo(metadataList);
// 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 the analytics SDK initialization code, including the in-app purchase settings API

// The in-app purchase update of the user
ISAnalyticsInAppPurchase coinsBundle123 = new ISAnalyticsInAppPurchase("coins_bundle_123").category("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
ISAnalyticsResourceUpdate coins1 = new ISAnalyticsResourceUpdate("Coins").consumed(30).placement("store").userAction("purchased_in_shop").balance(0);
IronSourceAnalytics.updateUserResources(coins1);
// Example of resource received
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 (and 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

// Example of using the user activity API
ISAnalyticsUserActivity clanActivity = new ISAnalyticsUserActivity("clan_window").property("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

// Example of using the API
@Override
   public void onImpressionSuccess(ImpressionData impressionData) {
       JSONObject allData =  impressionData.getAllData();
       IronSourceAnalytics.updateImpressionData(ISAnalyticsMediationName.IRONSOURCE, allData); 
   }

See the full API here

Manual download and integration of the App Analytics SDK

  1. Download the latest SDK version for Android
  2. Import the .AAR file as a library project
  3. If your use Android Studio, download the IronSourceAnalytics.aar file and add it as a dependency to your own module
    1. Go to File ➣ New ➣ New Module ➣ Import .AAR and navigate to the location where the ironSourceAnalytics.aar file has been downloaded
    2. NOTE: ironSource Analytics Manifest Activities are included in the AAR
  4. Add the following to your build.gradle file under the dependencies section:
    implementation project(path: ':IronSourceAnalytics:0.1.0.0')

  5. If you use Kotlin, add Kotlin JARs to your project