Attribution Analytics Mobile SDKs

Many clients leverage TUNE attribution by implementing our native Android SDK and iOS SDK, but you can use any number of other SDK resources to help you implement our attribution analytics and begin making the most of your advertising efforts and conversion metrics.

In addition to supporting Android, iOS & tvOS, Javascript and Windows natively, TUNE offers support for seven extensions/plugins of the most popular development technologies in the mobile advertising industry, as well as a Javascript SDK for HTML 5 apps.

To easily implement the TUNE SDK in your mobile app, we've created quick start guides for all supported platforms:

After you implement the TUNE SDK in your 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.

The Tune SDK natively supports measurement of many In-App Events. To build your own custom event, see Event Builder.

Native SDKs

Android Quick Start

📘

Latest Version

The latest Android SDK is version 6.1.1

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 gradle dependency. Our SDK is compatible with all Android devices running Android API 14 and above and is approximately 128 KB in size.

If you are migrating from an SDK version that includes now deprecated In-App Marketing capabilities, please see Migrating from 5.X.X to 6.X.X.

Installing the SDK with 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:

    api 'com.tune:tune-marketing-console-sdk:6.1.1'
    

This automatically adds the TUNE SDK to your project.

📘

Manual Installation

To manually install the TUNE Android SDK via the AAR distribution, please follow these instructions.

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 ads library to your dependencies:

implementation 'com.google.android.gms:play-services-ads:X.X.X'

Replace X.X.X with the latest version from https://developers.google.com/android/guides/setup. You can use any version of Google Play Services greater than 4.0.0

Notes:

  • When integrating the TUNE Android SDK, 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 (implementation 'com.google.android.gms:play-services:X.X.X') then you do not need to add the -basement subpackage.
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.google.android.gms.ads.identifier.** { *; }

To further reduce the size of the SDK, you can:

-assumenosideeffects class android.util.Log {
    public static boolean isLoggable(java.lang.String, int);
    public static int v(...);
    public static int d(...);
}

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

public class MyApplication extends TuneApplication {
    @Override
    public void onCreate() {
        super.onCreate();

        // Initialize TUNE
        Tune.init(this, "your_advertiser_ID", "your_conversion_key");
    }
}

📘

Set Your Own Values

your_advertiser_ID and your_conversion_key correlate with the Advertiser ID and Conversion Key that TUNE provides when you created your Mobile App in TUNE. For information about the advertiser ID and conversion key, please see our article Finding Advertiser ID and Conversion Key.

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

import com.tune.Tune;
import com.tune.application.TuneActivityLifecycleCallbacks;

public class MyApplication extends SomeOtherClass {
    @Override
    public void onCreate() {
        super.onCreate();

        // Initialize TUNE
        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).

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

Android Javadocs

Source Javadocs can be found at javadoc.io/doc/com.tune/tune-marketing-console-sdk.

iOS Quick Start

📘

Latest Version

The latest iOS SDK is version 6.2.0

The TUNE SDK for the native iOS platform provides application session and event logging functionality. The Tune SDK for iOS is available in the form of a dynamic framework that you include in your iOS project; and support devices on iOS versions 8.0 and above.

Downloading the SDK

The effective size of Tune SDK for iOS is 1.9MB when the project iOS deployment target is 8.0 (oldest supported). This does not account for additional size caused by the Apple App Store encryption process. See Reducing Your App's Size for more information.

  • After your app has been added to the TUNE platform, you can either download and install the SDK yourself, or install the TUNE CocoaPod.

  • The TUNE SDK is also available as an open-source framework with libraries for session and event measurement.

Installing the SDK

There are two methods available to install the TUNE iOS SDK. You can either use Cocoapods or install manually with the instructions below.

Install Using Cocoapods

If you’re using CocoaPods, add pod 'Tune' inside the target..do..end block as follows:

target '<your_project_target>' do
    pod 'Tune'
end

to your Podfile and run pod install.

Install Manually

See Manually Installing the TUNE iOS SDK.

Code Changes

In your AppDelegate file, import the Tune framework:

@import Tune;

and initialize it:

@interface AppDelegate () <TuneDelegate>

@end

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Account Configuration info - must be set
    [Tune initializeWithTuneAdvertiserId:@"your_advertiser_ID"
                       tuneConversionKey:@"your_conversion_key"];

    // Register this class as a deeplink listener to handle deferred deeplinks and Tune Universal Links.
    // This class must conform to the TuneDelegate protocol, implementing the tuneDidReceiveDeeplink: and tuneDidFailDeeplinkWithError: callbacks.
    [Tune registerDeeplinkListener:self];

    // Uncomment this line to enable auto-measurement of successful in-app-purchase (IAP) transactions as "purchase" events
    //[Tune automateIapEventMeasurement:YES];

