• iOS

    Migration Guide

    A migration guide for users of the KochavaTracker iOS SDK released prior to 2017, to help understand the changes and make the transition.

    Overview

    Version 3.1.0 is a comprehensive rewrite of the Kochava iOS SDK. Method names were changed, a singleton was provided, standardized keys for configuring the tracker’s parameters dictionary were provided, special considerations were made for Swift such as attributing parameters with nullable and nonnull, along with other changes


    SDK Name

    The name of the standard SDK was changed from “TrackAndAd” to “KochavaTrackeriOS”. Variants of the SDK now have their own unique names. The GameKit variant of the SDK, for example, is now named “KochavaTrackeriOSGK”. The tvOS platform variant of the SDK is named “KochavaTrackerTVOS”. This enables you to identify one SDK variant from another.


    Files

    The files bundled within the SDK changed.

     

    Old:

     

    New:


    Import

    As the name of the main header file changed, so also did the required import.

     

    Old:

     

    New:

     

    To migrate from an older version of the SDK, you should remove the old import and replace it with the new import- in all places where it occurs. Generally this is in your AppDelegate.m file for the purpose of initializing the tracker, however you may add it in numerous other places as well for sending post-install events and accessing other features. For Swift, this import is located in your Objective-C Bridging Header. If you had previously placed this import in your AppDelegate.h header file as opposed to your AppDelegate.m implementation file, it is generally recommended that you move it to your implementation file.


    Delegate Protocol

    The name of the delegate’s protocol changed.

     

    Old:

     

    New:

     

    To migrate from an older version of the SDK, you should replace any reference to the old delegate protocol with the new delegate protocol. If you did not add a protocol conformance added to any of your classes then you do not need to do anything with this.


    Tracker Initialization

    The basic approach to initialize the tracker was replaced.

     

    Old:

     

    New:

     

    To migrate from an older version of the SDK, you should replace your old initialization code with code that uses the newer approach. You may also consider using the non-singleton method which uses a designated initializer, which is documented within the tracker, but that method is not recommended for most installations.

    NOTE: The new code example provided sets the keys for log level and retrieving attribution to show the migration path for these keys, but these are not needed in most installations. If you do not want to select a specific log level or retrieve attribution, it is recommended that you do not set these parameters and allow the SDK to recognize that the defaults should be used.


    Retrieving Attribution Information (Delegate)

    The name of the delegate method for returning attribution information was changed.

     

    Old:

     

    New:

     

    To migrate from an older version of the SDK, you should replace the declaration of the old delegate method with the declaration for the new delegate method. Your logic within your method can stay the same, but the name of the parameter should be changed from the old name to the new name.


    Post-Install Events (Class – Kochava Event)

    The new class KochavaEvent defines an individual post-install event, providing a variety of standardized event names and parameters. Standard event names may represent a purchase, the completion of a level, an achievement, etc. Standard parameters may represent a currency, price, level, etc.

    The use of standard event names and parameters maximizes parity with external analytics partners and ensures optimal reporting and analytical output via the Kochava platform. If the data you are sending through post-install events can be sent using standard event names and parameters we recommend you use an instance of class KochavaEvent directly to do so.

    The class KochavaTracker also provides convenience methods for creating and sending events in one step when the name and information is a simple string or dictionary. For a simple string you may use the instance method sendEvent(withNameString:infoString:), and for a simple dictionary you may use theinstance method sendEvent(withNameString:infoDictionary:).


    Post-Install Events (Info String)

    The method for sending post-install events with a name and a string of information was changed.

     

    Old:

     

    New:

     

    To migrate from an older version of the SDK, you should replace the old method with the new method. For more information, see instance method sendEvent(withNameString:infoString:)

    NOTE: If you are passing a dictionary of information, there is now a convenience method provided for sending an info dictionary (see below).


    Post-Install Events (Info Dictionary)

    The method for sending post-install events with a name and a dictionary of information has changed.

     

    Old:

     

    New:

     

    To migrate from an older version of the SDK, you should replace the old method with the new method. For more information, see instance method sendEvent(withNameString:infoDictionary:)


    Deprecated Symbols

    All of the old symbols were deprecated, and you may use the following list as a reference.

    Symbols
    getKochavaDeviceId

    brief A method to return the device ID generated when the tracker was initialized.

    discussion This method has been deprecated and is scheduled to be permanently removed in v4.0 of this SDK. Please instead use deviceIdString().

    Supported iOS SDK Versions: (undefined) – 3.0

    identityLinkEvent:

    brief A method to queue an Identity Link event to be sent to server.

    param dictionary A dictionary containing key/value pairs to be associated with the app install.

    discussion This method has been deprecated and is scheduled to be permanently removed in v4.0 of this SDK. Please instead use sendIdentityLink(with:)

    Supported iOS SDK Versions: (undefined) – 3.0

    initKochavaWithParams:parametersDictionary:

    discussion This method has been deprecated and is scheduled to be permanently removed in v4.0 of this SDK. Please initialize a tracker either using the shared instance, or else using init?(parametersDictionary:delegate:)

    Supported iOS SDk Versions: (undefined) – 3.0

    initWithKochavaAppId

    discussion A deprecated initialization method for a KochavaTracker. This method is used to configure a newly instantiated KochavaTracker for use when you are not using the provided shared instance.

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

    Supported iOS SDK Versions: (undefined) – 3.0

    Replaced with Symbol(s):

    static var shared

    configure(withParametersDictionary:delegate:)

    init?(parametersDictionary:delegate:)

    retrieveAttribution

    brief A method to return the attribution information previously retrieved from the server (if any).

    discussion The use of this method assumes that the tracker was previously requested to retrieve attribution during its initial initialization. It is intended that this information be passed automatically back to the parent through delegation. This method can be used to re-retrieve the same information, but if it is called before attribution information has been retrieved then the result will be nil. This method has been deprecated and is scheduled to be permanently removed in v4.0 of this SDK. Please instead use attributionDictionary().

    @return a dictionary containing attribution information (or nil).

    Supported iOS SDK Versions: (undefined) – 3.0

    sendDeepLink:sourceApplication:

    brief A method to queue a deep-link and its associated data to be sent to server.

    param url The url received by the openURL application delegate method.

    param sourceApplication The sourceApplication string received by the openURL application delegate method.

    discussion This method has been deprecated and is scheduled to be permanently removed in v4.0 of this SDK. Please instead use sendDeepLink(withOpen:sourceApplicationString:)

    Supported iOS SDK Versions: (undefined) – 3.0

    setLimitAdTracking:

    brief A method to limit ad tracking at the application level.

    discussion This feature is related to the Limit Ad Tracking feature which is typically found on an Apple device under Settings, Privacy, Advertising. In the same way that you can limit ad tracking through that setting, this feature provides a second and independent means for the host app to limit ad tracking by asking the user directly. A value of NO (false) from either feature (this or Apple’s) will result in the limiting of ad tracking.

    param limitAdTrackingBool A boolean toggling app level limit ad tracking on (YES) or off (NO).

    discussion This method has been deprecated and is scheduled to be permanently removed in v4.0 of this SDK. Please instead use setAppLimitAdTrackingBool(_:)

    Supported iOS SDK Versions: (undefined) – 3.0

    trackEvent:value:

    brief A method to queue a post-install event with custom parameters to be sent to server.

    param titleString String containing event title or key of key/value pair.

    param valueString String containing event value or value of key/value pair. Value may be an un-nested (single dimensional) dictionary converted to a JSON formatted string.

    discussion This method has been deprecated and is scheduled to be permanently removed in v4.0 of this SDK. Please instead use sendEvent(withNameString:infoString:)

    Supported iOS SDK Versions: (undefined) – 3.0

    trackEvent:withValue:andReceipt:

    brief A method to queue a post-install event with a receipt to be sent to server.

    param titleString String containing event title or key of key/value pair.

    param valueString String containing event value or value of key/value pair. Value may be an un-nested (single dimensional) dictionary converted to a JSON formatted string.

    param encodedReceiptString String containing an App Store base64 encoded receipt.

    discussion This method has been deprecated and is scheduled to be permanently removed in v4.0 of this SDK. Please instead use sendEvent(withNameString:infoString:appStoreReceiptBase64EncodedString:)

    Supported iOS SDK Versions: (undefined) – 3.0

    trackWatchEvent:value:

    brief A method to queue a post-install Apple Watch event to be sent to server.

    param titleString String containing event title or key of key/value pair.

    param valueString String containing event value or value of key/value pair. Value may be an un-nested (single dimensional) dictionary converted to a JSON formatted string.

    discussion This method has been deprecated and is scheduled to be permanently removed in v4.0 of this SDK. Please instead use sendWatchEvent(withNameString:infoString:)

    Supported iOS SDK Versions (undefined) – 3.0

  • iOS

    Migration Guide

    A migration guide for users of the KochavaTracker iOS SDK released prior to 2017, to help understand the changes and make the transition.

    Overview

    Version 3.1.0 is a comprehensive rewrite of the Kochava iOS SDK. Method names were changed, a singleton was provided, standardized keys for configuring the tracker’s parameters dictionary were provided, special considerations were made for Swift such as attributing parameters with nullable and nonnull, along with other changes


    SDK Name

    The name of the standard SDK was changed from “TrackAndAd” to “KochavaTrackeriOS”. Variants of the SDK now have their own unique names. The GameKit variant of the SDK, for example, is now named “KochavaTrackeriOSGK”. The tvOS platform variant of the SDK is named “KochavaTrackerTVOS”. This enables you to identify one SDK variant from another.


    Files

    The files bundled within the SDK changed.

     

    Old:

     

    New:


    Import

    As the name of the main header file changed, so also did the required import.

     

    Old:

     

    New:

     

    To migrate from an older version of the SDK, you should remove the old import and replace it with the new import- in all places where it occurs. Generally this is in your AppDelegate.m file for the purpose of initializing the tracker, however you may add it in numerous other places as well for sending post-install events and accessing other features. For Swift, this import is located in your Objective-C Bridging Header. If you had previously placed this import in your AppDelegate.h header file as opposed to your AppDelegate.m implementation file, it is generally recommended that you move it to your implementation file.


    Delegate Protocol

    The name of the delegate’s protocol changed.

     

    Old:

     

    New:

     

    To migrate from an older version of the SDK, you should replace any reference to the old delegate protocol with the new delegate protocol. If you did not add a protocol conformance added to any of your classes then you do not need to do anything with this.


    Tracker Initialization

    The basic approach to initialize the tracker was replaced.

     

    Old:

     

    New:

     

    To migrate from an older version of the SDK, you should replace your old initialization code with code that uses the newer approach. You may also consider using the non-singleton method which uses a designated initializer, which is documented within the tracker, but that method is not recommended for most installations.

    NOTE: The new code example provided sets the keys for log level and retrieving attribution to show the migration path for these keys, but these are not needed in most installations. If you do not want to select a specific log level or retrieve attribution, it is recommended that you do not set these parameters and allow the SDK to recognize that the defaults should be used.


    Retrieving Attribution Information (Delegate)

    The name of the delegate method for returning attribution information was changed.

     

    Old:

     

    New:

     

    To migrate from an older version of the SDK, you should replace the declaration of the old delegate method with the declaration for the new delegate method. Your logic within your method can stay the same, but the name of the parameter should be changed from the old name to the new name.

    Post-Install Events (Class – Kochava Event)

    The new class KochavaEvent defines an individual post-install event, providing a variety of standardized event names and parameters. Standard event names may represent a purchase, the completion of a level, an achievement, etc. Standard parameters may represent a currency, price, level, etc.

    The use of standard event names and parameters maximizes parity with external analytics partners and ensures optimal reporting and analytical output via the Kochava platform. If the data you are sending through post-install events can be sent using standard event names and parameters we recommend you use an instance of class KochavaEvent directly to do so.

    The class KochavaTracker also provides convenience methods for creating and sending events in one step when the name and information is a simple string or dictionary. For a simple string you may use the instance method sendEventwithNameString:infoString:, and for a simple dictionary you may use the instance method sendEventWithNameString:infoDictionary:.


    Post-Install Events (Info String)

    The method for sending post-install events with a name and a string of information was changed.

     

    Old:

     

    New:

     

    To migrate from an older version of the SDK, you should replace the old method with the new method. For more information, see instance method sendEventWithNameString:infoString:

    NOTE: If you are passing a dictionary of information, there is now a convenience method provided for sending an info dictionary (see below).


    Post-Install Events (Info Dictionary)

    The method for sending post-install events with a name and a dictionary of information has changed.

     

    Old:

     

    New:

     

    To migrate from an older version of the SDK, you should replace the old method with the new method. For more information, see instance method sendEventWithNameString:infoDictionary:


    Deprecated Symbols

    All of the old symbols were deprecated, and you may use the following list as a reference.

    Symbols
    getKochavaDeviceId

    brief A method to return the device ID generated when the tracker was initialized.

    discussion This method has been deprecated and is scheduled to be permanently removed in v4.0 of this SDK. Please instead use – deviceIdString.

    Supported iOS SDK Versions: (undefined) – 3.0

    identityLinkEvent:

    brief A method to queue an Identity Link event to be sent to server.

    param dictionary A dictionary containing key/value pairs to be associated with the app install.

    discussion This method has been deprecated and is scheduled to be permanently removed in v4.0 of this SDK. Please instead use – sendIdentityLinkWithDictionary:

    Supported iOS SDK Versions: (undefined) – 3.0

    initKochavaWithParams:parametersDictionary:

    discussion This method has been deprecated and is scheduled to be permanently removed in v4.0 of this SDK. Please initialize a tracker either using the shared instance, or else using – initWithParametersDictionary:delegate:

    Supported iOS SDk Versions: (undefined) – 3.0

    initWithKochavaAppId

    discussion A deprecated initialization method for a KochavaTracker. This method is used to configure a newly instantiated KochavaTracker for use when you are not using the provided shared instance.

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

    Supported iOS SDK Versions: (undefined) – 3.0

    Replaced with Symbol(s):

    +shared

    – configureWithParametersDictionary:delegate:

    – initWithParametersDictionary:delegate:

    retrieveAttribution

    brief A method to return the attribution information previously retrieved from the server (if any).

    discussion The use of this method assumes that the tracker was previously requested to retrieve attribution during its initial initialization. It is intended that this information be passed automatically back to the parent through delegation. This method can be used to re-retrieve the same information, but if it is called before attribution information has been retrieved then the result will be nil. This method has been deprecated and is scheduled to be permanently removed in v4.0 of this SDK. Please instead use – attributionDictionary.

    @return a dictionary containing attribution information (or nil).

    Supported iOS SDK Versions: (undefined) – 3.0

    sendDeepLink:sourceApplication:

    brief A method to queue a deep-link and its associated data to be sent to server.

    param url The url received by the openURL application delegate method.

    param sourceApplication The sourceApplication string received by the openURL application delegate method.

    discussion This method has been deprecated and is scheduled to be permanently removed in v4.0 of this SDK. Please instead use – sendDeepLinkWithOpenURL:sourceApplicationString:

    Supported iOS SDK Versions: (undefined) – 3.0

    setLimitAdTracking:

    brief A method to limit ad tracking at the application level.

    discussion This feature is related to the Limit Ad Tracking feature which is typically found on an Apple device under Settings, Privacy, Advertising. In the same way that you can limit ad tracking through that setting, this feature provides a second and independent means for the host app to limit ad tracking by asking the user directly. A value of NO (false) from either feature (this or Apple’s) will result in the limiting of ad tracking.

    param limitAdTrackingBool A boolean toggling app level limit ad tracking on (YES) or off (NO).

    discussion This method has been deprecated and is scheduled to be permanently removed in v4.0 of this SDK. Please instead use – setAppLimitAdTrackingBool:

    Supported iOS SDK Versions: (undefined) – 3.0

    trackEvent:value:

    brief A method to queue a post-install event with custom parameters to be sent to server.

    param titleString String containing event title or key of key/value pair.

    param valueString String containing event value or value of key/value pair. Value may be an un-nested (single dimensional) dictionary converted to a JSON formatted string.

    discussion This method has been deprecated and is scheduled to be permanently removed in v4.0 of this SDK. Please instead use – sendEventWithNameString:infoString:

    Supported iOS SDK Versions: (undefined) – 3.0

    trackEvent:withValue:andReceipt:

    brief A method to queue a post-install event with a receipt to be sent to server.

    param titleString String containing event title or key of key/value pair.

    param valueString String containing event value or value of key/value pair. Value may be an un-nested (single dimensional) dictionary converted to a JSON formatted string.

    param encodedReceiptString String containing an App Store base64 encoded receipt.

    discussion This method has been deprecated and is scheduled to be permanently removed in v4.0 of this SDK. Please instead use – sendEventWithNameString:infoString:encodedReceiptString:

    Supported iOS SDK Versions: (undefined) – 3.0

    trackWatchEvent:value:

    brief A method to queue a post-install Apple Watch event to be sent to server.

    param titleString String containing event title or key of key/value pair.

    param valueString String containing event value or value of key/value pair. Value may be an un-nested (single dimensional) dictionary converted to a JSON formatted string.

    discussion This method has been deprecated and is scheduled to be permanently removed in v4.0 of this SDK. Please instead use – sendWatchEventWithNameString:infoString:

    Supported iOS SDK Versions (undefined) – 3.0

 
 

Last Modified: Jul 12, 2018 at 10:18 am