mParticle Apple SDK

Hello! This is the public repository of the unified mParticle Apple SDK built for the iOS and tvOS platforms.

At mParticle our mission is straightforward: make it really easy for apps and app services to connect and take ownership of your 1st party data. Like most app owners, you end up implementing and maintaining numerous SDKs ranging from analytics, attribution, push notification, remarketing, monetization, etc. However, embedding multiple 3rd party libraries creates a number of unintended consequences and hidden costs.

The mParticle platform addresses all these problems. We support an ever growing number of integrations with services and SDKs, including developer tools, analytics, attribution, messaging, advertising, and more. mParticle has been designed to be the central hub connecting all these services – check our site, or hit us at [email protected] to learn more.

Overview

This document will help you:

Obtain the mParticle SDK via CocoaPods or via Carthage
Extend the mParticle SDK with Kits
Initialize the mParticle SDK

The mParticle SDK is composed of the core library and a series of kit libraries that depend on the core. With each integration with a partner we strive to implement as many features as possible in the server-to-server layer, however some times a deeper integration to work side-by-side with a 3rd party SDK comes with greater benefits to our clients. We use the term Kit to describe such integrations.

The core SDK takes care of initializing the kits depending on what you've configured in your app's dashboard, so you just have to decide which kits you may use prior to submission to the App Store. You can easily include all of the kits, none of the kits, or individual kits – the choice is yours.

Get the SDK

The mParticle-Apple-SDK is available via CocoaPods or via Carthage. Follow the instructions below based on your preference.

CocoaPods

To integrate the SDK using CocoaPods, specify it in your Podfile:

source 'https://github.com/CocoaPods/Specs.git'

# Uncomment the line below if you're using Swift or would like to use dynamic frameworks (recommended but not required)
# use_frameworks!

target '<Your Target>' do
    pod 'mParticle-Apple-SDK', '~> 6'
end

Configuring your Podfile with the statement above will include only the Core mParticle SDK.

If your app targets iOS and tvOS in the same Xcode project, you need to configure the Podfile differently in order to use the SDK with multiple platforms. You can find an example of multi-platform configuration here.

If you'd like to add any kits, you can do so as follows:

source 'https://github.com/CocoaPods/Specs.git'

# Uncomment the line below if you're using Swift or would like to use dynamic frameworks (recommended but not required)
# use_frameworks!

target '<Your Target>' do
    pod 'mParticle-Appboy', '~> 6'
    pod 'mParticle-BranchMetrics', '~> 6'
    pod 'mParticle-Localytics', '~> 6'
end

In the cases above, the Appboy, Branch Metrics, and Localytics kits would be integrated together with the core SDK.

If you are using CocoaPods with use_frameworks! and you plan to use AppsFlyer, comScore, Kahuna, Kochava, or Localytics as a kit, please include the pre_install script below in your Podfile. This is necessary to inform CocoaPods how to properly handle static transitive dependencies:

pre_install do |pre_i|
    def pre_i.verify_no_static_framework_transitive_dependencies; end
end

For iOS only, you can also choose to install the crash reporter by including it as a subspec:

pod 'mParticle-Apple-SDK/CrashReporter', '~> 6'

You can't use the crash reporter at the same time as the Apteligent kit.

Carthage

To integrate the SDK using Carthage, specify it in your Cartfile:

github "mparticle/mparticle-apple-sdk" ~> 6.0

If you'd like to add any kits, you can do so as follows:

github "mparticle-integrations/mparticle-apple-integration-branchmetrics" ~> 6.0

In this case, only the Branch Metrics kit would be integrated; all other kits would be left out.

Currently Supported Kits

Kit	CocoaPods	Carthage
Adjust	✓	✓
Appboy	✓
AppsFlyer	✓
Apteligent	✓
Branch Metrics	✓	✓
Button	✓
comScore	✓
Flurry	✓
Kahuna	✓
Kochava	✓
Localytics	✓
Tune	✓
Wootric	✓

Initialize the SDK

The mParticle SDK is initialized by calling the startWithKey method within the application:didFinishLaunchingWithOptions: delegate call. The mParticle SDK must be initialized with your app key and secret prior to use. Preferably the location of the initialization method call should be one of the last statements in the application:didFinishLaunchingWithOptions:.

Note that it is imperative for the SDK to be initialized in the application:didFinishLaunchingWithOptions: method. Other parts of the SDK rely on the UIApplicationDidBecomeActiveNotification notification to function properly. Failing to start the SDK as indicated will impair it. Also, please do not use GCD's dispatch_async to start the SDK.

Swift

import mParticle_Apple_SDK

func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
    // Other code goes here, prior to initializing the mParticle SDK
    // ...

    MParticle.sharedInstance().startWithKey("<<<App Key Here>>>", secret:"<<<App Secret Here>>>")

    return true
}

Objective-C

For apps supporting iOS 8 and above, Apple recommends using the import syntax for modules or semantic import. However, if you prefer the traditional CocoaPods and static libraries delivery mechanism, that is fully supported as well.

If you are using mParticle as a framework, your import statement will be as follows:

@import mParticle_Apple_SDK;                // Apple recommended syntax, but requires "Enable Modules (C and Objective-C)" in pbxproj
#import <mParticle_Apple_SDK/mParticle.h>   // Works regardless of Enable Modules setting

Otherwise, for CocoaPods without use_frameworks, you can use either of these statements:

#import <mParticle-Apple-SDK/mParticle.h>
#import "mParticle.h"

Next, you'll need to start the SDK:

- (BOOL)application:(UIApplication *)application
        didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Other code goes here, prior to initializing the mParticle SDK
    // ...

    [[MParticle sharedInstance] startWithKey:@"<<<App Key Here>>>"
                                      secret:@"<<<App Secret Here>>>"];

    return YES;
}

If you are migrating to mParticle SDK v6.x from a previous version (4 or 5), please consult the Migration Guide

Example Project with Sample Code

A sample project is provided with the mParticle Apple SDK. It is a multi-platform video streaming app for both iOS and tvOS.

Clone the repository to your local machine

git clone https://github.com/mParticle/mparticle-apple-sdk.git

In order to run either the iOS or tvOS examples, first install the mParticle Apple SDK via CocoaPods.

Change to the Examples/CocoaPodsExample directory
Run pod install
Open Example.xcworkspace in Xcode, select either the iOS_Example or tvOS_Example scheme, build and run. (In case you want to run on iOS 7, please use the iOS7_Example scheme instead)

Just by initializing the SDK you'll be set up to track user installs, engagement, and much more. Check out our doc site to learn how to add specific event tracking to your app.

SDK Documentation

Support

Questions? Have an issue? Consult the Troubleshooting page or contact our Customer Success team at [email protected].

License

The mParticle-Apple-SDK is available under the Apache License, Version 2.0. See the LICENSE file for more info.

isabella232 / mparticle-apple-sdk Goto Github PK