Support Home > SDK Integration > iOS SDK Integration

iOS SDK Integration

DOCUMENT SUPERSEDED: The information that is contained within this document has been superseded. Refer to the current SDK integration support document for the latest integration instructions and procedures.


The Kochava SDK allows advertisers to integrate a single SDK to leverage the hundreds of ad network and publisher partners integrated with Kochava. This limits the number of 3rd party SDKs required to run a successful UA strategy and greatly reduces complexity during update cycles. Find documentation for other SDKs, plugins, and Server-to-Server Integrations here.

 

Minimum Requirements

  • Xcode 7 – if you are still using Xcode 6 please contact us for a compatible SDK.
  • iOS 6

Integrating the SDK

Make the following additions and project settings changes to your project to use the Kochava Event Tracking Library.

 

  1. From the attached zip, copy the following files into your project’s folder using Finder:
  2.  

  3. Right-clicking on your project in Xcode, select “Add Files to (project name)” and add TrackAndAd.h to your project.
  4. Click on the project name at the top of the Project Navigator in Xcode. Then select Targets on the pane to the right, then “Build Phases” across the top. Click the drop-down titled “Link Binary With Libraries”. If not already listed, using the plus sign, add the following frameworks and libraries. The first several will be found in the main list which appears. The ones at the bottom of the list you will have to add via the “Add Other…” button and locate them in the Kochava Tracker files you downloaded.
    • UIKit.framework
    • Foundation.framework
    • AdSupport.framework
    • iAd.framework
    • CoreLocation.framework
    • SystemConfiguration.framework
    • libTrackAndAd.a

     

  5. In your AppDelegate’s header file, add the following:
  6.  

    Within the @interface section:

     

    Under the @interface section:

     

  7. In your AppDelegate’s source file, add the following:
  8. Under @implementation:

     

    In didFinishLaunchingWithOptions:

     

    NOTE:  This must be prior to “self.window.rootViewController = self.viewController;”, or similar.

     

    In your dealloc method:


Calling the Constructor

By calling the Kochava Constructor, you have completed the basic integration with Kochava. The Constructor should be located in the logic of your application where things first startup.

 

Argument: An initialization dictionary

The initialization dictionary must contain a Kochava App Id.  All other information is optional.  Here is an example of an initialization dictionary:

 

Method: initKochavaWithParams

 

More details on each of the boolean values above can be found in their individual setter method documentation below.

The identityLink dictionary may contain one or two key/value pairs of strings and may be used to associate information with the device. For example, you could associate an internal userid which you want to connect to a user’s service identifier. There is more detailed information below under IdentityLink, which can be called at any time.

You might create your identityLinkDictionary, to be used in initKochavaWithParams, as follows:

 

When this method is called, the Kochava Tracker reports device and app information to Kochava, should those values be different than the last time this information was reported.

 

Data sent by this method:

  • Device type (iPad, iPhone iPod touch)
  • iOS name and version (eg: iPhone OS 4.3.5)
  • Application version (eg: 1.2)
  • Your Kochava application ID
  • The currency in which your application functions (will default to USD)
  • If you’d like to enable console logging of Kochava library events (will default to NO)
  • Limiting app level ad tracking* (is NO by default)

 

NOTE: If you wish to limit ad tracking at the application level, with respect to Kochava conversions, you can turn off ad tracking when you initialize the Kochava library or by an individual method for the purpose of changing the limit ad tracking state, which will be off by default (user opts-in to advertising).

 

(DEPRECATED):

Method: initWithKochavaAppId

Arguments:  kochavaAppId, currency (optional), enableLogging (optional), limitAdTracking (optional), isNewUser (optional)

If you are using the initWithKochavaAppId method currently, please start using initKochavaWithParams instead. If you have questions about initWithKochavaAppId, please forward them to us and we’ll be happy to assist you.

With each installation, Kochava gathers device information and sends it to the Kochava servers for analysis across each installation. Further, this information is ONLY sent in the following situations:

  • Upon initial installation
  • When the application is upgraded
  • When the operating system version is upgraded on the host device

