iOS – Using the SDK


The following document describes the common use cases for the Kochava SDK after integration is complete. For information on integrating the SDK or configuring and starting the Tracker, refer to our iOS/tvOS SDK Integration support documentation.


Estimated Time to Complete
5 Minutes

After integrating the SDK or creating a new App GUID, we suggest performing these tests to ensure the SDK has been integrated successfully and is functioning as expected within your app.

 

Validate the Install:

The SDK will send an install for the app once, after a fresh install. This test ensures the SDK was configured properly and successfully sent the install to Free App Analytics.

  1. Double check the SDK configuration in code, ensuring the correct App GUID.
  2. Run the app for approximately 30 seconds, which will allow more than enough time for the SDK to start and send an install to Free App Analytics under typical conditions.
  3. Wait a minute or two and visit the Install Feed Validation page for your app within the Free App Analytics dashboard, under Apps & Assets > Install Feed Validation. Within that page, look for the Integration Success! message which indicates integration was successful and that Free App Analytics did receive an install from the SDK. At this point you have confirmed a successful SDK integration and can move ahead to Validate Post Install Events below.
  4. If instead you see a Integration Not Complete! message, wait a few more minutes and refresh the page. After refreshing, if the Integration Not Complete! message persists, double check the following, then repeat this test:
    • Correct App GUID is used within SDK code configuration.
    • Ensure the SDK configuration and startup code is being reached.
    • Ensure the network connection from the test device is not limited behind a firewall or otherwise.

Validate Event Tracking:

If you are tracking user events, you can use this test to ensure the SDK was configured properly and is successfully sending these events to Free App Analytics.

  1. Double check the SDK configuration in code, ensuring the correct App GUID.
  2. Double check your event tracking code and ensure it is reachable.
  3. Launch the app and perform necessary actions within the app to trigger the event(s) you wish to test. After performing these actions, wait 60 seconds to allow more than enough time for the SDK to send these events.
  4. Wait a minute or two and visit the Event Manager page for your app within the Free App Analytics dashboard, under Apps & Assets > Event Manager. Within that page, ensure the tested event names are displayed here, in which case you have confirmed the SDK is successfully tracking these events.
  5. If your event names are not displayed here after waiting a few minutes, double check the following, then repeat this test:
    • Correct App GUID is used within SDK code configuration.
    • Ensure the SDK configuration and startup code is being reached prior to any event code.
    • Ensure the SDK event code is being reached.
    • Ensure the network connection from the test device is not limited behind a firewall or otherwise.

 

Standard Events:

 

Example (Standard Event with Standard Parameters)

 

 

Example (Standard Event with Standard and Custom Parameters)

 

If you wish to use a custom event type with standard parameters, choose the Custom standard event type and then set the customEventNameString property with your desired event name. Be aware that if you choose the Custom type but do not also provide a custom event name, the event name will simply appear as “Custom”.

 

For a detailed list of standard event types and parameters, see: Post Install Event Examples


Custom Events:

 

Example (Send a Custom Event with Only a Name, no Event Data)

 

Example (Send a Custom Event with Event Data)

 

Example (Send a Custom Event with Additional Data)

 

Example (Standard Event of Custom Type with Custom Parameters)


 

 

Developer API Reference:

func sendEvent(withNameString: String, infoString: String?)
func sendEvent(withNameString: String, infoDictionary: [AnyHashable: Any]?)
func send(KochavaEvent)
class KochavaEvent


 

App Store receipts can also be optionally included with your purchase event to be validated server-side by Kochava through the App Store. If desired, include the receipt in your event using the standard parameter appStoreReceiptBase64EncodedString.

 

Example (Standard Purchase Event):

 

Example (Custom Purchase Event with Additional Data):

 

Developer API Reference:

func sendEvent(withNameString: String, infoString: String?)
func sendEvent(withNameString: String, infoDictionary: [AnyHashable: Any]?)
func send(KochavaEvent)
class KochavaEvent


In order to effectively track user subscriptions and free trials, an event should be instrumented at the time of the subscription purchase or start of the free trial along with an accompanying identity link.

