Android Quick Start

Current Android SDK Version 4.12.0

Important Note: The following Quick Start Instructions are applicable for all TUNE customers. Please note that with the Android 4.11.0+ release Smartwhere is included and you will need to Opt in for that if you are an existing TUNE customer.

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

Installing the SDK

Add the Tune SDK as a dependency for your app. You can install the SDK via Gradle or AAR 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.

AAR

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.aar file and create the subproject.
  3. Now that the TuneMarketingConsoleSDK subproject has been created in your project, include it in your app's build.gradle: 
    compile project (':TuneMarketingConsoleSDK')
  4. Install the EventBus library and import it into your project.
    compile 'de.greenrobot:eventbus:2.4.0'
  5. Install the Android Support V4 library and import it into your project.
    compile 'com.android.support:support-v4:24.+'
  6. 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 '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.

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.

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.

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" />

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 {
 
    @Override
    public void onCreate() {
        super.onCreate();
        Tune tune = Tune.init(this, TUNE_ADVERTISER_ID, TUNE_CONVERSION_KEY, true);
    }
}

Enable Smartwhere

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.

Smartwhere is included in the latest TUNE SDK but is disabled by default. To enable Smartwhere call the following method after the TUNE initialization:

        // OPT-IN Enable SmartWhere
        Tune.getInstance().enableSmartWhere();

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();
configuration.grant(TuneSmartwhereConfiguration.GRANT_SMARTWHERE_TUNE_EVENTS);
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.

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.

No Comments

Leave a reply