By limiting the times that this information is sent, Kochava is optimizing performance of the SDK and only sending information when changes are made.

 

NOTE: That Kochava persists data in NSUserDefaults. All keys used are prefaced with com.kochava.KochavaTracker. You should be careful not to clear these keys or the SDK may perform unpredictably.


Toggling Console Logging

Console logging will be off by default, unless enabled via either the initial command or the enableConsoleLogging method, which takes only a bool as an argument. If you had enabled console logging when you initialized the library, you can also disable it via this method by passing NO to it.


Toggling Limit-Ad-Tracking

Ad tracking will be on by default, unless disabled via either the initial command or the setLimitAdTracking method, which takes only a bool as an argument.


Calling Event Methods

Sending Kochava post-install events is not a requirement. To track installation information, you do not need to do anything more than call the constructor for the tracker. Still, many advertisers want to understand and correlate the relationship between conversion and attribution source information with post-install behaviors. This can only be done by tracking post-install events.

Once the Constructor is called, Kochava event tracking methods can be called from anywhere within the application. Events will be coupled with the information sent by the Constructor to report events, based on user device and application information.

Events are not sent immediately to Kochava servers but queued, should the device not have connectivity.

 

Standard Events:

Standard events help you to classify information in a way that the Kochava servers will be able to understand and provide tailored reporting.  A standard event is sent by constructing an EventStandardParameters object, configuring it as desired, and then sending it to the tracker using its trackEventWithEventStandardParameters: method.

 

Prototypes –

To create an EventStandardParameter object:

 

To create an event with EventStandardParameters:

 

Sample Code –

 

Custom Events:

Custom events let you send event information beyond the standard parameters provided by the tracker.

 

NOTE: Event names may not be prepended with an underscore, as that convention is reserved for Kochava system events. (i.e. _INSTALL)

NOTE: For examples of post-install events for iOS, refer to our Post-Install Event Examples support documentation.

 

No event pre-registration is required. To instrument an event, simply send an event name via the eventTitle parameter. Optionally, you can also send an eventValue.

Uses of the the optional eventValue parameter could be any of the following:

  • Gather in-app purchase information that can be used for LTV calculation.
  • A JSON formatted string, in which you want to track several data points.
  • Just some other piece of information, paired with the eventTitle.

If the string passed in eventValue is all numeric (and may include a decimal point), Kochava will automatically sum the amounts passed in eventValue for the same eventTitle. For example, if you sent the purchase amount of in-app purchases in eventValue and named eventTitle “IAP – Purchase Price”, Kochava would add up all the purchase amounts for you and present them as a total for “IAP – Purchase Price”.

Regardless of what is passed in eventValue, Kochava’s user dashboard will let you access all the data passed in eventValue for any eventTitle, and present a count of all times trackEvent passed any given eventTitle.

 

NOTE: If you pass a string of JSON represented data, only the root level (no nested chunks) is stored.  Also, a limit of 75 characters is applied for a non-JSON-decodable string passed as an event value.

 

Prototype –

 

Sample Code –

You can call the tracking method from anywhere in your application. It is called by accessing it through the application’s delegate. Note that you’ll need to import your app delegate’s header file at the top of the file from which you call this method.

 

NOTE: In the example below, “Detail View” and “product list” are just examples for a particular scenario. Say an app has a bunch of items listed in a UITableView (like the Settings app on the iPhone). The user taps on one of the items in the list to go to a more detailed view. So the you want to log that the user went to the more detailed view of the product list (which was the item on the table table they tapped on). You might sent this pair of events to indicate the user went to a “Detail View” of the “product list”.


Sending App Store Receipts

Similar to the trackEvent method, a name/value pair with a Base64 encoded string containing an App Store receipt may be sent to Kochava servers.

 

Prototype:

 

NOTE: This event should be called like the trackEvent (normal post-install event), but adds a field for a Base64 encoded string of the App Store Receipt. For more information about retrieving the receipt, refer to Validating Receipts with the App Store support documentation.

NOTE: Sending the App Store Receipts should be used in conjunction with the iOS Purchase event. For an example of the proper format of an iOS Purchase event, refer to our Post-Install Event Examples support documentation.

 