    return YES;
}

- (void)applicationDidBecomeActive:(UIApplication *)application {
    // Attribution will not function without the measureSession call included
    [Tune measureSession];
}

// Capturing Universal Links
- (BOOL)application:(UIApplication *)application continueUserActivity:(nonnull NSUserActivity *)userActivity restorationHandler:(nonnull void (^)(NSArray * _Nullable))restorationHandler {
    // Check if Tune will handle the Universal Link. If so, the deeplink will be handled in your tuneDidReceiveDeeplink: or tuneDidFailDeeplinkWithError: callback
    BOOL handledByTune = [Tune handleContinueUserActivity:userActivity restorationHandler:restorationHandler];

    // If handledByTune is false, handle the routing yourself
    if (!handledByTune) {
        ...
    }
    return YES;
}

// Capturing deeplinks for iOS >= 9.0
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<NSString*, id> *)options {
    // When the app is opened due to a deep link, call the Tune deep link setter
    [Tune handleOpenURL:url options:options];
    // Take care of the routing yourself here
    ...
    return YES;
}

// Capturing deeplinks for iOS < 9.0
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation {
    // When the app is opened due to a deep link, call the Tune deep link setter
    [Tune handleOpenURL:url sourceApplication:sourceApplication];
    // Take care of the routing yourself here
    ...
    return YES;
}

#pragma mark - TuneDelegate protocol implementation
// For more information, please see https://help.branch.io/developers-hub/docs/attribution-analytics-mobile-sdks#implementing-a-deferred-deep-link
- (void)tuneDidReceiveDeeplink:(NSString *)deeplink {
    NSLog(@"Tune deferred deeplink = %@", deeplink);

    // Handle opening deeplink
    ...
}

- (void)tuneDidFailDeeplinkWithError:(NSError *)error {
    NSLog(@"Tune failed to receive deferred deep link: error = %@", error);
}
@end

📘

Set Your Own Values

your_advertiser_ID and your_conversion_key correlate with the Advertiser ID and Conversion Key that TUNE provides when you create your Mobile App in TUNE. For information about the advertiser ID and conversion key, please visit Finding Advertiser ID and Conversion Key.

Implementing Universal Links

With the release of iOS 9, Apple introduced Universal Links to make the content in your apps discoverable. Essentially, Universal Links makes it easier to deep link users from a web experience into your app experience. For instructions on how to configure your app and web browser to support Universal Links, please read Implementing iOS Universal Links.

tvOS Quick Start

📘

Latest Version

The latest tvOS SDK is version 4.12.2

The TUNE SDK for the native tvOS platform provides application session and event logging functionality. The TUNE SDK for tvOS is available in the form of a framework that you simply include in your tvOS project; it is compatible with Apple TV devices, and both Automatic Reference Counting (ARC) and non-ARC projects on tvOS versions 9.0 and above.

To begin measuring sessions and events, first integrate the TUNE SDK for tvOS with your AppleTV app. After you initiate the measureSession method, you can rely on Attribution Analytics to log in-app events (such as purchases, game levels, and any other user engagement).

If you’re implementing the TUNE SDK for tvOS apps written in the Swift programming language with Xcode 7.1+, see Including TUNE iOS Objective-C SDK in a Swift project.

Supported Solutions

The TUNE SDK for tvOS supports the following solutions:

  • Attribution Analytics
  • App Store Analytics

Downloading the SDK

The effective size of TUNE SDK for tvOS is up to ~1.1MB when the project tvOS deployment target is 9.0. Before you can download the TUNE SDK, make sure to add your app to the Attribution Analytics platform .

After it’s added to the TUNE platform, you can either download and install the SDK yourself, or install the Tune CocoaPod.

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

  1. Unzip and copy the Tune_tvos.framework folder into your source tree.
  2. Add the Tune_tvos.framework to your Xcode project:At the top of the Project Navigator, click the project name.
    1. On the General tab, scroll down to the bottom to see (Linked Frameworks and Libraries).
    2. To add a new framework, click the "+" sign, and then click Add Other….
    3. Browse to and select the Tune_tvos.framework folder, and then click Open.
  3. Add the following additional frameworks to your project:
    • AdSupport.framework
    • MobileCoreServices.framework
    • StoreKit.framework
    • SystemConfiguration.framework
    • UserNotifications.framework (only on iOS 10+)

Once you have added your Apple TV app to the platform, you can download the SDK whenever you like by navigating to Mobile Apps, clicking on the Download SDK button and choosing your app from the drop down menu.

In your AppDelegate.m, import Tune_tvos and initialize it.

