iOS Quick Start

Current iOS SDK Version 4.12.5

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 framework that you simply 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 6.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 6.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:

Downloading the SDK

The effective size of TUNE SDK for iOS is up to ~1MB when the project iOS deployment target is 6.0 (oldest supported). 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.

Implementation

Install

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.

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

Install Manually

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
    • CoreSpotlight.framework
    • CoreTelephony.framework
    • iAd.framework
    • libz.dylib/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

Code Changes

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

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

@import Tune;
 
- (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;
}

// TuneDelegate protocol deeplink callbacks
// For more information, please see https://developers.tune.com/sdk/implementing-a-deferred-deep-link/#code-platform-ios 
- (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);
}

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.

Testing & Troubleshooting

To test theTUNE 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.

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.

In-App Events

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