Sample Code:


Sending Spatial Events


Identity Link

IdentityLink events provide the opportunity to “link different identities” together. For example, you may have assigned each user of your app an internal userid which you want to connect to a user’s service identifier. Using the IdentityLink method, you can send both your internal id and their service identifier and connect them in the Kochava database.

Kochava reports can be output to show additional identity information for devices in the Kochava database so that you can supplement your reports with internal identifiers that are useful to you and your application.

Although you can call the identityLink method any time, it is best called just once per data pair being connected and it is your responsibility to know you have or have not made that connection.


Deep Link

Pass deep link events to Kochava using this method. After receiving the URI from your application via openURL:(NSURL *)url sourceApplication: in your application delegate, just pass the url and sourceApplication parameters to the sendDeepLink method. You can learn more about deep linking for iOS here.

 

Starting with iOS 9, you can take advantage of Apple’s Universal Links.  Implementation directions for Universal Links can be found here: https://developer.apple.com/library/ios/documentation/General/Conceptual/AppSearch/UniversalLinks.html

If you are not using Universal Links, you will need to register the URL scheme, taking the following approach:  https://developer.apple.com/library/ios/documentation/iPhone/Conceptual/iPhoneOSProgrammingGuide/Inter-AppCommunication/Inter-AppCommunication.html


Attribution Data Request (Onboarding Links)

Attribution data can be received from Kochava server, usually in less than 10 seconds from the initial application launch. You can receive attribution by a delegate to your host app, by asking for the attribution data at any point, or both. You MUST request attribution data from the server when you initialize the library for either of these approaches to work.

 

If you wish to receive attribution via a delegate, make sure you set the kochavaTracker.trackerDelegate after initializing the library.

 

To receive attribution data via a callback, add the following handler to your application:

 

If you want to ask what attribution data has been retrieved from the server, at any time you can call the getAttributionData method.

 

Sample Payload:

 

sample.attribution.payload

 

With either approach, an NSDictionary will contain the attribution data.

 

Possible return values for the attribution NSDictionary:

  • nil – Either you didn’t indicate when you initialized that you would like to retrieve attribution, or attribution hasn’t yet been determined. Kochava attempts to determine attribution within the first several seconds after the application has been run the first time.
  • Contains a single key/value pair with attribution = false – represents an organic install.
  • Contains a NSDictionary with a variety of attribution information – indicate attribution was made and contains the details of that attribution.

The delegate approach will not return until attribution has been determined and will not return a nil.


Kochava Device ID Retrieval

If you would like to retrieve the Kochava Device ID from the SDK for your own use, you can call the following static method (if a Kochava Device ID has not yet been generated it will return an empty string):


Apple Watch

As the Kochava tracker object exists already in your host application, you will pass data you want to track from the WatchKit Extension to the host application using the openParentApplication method of the WKInterfaceController class. The host application will receive information in your application’s delegate via handleWatchKitExtensionRequest.

 

Associating an Apple Watch With Your Application:

You are responsible for creating a protocol through which you wish to pass information between the WatchKit Extension and the host application, as there might be more information than just what you would track via Kochava. The examples below only illustrate how you might choose to pass this information.

 

In your application delegate, implement the handleWatchKitExtensionRequest to parse the data sent to it, so that it knows it should tell Kochava to associate the Apple Watch with your application. You will tell Kochava to associate the Apple Watch with your application by calling the handleWatchEvents method of the Kochava tracker object.

 

Prototype:

 

Send an Apple Watch Event to Kochava:

After you have associated an Apple Watch to your application, you may optionally send events which occur on the Apple Watch to Kochava for tracking. To do this you send information, again using a protocol you develop, from your WatchKit Extension to your host application.

 

In your application delegate, implement the handleWatchKitExtensionRequest to parse the data sent to it, so that it knows it should send an event to track to Kochava. Likely, you would also pass additional information via the NSDictionary (userInfo), such as specific data you wish to track.

 

Prototype:

 