#import <MobileAppTracker_tvos/MobileAppTracker.h>
#import <AdSupport/AdSupport.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    // Account Configuration info - must be set
    [Tune initializeWithTuneAdvertiserId:@"your_advertiser_ID"
                       tuneConversionKey:@"your_conversion_key"];

    // Check if a deferred deep link is available and handle opening of the deep link as appropriate in the success tuneDidReceiveDeeplink: callback.
    // Uncomment this line if your MAT account has enabled deferred deep links
    //[Tune checkForDeferredDeeplink:self];

    // Uncomment this line to enable auto-measurement of successful in-app-purchase (IAP) transactions as "purchase" events
    //[Tune automateIapEventMeasurement:YES];

    return YES;
}

- (void)applicationDidBecomeActive:(UIApplication *)application
{
    // MAT will not function without the measureSession call included
    [Tune measureSession];
}

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation
{
    [Tune applicationDidOpenURL:[url absoluteString] sourceApplication:sourceApplication];

    return YES;
}

📘

Set Your Own Values

your_advertiser_ID and your_conversion_key correlate with the Advertiser ID and Conversion Key that TUNE provides when you create your Apple TV App in Attribution Analytics. For information about the advertiser ID and conversion key, please visit Finding Advertiser ID and Conversion Key.

Things to Keep in Mind

The TUNE SDK for tvOS supports automatic measurement of successful in-app-purchase events. This feature can be optionally enabled through the corresponding Tune setter. Once auto-measurement is enabled, you do not need to and should not explicitly measure successful "purchase" events to avoid duplicate event measurement. For more info, please visit IAP Event Measurement.

The TUNE SDK for tvOS automatically collects the Identifier for Advertising (IFA) when AdSupport.framework has been imported. IFA collection improves event attribution on iOS. When you use IFA in your tvOS app, make sure you identify the purpose of its use when submitting your app in App Store Connect. If you decide against collecting IFA, learn about the Implications of Removing Apple’s IFA.

For information about deferred deep linking, see Implementing a Deferred Deep Link.

Javascript Quick Start

📘

Latest Version

The latest Javascript SDK is version 3.10.0

The TUNE SDK for Javascript provides application session and event logging functionality. The Javascript SDK is available in the form of a single .js file that you simply include in your HTML file.

To begin logging sessions and events, first integrate the Javascript SDK with your mobile app. After you initiate the measureSession method, you can log in-app events (such as purchases, game levels, and any other user engagement).

If you're not embedding your HTML5 experience into a native app but instead, are building a stand-alone web experience, use our pixel and cookie tracking method instead.

Supported Solutions

The TUNE SDK for Javascript supports the following solutions:

  • Attribution Analytics
  • App Store Analytics

Downloading the SDK

️ Unavailable

The Javascript SDK is no longer available to download.

Implementation

To implement the downloaded SDK, add the following JavaScript code to your main HTML file:

<script src="https://your.url.here/path/to/attribution-version.js" type="text/javascript"></script>
<script type="text/javascript">
// <![CDATA[
    window.onload = function() {
        MobileAppTracker.init({"advertiserId": "your_advertiser_ID",
                               "conversionKey": "your_conversion_key",
                               "packageName":  "com.example.appname",             // your app's bundle ID
                               "sdkPlatform":  MobileAppTracker.PLATFORM_ANDROID, // or PLATFORM_IOS or PLATFORM_WINDOWS
                               "appVersion": "1"                                  // your app's version string
                               });

        // Set device identifiers here.
        // See https://help.branch.io/developers-hub/docs/attribution-analytics-mobile-sdks#passing-native-device-identifiers-to-javascript.

        // Start measuring session
        MobileAppTracker.measureSession();
    }
// ]]>
</script>

📘

Set Your Own Values

your_advertiser_ID and your_conversion_key correlates with the Advertiser ID that TUNE provides when you create your Mobile App in Attribution Analytics. For information about the advertiser ID, visit Finding Advertiser ID and Conversion Key.

https://your.url.here/path/to/attribution-version.js and com.example.appname should also be set to the URL where the Javascript SDK is hosted on your server and your app's package name.

Things to Keep in Mind

Windows Quick Start

📘

Latest Version

The latest Windows SDK is version 3.6.0

The TUNE SDK for Microsoft Windows provides application session and event logging functionality. This SDK is available in the form of a single DLL file that you simply include in your project. Our SDK is compatible with all Windows-powered devices running Windows Phone 8, Windows 8.1 or Windows 10.

To begin logging sessions, first integrate the Windows SDK with your mobile app. After you initiate the MeasureSession method, you can log in-app events (such as purchases, game levels, and any other user engagement).

Supported Solutions

The TUNE SDK for Windows supports the following solutions:

  • Attribution Analytics
  • App Store Analytics