When a subscription or free trial begins, first set an identity link for this subscriber and then instrument a standard Subscription or Trial event populated with the following values:

  • Price
  • Currency
  • Product Name
  • User or Subscriber ID (hash suggested)
  • Receipt (if available)

 

BEST PRACTICES: Always set the identity link before sending the event, otherwise the identity link will not be properly associated with the event.

 

Example (Identity Link with Subscription):

 

A free trial is handled in a similar way, although the price should be set to 0 and the event type should indicate Trial rather than Subscription. The product name should remain the same, as the event type indicates whether this was free trial or subscription.

Example (Identity Link with Free Trial):

 


 

Example (Standard Deeplink Event):

 

Example (Custom Deeplink Event with Additional Data):

 

Developer API Reference:

func send(KochavaEvent)
func sendEvent(withNameString: String, infoDictionary: [AnyHashable: Any]?)
class KochavaEvent


Estimated Time to Complete
10 Minutes

Enhanced Deeplinking facilitates the routing of users who are deeplinked into the app, whether through a standard deeplink or deferred deeplink. Re-engagement attribution is also supported for those users. Enhanced Deeplinking is available as of Android native SDK version 3.7.0 and iOS native SDK version 3.12.

Use of this feature consists of these steps:

  1. Acquire a deeplink and Pass it to the SDK.
  2. Wait for the callback and Route the user.

 

Terminology:

Standard Deeplink: A deeplink into an app which is already installed. The app opens (or is already open) and the deeplink is immediately available.

Deferred Deeplink: A deeplink into an app which is not yet installed. In this case, a deeplink-enabled Kochava tracker is clicked, but the user must first install and then launch the app. The deeplink would have been lost during the installation, but Free App Analytics is able to provide you with the original deeplink.

 

Acquire the Deeplink and Pass it to the SDK:

As a first step, acquire any incoming deeplink on launch or at runtime. If no deeplink exists on launch, pass in an empty string to indicate a deferred deeplink may be present. Remember, you do not need to check whether the deeplink is from Free App Analytics or not; the SDK will do this for you.

A timeout, in seconds, may also be specified with the deeplink, which indicates the maximum amount of time to allow the SDK to attempt to process the deeplink. Typical standard deeplink processing should complete in less than 1 second, but if network connectivity is poor the timeout could be reached. Deferred deeplinking typically completes in 3-7 seconds, but could take longer depending on network connection and attribution processing time. We suggest setting a timeout of at least 10 seconds for standard deeplinks and 15 seconds for deferred deeplinks.

NOTE: Ensure you have started the Kochava Tracker SDK before using this feature.

 

Example (Acquire the Deeplink)

 

Example (Acquire a Deferred Deeplink)

NOTE: For iOS, only proceed with deeplink processing if the deeplink is either not empty or this is the first app launch. This will prevent deferred deeplinks from being returned on app launches other than the first. This is reflected in the code sample above.

 

Wait for the Callback and Route the User:

Once the SDK finishes processing the deeplink, a callback will fire which will include the final routing destination for this user. This destination may or may not differ from the original deeplink passed in, but it’s been validated and is now ready to be used. Please note that if the timeout is reached the callback will fire with the unchanged deeplink originally passed in.

If no deeplink was present, an empty string will be returned as the destination.

It is important to understand that if the SDK does not recognize the deeplink as a Free App Analytics deeplink, the deeplink passed in will be returned via the callback unchanged. Because of this, you don’t need to add code to determine whether or not the deeplink is from Free App Analytics before passing it to the SDK; simply pass all deeplinks to the SDK and wait for the callback each time.

 

Example (Wait for the Callback)

 

About Deferred Deeplinking:

By passing an empty string (“”) to the Tracker’s ProcessDeeplink() method, as described in the first example above, the SDK will automatically look for any deferred deeplink from the attribution results and surface it within the callback no differently than a standard deeplink.

This means you do not need to care about where a deeplink is coming from or whether it is deferred or standard. Just pass in the deeplink if it exists or pass in an empty string if it does not, then wait for the callback and route the user.

 

