Android Quick Start

Current Android SDK Version 4.10.2

Important Note: The following Quick Start Instructions are applicable for all TUNE customers.

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 JAR file that you simply include in your Android project. Our SDK is compatible with all Android devices running Android API 9 and above.

Follow this Quick Start to get the TUNE SDK up-and-running in no time. 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.

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).

Note: If you support Android API 14 and below, please review the Android API 14 and below Getting Started guide.

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 260 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.

Implementation

Add the Tune SDK as a dependency for your app. You can install the SDK via Gradle or JAR distribution.

Gradle

Install via the TUNE jCenter distribution:

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

This automatically adds the TUNE SDK (with associated dependencies) to your project.

JAR

Install via the TUNE SDK JAR distribution:

  1. Copy the TuneMarketingConsoleSDK-x.y.z.jar file to the libs directory for your mobile app. If you’re using Gradle, you may also want to add the libs local folder to your dependencies:
    compile fileTree(dir: 'libs', include: ['*.jar'])
  2. Install the EventBus library and import it into your project.
    compile 'de.greenrobot:eventbus:2.4.0'
  3. Install the Android Support V4 library and import it into your project.
    compile 'com.android.support:support-v4:24.+'

Prerequisites

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 'com.google.android.gms:play-services-basement:10.0.0'

Note: If you are already including the full Google Play Services library (compile 'com.google.android.gms:play-services:10.0.0') then you do not need to add the -basement subpackage. You can use any version of Google Play Services greater than 4.0.0.

Android Manifest File

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).

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">        
        <intent-filter>       
            <action android:name="com.android.vending.INSTALL_REFERRER" />        
        </intent-filter>
    </receiver>
</application>

Note: 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.

ProGuard

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 com.google.android.gms.ads.identifier.** { *; }
-keep public class com.google.android.gms.gcm.** { *; }
-keep public class com.google.android.gms.common.** { *; }
  
-keepclassmembers class ** {
    public void onEvent(**);
}

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

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;
import com.tune.ma.application.TuneApplication;
 
public class MyApplication extends TuneApplication {
    @Override
    public void onCreate() {
        super.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 in your Application’s onCreate:

import com.tune.ma.application.TuneActivityLifecycleCallbacks;
 
public class MyApplication extends SomeOtherClass {
    @Override
    public void onCreate() {
        super.onCreate();

        if (Build.VERSION.SDK_INT >= 14) {
            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).

<application
    android:name=".MyApplication" />

Activities

IF your app supports a minimum SDK version below 14, then you must either extend TuneActivity for each of your Activities OR if your Activity classes already extend another class, you may instead call:  TuneActivity.onStart(Activity activity), and TuneActivity.onResume(Activity activity), and TuneActivity.onStop(Activity activity); in your Activity’s respective lifecycle events:

public class MainActivity extends SomeOtherActivityNotTuneActivity {
    @Override
    public void onStart() {
        super.onStart();
        if (Build.VERSION.SDK_INT < 14) {
            TuneActivity.onStart(this);
        }
    }
  
    @Override
    public void onResume() {
        super.onResume();
        if (Build.VERSION.SDK_INT < 14) {
            TuneActivity.onResume(this);
        }
    }
  
    @Override
    public void onStop() {
        if (Build.VERSION.SDK_INT < 14) {
            TuneActivity.onStop(this);
        }
        super.onStop();
    }
}

IDs

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

import android.telephony.TelephonyManager;
 
String deviceId = ((TelephonyManager) getSystemService(Context.TELEPHONY_SERVICE)).getDeviceId();
Tune.getInstance().setDeviceId(deviceId);

MAC Address
Requires android.permission.ACCESS_WIFI_STATE

import android.net.wifi.WifiManager;
 
// WifiManager objects may be null
try {
    WifiManager wm = (WifiManager) getSystemService(Context.WIFI_SERVICE);
    Tune.getInstance().setMacAddress(wm.getConnectionInfo().getMacAddress());
} 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.

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.

Invite

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.

Login

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

Purchase

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

Rated

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

Registration

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

Reservation

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

Search

Actively looking for or seeking out something via a keyword.

Share

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.

Have a Question? Please contact support@tune.com for technical support.