Downloading the SDK

The TUNE SDK for Windows is 38 KB in size and available via NuGet. Before you implement the TUNE SDK, make sure to add your app to the Attribution Analytics 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

To implement the SDK:

  1. Add the MobileAppTracking NuGet package to your project.

  2. If your app is targeted for WP8, you should instead download the SDK from the MobileAppTracking site and add the WP8 DLL as a reference in your project, along with Json.NET and Bouncy Castle PCL.

  3. Declare a MobileAppTracker object and instantiate it in your app. Where you instantiate a new class is a decision that is unique to your application and code design. Generally, you perform this step during creation of the first page of your app.

using MobileAppTracking;

private MobileAppTracker mobileAppTracker;

public MainPage()
{
    this.InitializeComponent();

    mobileAppTracker = MobileAppTracker.InitializeValues("your_advertiser_id", "your_conversion_key");

    mobileAppTracker.MeasureSession();
}

📘

Set Your Own Values

your_advertiser_ID and your_conversion_key correlate with the Advertiser ID and Conversion Key that MAT provides when you create your Mobile App in MAT. For information about the advertiser ID and conversion key, please visit Finding Advertiser ID and Conversion Key.

  1. Confirm that the package name for your app is the same as the package name specified in MAT. Note that for the store, the package name for your app is set to a new unique value upon publishing, so after you publish, change the package name on the site to match. For testing purposes, set the same "test" value in both the app and MAT.

    On Windows, MAT uses the following values for a package name:

    • Windows Phone 8: WMAppManifest.xml → Product ID
    • Windows Universal: Package.appxmanifest → Package name
  2. For Windows Phone 8, enable the ID_CAP_IDENTITY_DEVICE capability in your WMAppManifest.xml file.

Plugins

Adobe Air Quick Start

📘

Latest Version

The latest Adobe Air plugin is version 5.1.1

The TUNE plugin for Adobe AIR provides application session and event logging functionality via the native TUNE SDKs. The plugin is available in the form of a single .ANE file that you simply include in your AIR project. The AIR plugin is compatible with Flash Builder 4.7 and above, and was compiled using the Apache Flex SDK version 4.16 with AIR 24.0. If you require a different AIR SDK version, please see the GitHub README for build instructions for your version.

To begin logging sessions and events, first integrate the Adobe AIR plugin with your mobile app. After you initiate the measureSession method, you can track in-app events (such as purchases, game levels, and any other user engagement).

Supported Solutions

The TUNE plugin for Adobe AIR supports the following solutions:

  • Attribution Analytics
  • App Store Analytics

Downloading the Plugin

All of our extensions/plugins are open source and available on GitHub.

Before you can download the TUNE plugin for Adobe AIR, add your app to the Attribution Analytics platform.

Implementation

  1. Download the /dist/TuneANE.ane file and copy it into your project folder, if desired.

  2. Add the TuneANE.ane file to your project as a Native Extension to your AIR app: right-click your project, select Properties → Flex Build Path → Native Extensions → Add ANE.

  3. Include the .ane file in your builds by navigating to Properties → Flex Build Packaging → Apple iOS/Google Android → Native Extensions → check the Package box next to TuneANE.ane.

  4. On app startup:

     <![CDATA[
            import com.tune.ane.Tune;
    
            public static var tune:Tune = Tune.instance;
            tune.init("your_advertiser_ID", "your_conversion_key");
    
            // Check if a deferred deeplink is available and handle opening of the deeplink as appropriate in the success tuneDeeplinkCallback: callback.
            // Uncomment these lines if your TUNE account has enabled deferred deeplinks
            // Add event listeners for TUNE_DEEPLINK, TUNE_DEEPLINK_FAILED before checking for deferred deeplinks
            //tune.addEventListener(MobileAppTracker.TUNE_DEEPLINK, tuneDeeplinkCallback);
            //tune.addEventListener(MobileAppTracker.TUNE_DEEPLINK_FAILED, tuneDeeplinkFailedCallback);
            // Check for deferred deeplink
            //tune.checkForDeferredDeeplink();
    
            tune.measureSession();
    ]]>
    

📘

Set Your Own Values

your_advertiser_ID and your_conversion_key correlate with the Advertiser ID and Conversion Key that MAT provides when you create your Mobile App in Attribution Analytics. For information about the advertiser ID and conversion key, see Finding Advertiser ID and Conversion Key.

Android Permissions

If your app supports Android, add the following permissions to your project XML file:

<![CDATA[
            <manifest android:installLocation="auto">
                <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
                <uses-permission android:name="android.permission.INTERNET"/>

                <application>
                    <receiver android:name="com.tune.TuneTracker" android:exported="true">
                        <intent-filter>
                            <action android:name="com.android.vending.INSTALL_REFERRER" />
                        </intent-filter>
                    </receiver>
                </application>
            </manifest>
]]>

