iOS Quick Start

Current iOS SDK Version 5.2.1

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; it is compatible with iPhone, iPad, and iPod Touch devices, and both Automatic Reference Counting (ARC) and non-ARC projects on iOS versions 8.0 and above.

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

Follow this Quick Start to get the TUNE SDK up-and-running in no time. If you're upgrading your app from an older MobileAppTracker (MAT) SDK version, then please visit Migrating from MobileAppTracker SDK 2.x to latest 3.x.x OR Migrating from SDK MobileAppTracker 3.x.x to Tune 4.x.x as appropriate. If you’re implementing the TUNE SDK for iOS apps written in the Swift programming language with Xcode 9.0+, then please see our Including Tune iOS Objective-C SDK in a Swift project article.

Supported TMC Solutions

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

  • Attribution Analytics
  • In-App Marketing - In-App Marketing will be shutting down November 1st, 2018. API calls will be removed in Tune iOS SDK v6.0.0. Customers are required to remove all code references to prevent service disruption.
  • App Store Analytics

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 App Store Considerations for more information.

Before you can download the TUNE SDK, make sure to add your app to the TUNE 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.



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 block as follows:

target '<your_project_target>' do 
    pod 'Tune'
to your Podfile and run pod install.

If not already present, then add $(inherited) to "Other Linker Flags" in the Xcode project Build Settings.

Install Manually

Note: While we provide the iOS SDK in the form of a dynamic library, you can build a static library from the source code version using the TuneUniversal_static target.

To install manually, follow the steps below:

  1. Unzip and copy the Tune.framework folder into your source tree.
  2. Add the Tune.framework to your Xcode® project:
    1. At the top of the Project Navigator, click the project name.
    2. On the General tab, scroll down to the bottom to see (Linked Frameworks and Libraries).
    3. To add a new framework, click the “+” sign, and then click Add Other….
    4. Browse to and select the Tune.framework folder, and then click Open.

  3. Add the following additional frameworks to your project:
    • AdSupport.framework
    • CoreLocation.framework
    • CoreSpotlight.framework
    • CoreTelephony.framework
    • iAd.framework
    • libz.tbd
    • MobileCoreServices.framework
    • QuartzCore.framework
    • Security.framework
    • StoreKit.framework
    • SystemConfiguration.framework
    • UserNotifications.framework (only on Xcode 8 to support iOS 10+)
  4. Add the following flags to "Other Linker Flags" in the Xcode project Build Settings.
    -ObjC -lz
  5. Add the Tune.framework to the Embed Frameworks build phases.
  6. Add the following script to the Run Script build phases to strip out simulator slices from the Tune.framework .
    echo "Target architectures: $ARCHS"
    find "$APP_PATH" -name '*.framework' -type d | while read -r FRAMEWORK
    FRAMEWORK_EXECUTABLE_NAME=$(defaults read "$FRAMEWORK/Info.plist" CFBundleExecutable)
    echo "Executable is $FRAMEWORK_EXECUTABLE_PATH"
    echo $(lipo -info "$FRAMEWORK_EXECUTABLE_PATH")
    # remove simulator's archs if location is not simulator's directory
    case "${TARGET_BUILD_DIR}" in
    echo "No need to remove archs"
    if $(lipo "$FRAMEWORK_EXECUTABLE_PATH" -verify_arch "i386") ; then
    lipo -output "$FRAMEWORK_TMP_PATH" -remove "i386" "$FRAMEWORK_EXECUTABLE_PATH"
    echo "i386 architecture removed"
    if $(lipo "$FRAMEWORK_EXECUTABLE_PATH" -verify_arch "x86_64") ; then
    lipo -output "$FRAMEWORK_TMP_PATH" -remove "x86_64" "$FRAMEWORK_EXECUTABLE_PATH"
    echo "x86_64 architecture removed"
    echo "Completed for executable $FRAMEWORK_EXECUTABLE_PATH"
    echo $(lipo -info "$FRAMEWORK_EXECUTABLE_PATH")

Code Changes

First, make sure your app has Enable Modules (C and Objective-C) set to YES in your Build Settings.

Then in your AppDelegate file, import the Tune framework:

@import Tune;
and initialize it:

@interface AppDelegate () <TuneDelegate>
@implementation AppDelegate 

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Account Configuration info - must be set
    [Tune initializeWithTuneAdvertiserId:@"your_advertiser_ID"
    // 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 
- (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);

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 extends the power of the TUNE platform to the real-world. Enabling it unlocks features such as:

  • In-store visit attribution
  • Audience segmentation creation based on the real-world places your app users visit
  • Proximity triggered engagements

To enable Smartwhere make the following call after you have initialized Tune in your AppDelegate.

[Tune enableSmartwhereIntegration];

For users that have previously integrated Smartwhere, you simply need to drop in the new combined SDK and remove the following line from the AppDelegate (the headers  included with Tune now are still relevant):

#import <SmartWhere/SmartWhere.h>

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

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.

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. Bottom line? 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.

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

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 create your Mobile App in TUNE. For information about the advertiser ID and conversion key, please visit Finding Advertiser ID and Conversion Key.
  • Deferred deeplinking functionality is only available in the MAT/TUNE SDK for iOS versions 3.15.0 and above. For information about deferred deeplinking, please visit Implementing a Deferred Deeplink.
  • 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.
  • MAT SDK v3.9+ 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.
  • MAT SDK v3.10.0+ 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 mobile app, make sure you identify the purpose of its use when submitting your app in iTunes Connect. If you decide against collecting IFA, learn about the Implications of Removing Apple’s IFA.
  • MAT SDK v3.10.0+ automatically collects the geo location of the user’s device to help improve location-based user segmentation. The location is collected only when the CoreLocation framework is present and the app has already been permitted to access the geo location. The SDK never requests location access permission from the end user. For more info, please visit Location Auto-Collection.
  • Starting with SDK v3.11.0, you can control the IFA and device-geo-location auto-collection behavior using the corresponding TUNE setters.
  • 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:

Testing & Troubleshooting

  • 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 visit Testing Your Mobile App.
  • There are features of the TuneDelegate protocol that can be useful to make sure events are being measured and transmitted correctly. Please visit Reading Server Responses.

In-App Events

No Comments

Leave a reply