Enhanced Deeplinking vs. Attribution Retrieval:

If you choose to use this Enhanced Deeplinking functionality for deferred deeplinking, you should not also need to use the SDK’s attribution retrieval feature for deferred deeplinking, unless you want to parse the attribution results for another reason. If you do not want Enhanced Deeplinking checking for a deferred deeplink, do not pass an empty string to the SDK when no deeplink exists. Choose one method or the other, but don’t rely on both for deferred deeplinking as you could end up routing the user twice.

One important difference between these two approaches is that Attribution Retrieval has no timeout and will eventually complete, no matter how much time it takes. If, for example, the network connection is bad and attribution results are not able to be retrieved, they would eventually be retrieved once the network connection was restored or even on a future launch. By contrast, Enhanced Deeplinking is designed with user experience in mind, and will only attempt to retrieve a deferred deeplink on the first launch of the first install, and only up to the timeout you specify. If the SDK is able to detect a reinstall, any deferred deeplink from the original install will be ignored. This is because a user would not expect to be routed to a deeplink destination long after the relevant time window had expired or on a future app launch. Imagine clicking a deeplink on a Monday, and being routed on Friday; it would be a confusing experience.

In summary, if you want to parse the raw attribution results yourself, or you do not care about receiving a deferred deeplink after the relevant time window expires, you may use the Attribution Retrieval [Android, iOS] functionality for deferred deeplinking. If you do not care to parse the raw attribution results and you want to receive a deferred deeplink only when relevant, use the Enhanced Deeplinking functionality described here.

 

Example (Set an Identity Link During Tracker Configuration):

 

Example (Set an Identity Link After Starting the Tracker):

 

Developer API Reference:

func sendIdentityLink(with: [AnyHashable: Any])
constant kKVAParamIdentityLinkDictionaryKey
trackerParametersDictionary


 

Example (Configuring the Tracker to Retrieve Attribution):

 

Example (Using the Getter After Attribution Results Have Been Retrieved):

 

The attribution results are provided as an NSDictionary which contains a decoded JSON object. If the attribution failed to attribute (e.g., false) an NSDictionary is created and returned which contains a key which indicates this. If the attribution results have not yet been retrieved, calling the attribution data getter will return nil rather than an NSDictionary object.

 

Developer API Reference:

constant kKVAParamRetrieveAttributionBoolKey
trackerParametersDictionary
KochavaTrackerDelegate
func attributionDictionary() -> String?


 

Example (Getting the Free App Analytics Device ID):

 

 

Developer API Reference:

Tracker.DeviceId


Estimated Time to Complete
1 Minute

If at any time you would like to get the current version of the SDK, call the SDK Version string getter. This will return the full string value of the SDK version, such as “libKochavaTracker 3.7.0”.

 

Example (Getting the SDK Version String)

 

Developer API Reference:

func sdkVersionString() -> String?


 

Example (Enabling App Limit Ad Tracking During Tracker Configuration):

 

Example (Enable App Limit Ad Tracking After Starting the Tracker):

 

Developer API Reference:

constant kKVAParamAppLimitAdTrackingBoolKey
trackerParametersDictionary
func setAppLimitAdTrackingBool(_ appLimitAdTrackingBool: Bool)


 

To enable logging, set the desired log level during tracker configuration. When the tracker runs, each log message will be printed to your console log. In this example we’re setting a higher log level only when a debug build is detected, which is suggested but is not required.

 

Example (Configuring the Tracker with Testing Values):

 

 

Developer API Reference:

Log Levels
constant kKVAParamLogLevelEnumKey
constant kKVAParamLogMultiLineBoolKey
trackerParametersDictionary


 

Example (Enabling Sleep Mode During Tracker Configuration):

 

Example (Enabling Sleep Mode After Starting the Tracker):

 

 

Example (Waking the Tracker from Sleep Mode)

 

 

Developer API Reference:

var sleepBool = false


The SDK can be shut down after starting, which will completely disable the SDK and stop all tracking from continuing.

The SDK should not be shutdown in typical scenarios, but this may be useful during consent-applicable instances when consent has been declined or revoked after starting the SDK and you wish to completely stop tracking the user.

 