Advertising Identifiers

To increase the consistency and ease of attribution, TUNE.ANE automatically collects the Google Advertising ID and Apple Advertising ID device identifiers.

Cocos2dx Quick Start

📘

Latest Version

The latest Cocos2dx plugin is version 2.3.10

The TUNE plugin for Cocos2dx provides application session and event logging functionality via the native TUNE SDKs.

To begin logging sessions and events, first integrate the Cocos2dx plugin with your mobile app. After you initiate the measureSession method, you can log in-app events (such as purchases, game levels, and any other user engagement).

Supported Solutions

The TUNE plugin for Cocos2dx supports the following solutions:

  • Attribution Analytics
  • App Store Analytics

Downloading the Plugin

The TUNE plugin is available via Cocos2dx’s SDKBOX.

Before you integrate the TUNE plugin, make sure to add your app to the Attribution Analytics platform.

Implementation

To implement the downloaded plugin:

  1. From your project folder, import the TUNE SDKBOX plugin:

    sdkbox import tune
    
  2. SDKBOX will output the steps you need to follow from the integration guide in the /doc folder inside the plugin file.

  3. A basic integration will have AppDelegate.cpp look like this:

    #include "AppDelegate.h"
    #include "HelloWorldScene.h"
    #include "PluginTune/PluginTune.h"
    
    USING_NS_CC;
    
    bool AppDelegate::applicationDidFinishLaunching() {
        sdkbox::PluginTune::init();
    
        return true;
    }
    
    // this function will be called when the app is active again
    void AppDelegate::applicationWillEnterForeground() {
        sdkbox::PluginTune::measureSession();
    }
    

Advertising Identifiers

To increase the consistency and ease of attribution, consider collecting device identifiers.

Android
  • In your app’s /proj.android/project.properties, make sure that the path to the Google Play Services SDK is correct.

  • In /proj.android/AndroidManifest.xml, make sure that the manifest contains the follow entry inside the <application> tags:

    <meta-data android:name="com.google.android.gms.version"
               android:value="@integer/google_play_services_version" />
    

When this reference to the Google Play Services library is set up, the TUNE plugin will be able to collect the Google Advertising ID.

iOS

The Apple Advertising ID is automatically collected by the TUNE plugin. It requires you include AdSupport.framework in your iOS project. This is automatically added when installing the TUNE SDKBOX plugin on iOS.

PhoneGap / Cordova Quick Start

📘

Latest Version

The latest PhoneGap / Cordova plugin is version 8.0.0

The TUNE plugin for PhoneGap/Cordova provides application session and event logging functionality via the TUNE native SDKs.

To begin logging sessions and events, first integrate the plugin with your mobile app. After you initiate the measureSession method, you can log in-app events (such as purchases, game levels, and any other user engagement).

Downloading the Plugin

All of our extensions/plugins are open source and available on GitHub. The PhoneGap / Cordova plugin can be found at:

https://github.com/BranchMetrics/phonegap-plugin

The TUNE PhoneGap / Cordova plugin is also available from npm via the Cordova CLI:

cordova plugin add cordova-plugin-tune

Before you can download the TUNE PhoneGap / Cordova plugin, make sure to add your app to the Attribution Analytics platform.

📘

Include Required Dependencies

For iOS apps, please ensure you've included Cocoapods in your implementation as it is a required dependency.

Implementation

  1. Install the plugin into your project.

    $ cordova create MyAwesomeApp
    $ cd MyAwesomeApp
    $ cordova plugin add cordova-plugin-tune
    
  2. Initialize the tracker upon receiving the deviceready event. For example, in a new Cordova project, you would add in onDeviceReady of index.js:

    var app = {
        tune: null,
    
        onDeviceReady: function() {
            app.receivedEvent('deviceready');
    
            app.tune = window.plugins.tunePlugin;
            app.tune.init("your_advertiser_ID", "your_conversion_key");
    
            // Only if you have pre-existing users before TUNE SDK implementation, identify these users
            // using this code snippet.
            // Otherwise, pre-existing users will be counted as new installs the first time they run your app.
            //var isExistingUser = ...
            //if (isExistingUser) {
            //    app.tune.setExistingUser(true);
            //}
    
            app.tune.measureSession();
        },
    };
    

📘

Set Your Own Values

your_advertiser_ID and your_conversion_key correlate with the Advertiser ID and Conversion Key that TUNE provides when you create your Mobile App in TUNE. For information about the advertiser ID and conversion key, please visit Finding Advertiser ID and Conversion Key.

📘

Note

