Android Quick Start

Current Android SDK Version 5.2.3

The TUNE SDK for the native Android™ platform provides application session and event logging functionality. The TUNE SDK for Android is available in the form of a single java AAR file that you simply include in your Android project. Our SDK is compatible with all Android devices running Android API 14 and above.

The Android Quick Start is applicable to all TUNE Marketing Console customers.

Important Notes

  • If you’re upgrading your app from TUNE SDK version 3.x to 4.x, then please visit Migrating from SDK 3.x to 4.x.
  • If you are upgrading from TUNE SDK 4.x to 4.8 or above, then please visit Migrating to 4.8.0 and above. If you support Android API 14 and below, please review the Android API 14 and below Getting Started guide.
  • To begin measuring sessions and events, integrate the TUNE SDK for Android with your mobile app. After your first Activity resumes, you can rely on Attribution Analytics to log in-app events (such as purchases, game levels, and any other user engagement).

Supported TMC Solutions

The TUNE SDK for Android supports the following TUNE Marketing Console solutions:

Downloading the SDK

The TUNE SDK for Android is approximately 400 KB in size. Before you can download the TUNE SDK, make sure to add your app to the TUNE platform. The TUNE SDK is also available as an open-source framework with libraries for session and event measurement. To access the open source SDK, please visit GitHub.

Installing the SDK

Add the TUNE SDK as a dependency for your app. You can install both the regular and lite SDK builds via Gradle or AAR distribution.