Kochava’s trackWatchEvent method is processed just like other post-install events and therefore the following applies to them:

  • Event names may not be prepended with an underscore, as that convention is reserved for Kochava system events. (i.e. _INSTALL)
  • No event pre-registration is required.  To instrument an event, simply send an event name via the eventTitle parameter.  Optionally, you can also send an eventValue.
  • Uses of the the optional eventValue parameter could be any of the following:
  • Gather in-app purchase information that can be used for LTV calculation.
  • A JSON formatted string, in which you want to track several data points.
  • Just some other piece of information, paired with the eventTitle.

 

If the string passed in eventValue is all numeric (and may include a decimal point), Kochava will automatically sum the amounts passed in eventValue for the same eventTitle. For example, if you sent the purchase amount of in-app purchases in eventValue and named eventTitle “IAP – Purchase Price”, Kochava would add up all the purchase amounts for you and present them as a total for “IAP – Purchase Price”.

Regardless of what is passed in eventValue, Kochava’s user dashboard will let you access all the data passed in eventValue for any eventTitle, and present a count of all times trackEvent passed any given eventTitle.

 

NOTE: If you pass a string of JSON represented data, only the root level (no nested chunks) is stored. Also there exists a limit of 75 total characters passed in eventValue.


iBeacon Detection

NOTE: iBeacon Detection is not included with the standard Kochava SDK , an iOS SDK capable of iBeacon detection is available upon request. For further information on iBeacon Detection, contact a Kochava account manager.


Swift Support

The Kochava iOS SDK supports the Swift programming language through bridging. You will need to add the following to your Objective-C bridging header file.

 

Information on Objective-C / Swift bridging can be found here: https://developer.apple.com/library/ios/documentation/swift/conceptual/buildingcocoaapps/MixandMatch.html.

 

At the top of your AppDelegate class, make sure the following line exists before any class prototypes:

 

If you want to retrieve attribution from the server, you will also need to add this protocol conformance to your tracker’s parent class:

 

You may now use the Kochava Objective-C SDK methods.  For example, you could now initialize the SDK with this:

 

Post-install events can be called with this:

 

To retrieve attribution back from the server, in addition to setting the retrieveAttribution flag above, the following function would receive the data into your application:


Upload to App Store

NOTE: Around April 26, 2014, Apple modified their automatic code validation surrounding the gathering of the Advertising Identifier (IDFA). The following error indicates a problem with this validation process:

 

“Improper advertising identifier [IDFA] usage. Your app contains the Advertising Identifier [IDFA] API but your app is not respecting the Limit Ad Tracking setting in iOS.”

There have been no instances of the Kochava SDK triggering this error. Kochava’s SDK’s IDFA usage complies with Apple’s guidelines, and Kochava adheres to a user’s Limit Ad Tracking setting. Also, Kochava periodically submits apps with our library integrated to ensure that our SDK passes Apple validation.

 

If this error message appears when you try to submit an app to the app store, alert your Account Manager that you received it, and provide the following information:

  • Version of Kochava’s SDK that you are using
  • Whether or not you checked YES to answer the question, Does this app use the Advertiser Identifier (IDFA)?
  • Whether or not you checked any of the 3 boxes under: This app uses the Advertising Identifier to (select all that apply):
  • What other tracking/conversion SDKs, if any, you are using in your app

 

From this information, we can trouble-shoot.

 

idfauseragreementhd

A. Select the Following


Files For Download

You can download the SDK files below.  

 

Kochava iOS SDK Release Notes

 

NOTE: If a superseded version of the SDK is required, contact your Account Management team for more details.


Game Center Support

The Kochava iOS SDK with Game Center Support will automatically collect your users’ Game Center ID and alias.

In addition to the frameworks listed at the top of this page, you will need to include GameKit.framework in your project.

If you are using Cocoapods, source the Cocoapods trunk and add ‘Kochava-gc’ as a pod.

 

Kochava_iOS_20160921-gc

 


Testing the Integration

For more information on testing the integration with Kochava, refer to our Testing an Integration with Kochava support documentation.

 
 

Last Modified: Sep 1, 2017 at 5:07 pm