The Android INSTALL_REFERRER receiver is automatically added via plugin.xml

Advertising Identifiers

To increase the consistency and ease of attribution, the TUNE PhoneGap / Cordova plugin collects device identifiers.

Android

The Google Advertising ID is automatically collected by the PhoneGap / Cordova plugin. It requires the following:

iOS

The Apple Advertising ID is automatically collected by the TUNE plugin. It requires the following:

  • Include AdSupport.framework in your iOS project. This is automatically added when installing the TUNE plugin on iOS.

Titanium Quick Start

The TUNE plugin for Titanium provides application session and event tracking functionality via the TUNE native SDKs.

To begin tracking sessions, you must first integrate the Titanium plugin with your app. You may track in-app events – such as purchases, game levels, and any other user engagement – once you have initiated measureSession.

Supported Solutions

The TUNE plugin for Titanium supports the following solutions:

  • Attribution Analytics
  • App Store Analytics

Downloading the Plugin

️ Unavailable

The Titanium Plugin is deprecated as of July 2018 and no longer available for download.

Implementation

var mobileAppTracker = require("ti.mobileapptracker");

mobileAppTracker.initTracker("your_advertiser_ID", "your_conversion_key");

// Only if you have pre-existing users before MAT SDK implementation, identify these users
// using this code snippet.
// Otherwise, pre-existing users will be counted as new installs the first time they run your app.
//var isExistingUser = ...
//if (isExistingUser) {
//    mobileAppTracker.setExistingUser(true);
//}

mobileAppTracker.measureSession();

📘

Set Your Own Values

your_advertiser_ID and your_conversion_key correlate to the Advertiser ID and Conversion Key provided to you when you created the Mobile App (Step 3 in "Create Mobile App") in platform. See Finding Advertiser ID and Conversion Key document for reference.

📘

Note

The Android INSTALL_REFERRER receiver is automatically added via mobile/android/timodule.xml

Advertising Identifiers

To increase the consistency and ease of attribution, the Apple Advertising ID and Google Advertising ID are automatically collected by the Titanium plugin.

Unity Quick Start

📘

Latest Version

The latest Unity plugin is version 7.0.0

The TUNE plugin for Unity provides application session and event logging functionality via the TUNE native SDKs. The TUNE plugin is compatible with Unity 5.3+.

To begin logging sessions and events, first integrate the Unity plugin with your mobile app. After you initiate the MeasureSession method, you can measure in-app events (such as purchases, game levels, and any other user engagement).

📘

Note

Based on your platform, SDK initialization is necessary in the Native app code for Unity initialization. For iOS this is the Delegate class, for Android this is the Application class.

Supported Solutions

The TUNE plugin for Unity supports the following solutions:

  • Attribution Analytics
  • In-App Marketing (Supported in v4.0.0+)
  • App Store Analytics

Downloading the Plugin

All of our extensions/plugins are open source and available on GitHub.

📘

Note

You must also download and install Google's Unity Jar Resolver plugin which resolves dependencies and performs version management.

Before you can download the TUNE plugin for Unity, make sure to add your app to the Attribution Analytics platform.

Implementation

To implement the downloaded plugin:

  1. Open your Unity project.
  2. Go to Assets → Import Package → Custom Package and select the Tune.unitypackage to import.
  3. Attach a new C# script to a GameObject in your main scene.
  4. In your GameObject, click Add Component → New Script.
  5. Edit the new script as follows:
using UnityEngine;
using System.Collections;
using System.Runtime.InteropServices;
using TuneSDK;

public class TuneScript : MonoBehaviour {

    void Awake() {
        Tune.Init("your_advertiser_ID", "your_conversion_key");

        // Check if a deferred deep link is available and handle opening of the deep link as appropriate in the success callback.
        // Uncomment the following line if your TUNE account has enabled deferred deep links
        // Tune.CheckForDeferredDeeplink();

        // Uncomment the following line to enable auto-measurement of successful in-app-purchase (IAP) transactions as "purchase" events
        // Tune.AutomateIapEventMeasurement(true);

        // Measure initial app open
        Tune.MeasureSession();
    }

    void OnApplicationPause(bool pauseStatus) {
        if (!pauseStatus) {
            // Measure app resumes from background
            Tune.MeasureSession();
        }
    }
}

📘

Set Your Own Values

your_advertiser_ID and your_conversion_key correlate with the Advertiser ID and Conversion Key that TUNE provides when you create your Mobile App in Attribution Analytics. For information about the advertiser ID and conversion key, see Finding Advertiser ID and Conversion Key.

For an example implementation, you may refer to the following files:

  • Tune/Scenes/TUNESampleScene.unity
  • Tune/Scripts/TuneSample.cs