Example (Shut Down the SDK)

 

After shutting down, all network communication with Kochava will cease, events will no longer queue, and any API calls will fail just as if the SDK had never been started. The SDK must be configured and started again if you wish for tracking to resume.

 

Shutdown vs. Sleep:

The SDK’s Sleep() functionality can also be used to temporarily prevent the SDK from sending data to Kochava. However, Sleep() will continue to queue events and track the user, but will simply not send that data to Kochava until awoken. For this reason, Sleep() should not be used as a solution for consent-applicable situations because tracking is still queuing locally and may be sent on the next app launch.

Shutting down the SDK, on the other hand, completely stops the SDK from functioning and no tracking will occur until it is configured and started again.


The Kochava SDK does deal with GDPR-sensitive data, such as device identifiers. Care should be taken to ensure that your use of the Kochava SDK remains GDPR compliant when applicable.

GDPR applies to users within the EU and requires users to opt-in to data collection. For common questions and answers regarding both GDPR and CCPA consent models, refer to our Handling Consent support documentation.

 

Intelligent Consent Manager:

As GDPR can present many challenges during development, Free App Analytics offers a fully managed solution for all your GDPR consent requirements through the use of our Intelligent Consent Manager feature. By using this feature the Kochava SDK will handle determining when consent is required for any user while shouldering much the GDPR burden for you. For more information on this feature, see: Intelligent Consent Manager

 

Self Managed Consent:

 

Example (Starting the Tracker Only When Consent Allows)

 

Example (Calling Tracker Methods Only When Consent Allows)

 

NOTE: All consent-related API calls (such as granting or declining consent) will have no effect unless the Intelligent Consent Manager feature has been enabled in code and has also been setup in your Free App Analytics dashboard. Do not use these methods if you are handling consent on your own or through a 3rd party tool.


CCPA applies to users within California and allows users to opt out of the sale of their data.

For purposes of CCPA, the Kochava Tracker SDK follows IAB’s CCPA Compliance Framework by reading the U.S. Privacy String from local storage, when present. The app or any entity within the app can set this string any time.

This means that if IAB’s U.S. Privacy String has been set within the app, the Kochava Tracker SDK will automatically adorn installs and post-install events with it’s value, when present. By doing so, CCPA consent status via the U.S. Privacy String can be associated with all user tracking and syndicated downstream for interested 3rd parties.

You do not need to take any action in the Kochava Tracker SDK for this functionality. However, it is your responsibility to ensure the U.S. Privacy String has been set within local storage when appropriate. The SDK will look for the U.S. Privacy String in local app storage under the key ‘IABUSPrivacy_String’ within default shared preferences on Android and default NSUserDefaults on iOS. As long as the value is present, the SDK will pick it up.

For more information regarding SDK-based solutions for CCPA, refer to our Handling Consent support documentation.

 


Estimated Time to Complete
1 Day

As GDPR can present many challenges during development, Free App Analytics offers a fully managed solution for all your GDPR consent requirements through the use of our Intelligent Consent Manager feature. By using this feature the Kochava SDK will handle determining when consent is required for any user while shouldering much the GDPR burden for you. For complete details on how this feature works, see: Intelligent Consent Manager.


  1. Use an alternate testing App GUID so that your testing activities do not have an impact on your live app analytics.
  2. Enable Logging, if helpful, to gain insight into the SDK’s behavior during runtime.
  3. If you would like the SDK to behave as it would during a new install, be sure to un-install the app before each test.
  4. Test your Free App Analytics integration. For more information see: Testing the Integration.

 

Analyzing SDK Behavior:

 

Developer API Reference:

constant kKVAParamLogLevelEnumKey
constant kKVAParamAppGUIDStringKey
trackerParametersDictionary
func configure(withParametersDictionary: [AnyHashable: Any], delegate: KochavaTrackerDelegate?)

In order to call methods and interact with the Kochava SDK from within a native WebView, see: SDK Utilization from a Web View.


 
 

Last Modified: Jun 25, 2020 at 9:20 am