Install via the TUNE jCenter distribution:

  1. Ensure that jCenter is included as a repository in your Gradle file:
    buildscript {
        repositories {
  2. Add the following line to your Gradle dependency stanza:
    compile 'com.tune:tune-marketing-console-sdk:5.2.3'

This automatically adds the TUNE SDK to your project.


Install via the TUNE SDK AAR distribution:

  1. In Android Studio, go to File -> New -> New Module -> Import .JAR/.AAR Package.
  2. Select the TuneMarketingConsoleSDK-5.2.2.aar file and create the subproject.
  3. Now that the TuneMarketingConsoleSDK-5.2.2 subproject has been created in your project, include it in your app's build.gradle: 
    compile project (':TuneMarketingConsoleSDK-5.2.3')
  4. Include the EventBus library and import it into your project.
    compile 'org.greenrobot:eventbus:3.0.0'
  5. Include the Play Install Referrer library and import it into your project. 
    compile ''
    If you receive an error after adding this dependency, check that your top-level build.gradle contains a reference to
    maven { url "" }
  6. Install the Android Support V4 library and import it into your project.
    compile ''
  7. If you would like to use Smartwhere and you are installing Tune via standalone AAR please see the Smartwhere Integration page.

Code Changes

Google Play Services

Install the Google Play Services SDK and import it into your project in order for the SDK to collect the Google Advertising ID. If you’re using Gradle, you may choose to add only the basement library to your dependencies:

compile ''

Replace X.X.X with the latest version from You can use any version of Google Play Services greater than 4.0.0


  • When integrating the TUNE Android SDK 5.+, it's required that you set your compileSDKVersion to at least 27. It's NOT required to update your targetSDKVersion.
  • If you are already including the full Google Play Services library (compile '') then you do not need to add the -basement subpackage.


If using ProGuard, exclude the TUNE and Google Advertising ID classes from obfuscation in your ProGuard configuration file with the following lines:

-keep public class com.tune.** { public *; }
-keep public class** { *; }
-keep public class** { *; }
-keep public class** { *; }
-keepattributes *Annotation*
-keepclassmembers class ** {
    @org.greenrobot.eventbus.Subscribe <methods>;
-keep enum org.greenrobot.eventbus.ThreadMode { *; }

If you wish to do further optimization, view our article on Avoiding the Dalvik 65K Method Limit.

Android Manifest File

Add the following sections to your AndroidManifest.xml file:

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>     
<application ... >        
    <receiver android:name="com.tune.TuneTracker">        
            <action android:name="" />        

Things to Keep In Mind:

  • TUNE uses the BroadcastReceiver for attribution if your application is running a TUNE SDK version below 4.15.0 and therefore cannot rely on the Google Play App Install Referrer API to return the Install Referrer plus timestamp.
  • If you have multiple SDKs implemented in your Android app that do install attribution, then you may have multiple Android INSTALL_REFERRER receivers as described at Multiple Android Install Referrers.
  • To ensure that the INSTALL_REFERRER is collected properly, please visit our Testing the Google Play Install Referrer article.

Initialize TUNE SDK

Create a new Application class, or update an existing class, to extend from TuneApplication, and initialize the TUNE SDK:

import com.tune.Tune;
public class MyApplication extends TuneApplication {
    public void onCreate() {
        // Initialize TMC
        Tune.init(this, "your_advertiser_ID", "your_conversion_key");

Note: If your Application class already extends another class, you may instead call registerActivityLifecycleCallbacks with TuneActivityLifecycleCallbacks after Tune.init :

import com.tune.Tune;
public class MyApplication extends SomeOtherClass {
    public void onCreate() {
        // Initialize TMC
        Tune.init(this, "your_advertiser_ID", "your_conversion_key");
        if (Build.VERSION.SDK_INT >= 14) {
            // Make sure you register this AFTER Tune.init
            registerActivityLifecycleCallbacks(new TuneActivityLifecycleCallbacks());

Modify the AndroidManifest.xml by adding an android:name field to the <application> tag in order to use the custom Application you created (unless already set).

    android:name=".MyApplication" />

Enable In-App Marketing

To enable In-App Marketing:

In your Application onCreate, call Tune.init with the extra argument turnOnIAM = true

public class MyApplication extends TuneApplication {
    public void onCreate() {
        Tune tune = Tune.init(this, TUNE_ADVERTISER_ID, TUNE_CONVERSION_KEY, true);

In order to leverage in-app campaigns, you also need to add the following to your AndroidManifest.xml file:

<activity android:name=""
                  android:animateLayoutChanges="true" />

Enable Smartwhere

IMPORTANT: Your app must also include the Smartwhere SDK before you can enable the Smartwhere Integration within the TUNE SDK. For more information, please see the Smartwhere developer portal.

The TUNE Marketing Console integration with Smartwhere provides clients with location-based business intelligence by implementing defined geofences to provide insights on "in-store" user engagement for their mobile app. By default Smartwhere is included with the TUNE SDK for version 4.11.1+ . For more information please see our Smartwhere Integration  article.

To enable Smartwhere call the following method after the TUNE initialization:

        // OPT-IN Enable SmartWhere

To optionally expose your TUNE client events to Smartwhere, for example to trigger proximity engagements based on your own custom events, make the following call after enabling Smartwhere:

TuneSmartwhereConfiguration configuration = new TuneSmartwhereConfiguration();
Tune.getInstance().configureSmartwhere(configuration);    // configure must be called AFTER enable

Event sharing

For more information on Smartwhere and event sharing please see our Smartwhere Integration and Smartwhere In Store Event Tracking articles.


SKIP THIS IF your app is distributed only via Google Play. If your app is available in Android app stores other than Google Play, you can continue to collect ANDROID_ID, Device ID, and MAC Address for device identifiers. Pass these identifiers to the TUNE SDK via the following setters after TMC initialization in onCreate.

Android ID 
The ANDROID_ID is auto-collected as a fallback if the Google Advertising ID collection fails (Amazon devices, Google Play Services version older than 4.0). Use the following code if you want to ALWAYS collect it, no matter what.

import android.provider.Settings.Secure;
Tune.getInstance().setAndroidId(Secure.getString(getContentResolver(), Secure.ANDROID_ID));

Device ID
Requires android.permission.READ_PHONE_STATE. The following example uses the .getMeid() method to return the MEID for CDMA. To return the IMEI for GSM, instead use the .getImei() method.

import android.telephony.TelephonyManager;
String deviceId = ((TelephonyManager) getSystemService(Context.TELEPHONY_SERVICE)).getMeid();

MAC Address
Requires android.permission.ACCESS_WIFI_STATE

// WifiManager objects may be null
try {
    WifiManager wm = (WifiManager) getSystemService(Context.WIFI_SERVICE);
} catch (NullPointerException e) {

Things to Keep in Mind

  • The “your_advertiser_ID” and the “your_conversion_key” values correlate with the Advertiser ID and Conversion Key that TUNE provides when you created your Mobile App in TMC. For information about the advertiser ID and conversion key, please see our article Finding Advertiser ID and Conversion Key.
  • Deferred deep linking functionality is only available in the TUNE SDK for Android versions 3.7.0 and above. For information about deferred deep linking, please visit Implementing a Deferred Deep Link.
  • If your app already has a pre-existing user base (people who have already installed your app), TUNE has several options to flag these users as Pre-Existing Users to prevent attributing these users to a marketing partner. For information about migrating existing users, please visit handle existing users prior to SDK implementation.
  • To increase the consistency and ease of attribution, consider collecting device identifiers as described in Unique Identifiers for Attribution.
  • TUNE SDK v4.0+ automatically collects the geo location of the user's device to help improve location-based user segmentation. The location is collected only if the app has already requested and obtained end-user permissions; the TUNE SDK never asks for location access permission from the end-user.

Testing & Troubleshooting

  • To test the TMC SDK implementation in your mobile app, you can do so straight from the MAT platform itself rather than creating a test environment. Please visit our Testing Your Mobile App article.
  • Setting a TuneListener in your app can be useful for when you are integrating the SDK and want to make sure that events are being measured and transmitted correctly. Please visit our Reading Server Responses.


Measuring Events

After you implement the TUNE SDK in your mobile app and start logging sessions, you can move on to logging a wide variety of in-app events such as registrations and in-app purchases.

By logging and analyzing in-app events, you can more efficiently optimize both the functionality of your app and your advertising strategies. Most importantly, understanding how your users interact with your mobile app directly impacts your ability to build effective and profitable advertising campaigns by enabling you to compare retention, engagement, and lifetime value (LTV) to your costs.

To build your own custom event, please visit our Event Builder article.

In-App Events

Achievement Unlocked

Gaining access to additional functionality; generally by completion of a particular event or level.

Add to Cart

Including items in one's virtual shopping cart to be purchased.

Add to Wishlist

Including items in one's virtual list of wanted items not to be readily purchased.

Added Payment Info

Including one's payment information to be used for making purchases.

Checkout Initiated

Starting the checkout process once items have been added to one's cart and ready to complete the purchase.

Content View

Looking at or inspecting content on a page; essentially the rendering of the page.


Requesting someone to do something; for example, a friend invite or an app invite.

Level Achieved

Completing the necessary requirements to move on to the next stage; generally applies to gaming apps.


The process by which an individual gains access to their account by identifying and authenticating themselves.


Completing a purchase transaction in which one has bought an item.


Assigning a value to something according to a particular scale; e.g. 4 stars.


The act or process of entering information about one's self to create an account.


Arranging to have something (such as a table or seat) held for one's use at a later time.


Actively looking for or seeking out something via a keyword.


Giving others access to something; e.g. sending a link online content.

Spent Credits

Applying accumulated rewards/points as payment for an item.

Tutorial Complete

Finishing a lesson or instructions on how to do/achieve something.

No Comments

Leave a reply