Configuration for Android

  • Building on Android will require JDK 1.8. You may tell Unity to use this from the menu option Unity → Preferences → External Tools → JDK.
  • The sample/Assets/Plugins/Android folder includes a working example of AndroidManifest.xml. This example contains the necessary components for the TUNE plugin, simply modify it to suit your needs.

Advertising Identifiers

To increase the consistency and ease of attribution, the TUNE plugin for Unity collects device identifiers.

Android

The Google Advertising ID is automatically collected by the Unity plugin. It requires the following:

  • google-play-services_lib folder or play-services-basement.aar file in Assets/Plugins/Android

  • Special metadata added to the <application> tags in AndroidManifest.xml:

    <meta-data android:name="com.google.android.gms.version"
               android:value="@integer/google_play_services_version" />;
    

These will be automatically present with the above Android installation instructions.

iOS

The Apple Advertising ID is automatically collected by the Unity plugin.

Things to Keep in Mind

  • Deferred deep linking functionality is only available in the TUNE plugin for Unity versions 3.11.0+. For information about deferred deeplinking, please visit Implementing a Deferred Deep Link.
  • TUNE SDK v4.0+ for Android & v3.10+ for iOS 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. For more info, please visit Location Auto-Collection.

Xamarin Quick Start

📘

Latest Version

The latest Xamarin plugin is version 6.0.0

The TUNE plugin for Xamarin provides application session and event measuring functionality via the TUNE native SDKs.

To begin measuring sessions, you must first integrate the Xamarin plugin with your app. You may measure in-app events – such as purchases, game levels, and any other user engagement – once you have initiated measureSession.

Supported Solutions

The TUNE plugin for Xamarin supports the following solutions:

  • Attribution Analytics
  • In-App Marketing
    • Supported in v5.0.0+
  • App Store Analytics

Downloading the Plugin

All of our plugins/extensions are open source and available on GitHub.

It is also available via NuGet:

Before you download the TUNE SDK, make sure to add your app to the Attribution Analytics platform.

Implementation

Android
  1. Open your project in Xamarin Studio.

  2. In Solution view, right click on your project and select Add → Add NuGet Packages…

  3. Search for and add the Tune.Xamarin.Android NuGet package.

  4. Add the Xamarin.Android.Support.v4 NuGet package.

  5. Add the following to your Properties/AndroidManifest.xml:

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    
    <application>
        <receiver android:name="com.tune.TuneTracker" android:exported="true">
            <intent-filter>
                <action android:name="com.android.vending.INSTALL_REFERRER" />
            </intent-filter>
        </receiver>
    </application>
    
  6. Add code to run at startup

    • Create a new class MainApplication.cs and initialize the TUNE SDK in onCreate():

      using TuneSDK;
      
      namespace YourAwesomeApp
      {
          [Application]
          public class MainApplication : Application
          {
              public MainApplication(IntPtr javaReference, JniHandleOwnership transfer) : base(javaReference, transfer)
              {
              }
      
              public override void OnCreate()
              {
                  base.OnCreate();
                  //app init ...
                  Tune tune = Tune.Init(this.ApplicationContext, "your_advertiser_id", "your_conversion_key");
              }
          }
      }
      

    📘

    Set Your Own Values

    your_advertiser_ID and your_conversion_key correlate with the Advertiser ID and Conversion Key that TUNE provides when you create your Mobile App in TUNE. For information about the advertiser ID and conversion key, please see our Finding Advertiser ID and Conversion Key article.

    • Add measure calls to your MainActivity.cs using the Tune SDK instance that you initialized in your Application class:

      using TuneSDK;
      
      namespace YourAwesomeApp
      {
          public class MainActivity : Activity
          {
              protected override void OnResume()
              {
                  Tune.Instance.SetReferralSources(this);
                  Tune.Instance.MeasureSession();
              }
          }
      }
      
iOS
  1. Open your project in Xamarin Studio.

  2. In Solution view, right click on your project and select Add → Add NuGet Packages…

  3. Search for and add the Tune.Xamarin.iOS NuGet package.

  4. Add code to run at startup. For iOS, add to your AppDelegate.cs:

    using TuneSDK;
    
    namespace YourAwesomeApp
    {
        public partial class AppDelegate : UIApplicationDelegate
        {
            public override bool FinishedLaunching(UIApplication app, NSDictionary options)
            {
                Tune.InitTracker("your_advertiser_ID", "your_conversion_key");
    
                // Only if you have pre-existing users before MAT SDK implementation, identify these users
                // using this code snippet.
                // Otherwise, pre-existing users will be counted as new installs the first time they run your app.
                //bool isExistingUser = ...
                //if (isExistingUser) {
                //    Tune.SetExistingUser(true);
                }
    
                Tune.MeasureSession();
            }
        }
    }
    

📘

Set Your Own Values

your_advertiser_ID and your_conversion_key correlate with the Advertiser ID and Conversion Key that TUNE provides when you create your Mobile App in TUNE. For information about the advertiser ID and conversion key, please see our Finding Advertiser ID and Conversion Key article.

Advertising Identifiers

To enable accurate 1-to-1 attribution, we strongly recommend collecting the advertising identifiers.

Android
iOS
  • The Tune.Xamarin.iOS binding includes AdSupport which allows it to auto-collect the Apple Advertising Identifier.

SDK Integrations

Segment Quick Start

Our TUNE integration code is open sourced on GitHub. Feel free to check it out!

Getting Started

Once the Segment library is integrated, toggle TUNE on in your Segment integrations, adding your TUNE Advertiser ID and Conversion Key.

You can integrate TUNE via a server side or mobile integration (iOS and Android).

TUNE supports the identify and track methods.

📘

Note

This documentation is for the TUNE/Segment mobile integration. We recommend clients utilize this client-side integration for the most up-to-date, full-featured, and best supported experience with TUNE.

Additional features supported by the mobile integration include:

  • Facebook attribution
  • Attribution for re-engagement campaigns and deeplinking
  • Customizable event tracking

Identify

When you identify a user, we’ll set that user id in TUNE. If present, the email, phone, and username fields will automatically set corresponding user identifier fields in TUNE, to be sent with any future events.

Track

When you track an event, we will send that event to TUNE. If present, the revenue, currency, orderId, productId, andcategory fields will automatically map to corresponding fields for the event in TUNE.

Integration

Android
  1. Add the TUNE Segment Integration dependency to your app build.gradle:

    compile 'com.tune:tune-segment-integration:+'
    
  2. Add the following permissions to your application’s AndroidManifest.xml:

    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
    
  3. Add TUNE’s referrer receiver to your AndroidManifest.xml inside your app’s <application> tags:

    <application>
          ...
    
          <receiver android:name="com.tune.TuneTracker">
              <intent-filter>
                  <action android:name="com.android.vending.INSTALL_REFERRER" />
              </intent-filter>
          </receiver>
      </application>
    
  4. Declare TUNE’s integration in your Analytics instance:

    Analytics analytics = new Analytics.Builder(getApplicationContext(), "SEGMENT_WRITE_KEY")
        .use(TuneIntegration.FACTORY)
        .build();
    
iOS
  1. Add the TUNE Segment Pod to your Podfile:

    pod 'Segment-Tune'
    
  2. Declare TUNE’s integration in your app delegate instance:

      SEGAnalyticsConfiguration *config = [SEGAnalyticsConfiguration configurationWithWriteKey:@"SEGMENT_WRITE_KEY"];
      [config use:[SEGTuneIntegrationFactory instance]];
      [SEGAnalytics setupWithConfiguration:config];
    
  3. Pass any deep link URLs to TUNE in your app delegate:

    // iOS 9.0+ minimum target
    - (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<NSString *,id> *)options {
    // when the app is opened due to a deep link, call the Tune deep link setter NSString *sourceApplication = options[UIApplicationLaunchOptionsSourceApplicationKey];
    [Tune handleOpenURL:[url absoluteString] sourceApplication:sourceApplication];
    return YES;
    }
    
    // iOS 8.0 minimum target
    - (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation { // when the app is opened due to a deep link, call the Tune deep link setter
    [Tune handleOpenURL:[url absoluteString] sourceApplication:sourceApplication];
    return YES;
    }
    

Settings

Segment lets you change these settings on the Integrations page, without having to touch any code.

Advertiser ID

The Advertiser ID found in your TUNE dashboard, used to identify your account.

Conversion Key

The Conversion Key found in your TUNE dashboard, used to identify your application and encrypt your request data.

📘

Note

Our Segment integration currently does not support In-App Marketing.

Testing, Troubleshooting, and Deployment

  • To test the TUNE SDK implementation in your mobile app, you can do so straight from the TUNE platform itself rather than creating a test environment. Please see Testing Your Mobile App.
  • TuneListener and TuneDelegate can be useful to make sure events are being measured and transmitted correctly. See Reading Server Responses for more information.
  • 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 see handle existing users prior to SDK implementation.
  • When you submit an app to the Apple App Store you may be asked whether your app includes cryptography. The Tune iOS SDK uses Apple's CommonCrypto library to AES encode data that is sent to the server (with 256 bit keys). We also use HTTPS. Please refer to our open source repository if you would like to review the details of how we are handling encryption: https://github.com/BranchMetrics/sdk-release/tree/master/sdk-ios/Tune

Did this page help you?