Support Home > SDK Integration > SDK – KochavaTracker > Class – KochavaTracker

Class – KochavaTracker

  • Class

    KochavaTracker (iOS/tvOS)

    The class KochavaTracker provides an interface between a host application and Kochava’s Attribution and Analytics Servers. A tracker manages the exchange of data between these two entities, along with the associated tasks and network transactions.


    Overview

    The class KochavaTracker is the main interface for the KochavaTracker SDK. If you have not already integrated a KochavaTracker SDK into your project, refer to our KochavaTracker iOS SDK support documentation.

    You rarely create instances of the KochavaTracker class. Instead, you configure a provided shared instance using the designated configuration instance method configure(withParametersDictionary:delegate:).

    From there, the tracker proceeds to initialize immediately and perform its various tasks. This is typically done during the earliest phases of the host’s life-cycle, so that installation attribution can be quickly established and post-install events may immediately begin to be queued.

    You may alternately create an instance of the KochavaTracker class. If you do, it is your responsibility to maintain a strong reference. And if you create multiple instances, it is your responsibility to configure each with a unique storage identifier.

    Initialization and Configuration

    By initializing and configuring a KochavaTracker, you are completing the basic integration with a KochavaTracker SDK. This should be done in the logic of your application where things first start up, such as in your UIApplicationDelegate class’ application(_:didFinishLaunchingWithOptions:) method. You may do this on the main thread, or else on a background thread with iOS SDK v3.1.5 or higher.

     

    1. Import the KochavaTracker SDK’s main header file.
    2. The name of this header file may vary depending on the SDK variant you are using. For Objective-C, you will typically import this file inside of your UIApplicationDelegate class’ implementation file. For Swift, this requirement will have been resolved when you integrated a KochavaTracker SDK variant into your project and imported this file inside of your Objective-C bridging header.

    3. Configure the provided shared instance.
    4. The provided shared instance instance is automatically allocated and initialized (lazily), enabling it to gracefully report and handle unexpected activity prior to the designated configuration method having been called. To configure it, first create a trackerParametersDictionary, and then perform the configuration using the designated configuration instance method configure(withParametersDictionary:delegate:).

       

      Sample Code:

       

    5. Alternate Step – Create and Initialize a New Instance
    6. You may alternatively create and initialize a new instance using the designated initialization method init?(parametersDictionary:delegate:). Using the provided shared instance is recommended for most integrations; however, a designated initialization method is provided for when the provided shared instance may not be suitable. The primary use-case for the designated initialization method is when multiple instances of the tracker are desired. For more information concerning multiple instances see constant kKVAParamStorageIdStringKey. Perform the initialization using the method initWithParametersDictionary:delegate: For a complete list of the supported parameters refer to dictionary trackerParametersDictionary.

       

      Sample Code:

     

    Sending Post-Install Events

    Sending post-install events (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 tracker has been configured, Kochava event tracking methods can be called from anywhere within the application. Events will be coupled with the information sent by the tracker 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.

    There are a variety of methods which can be used to send post-install events, depending on the kind of information you are tracking. If the information you have can be expressed in the standardized parameters of a class KochavaEvent object, it is recommended that you create one and send it to the instance method send(_:). If the information cannot be expressed in the standardized parameters of KochavaEvent. It is recommended that you next use instance method sendEvent(withNameString:infoDictionary:). If you need to only send an event name and a string of associated information (or no information at all), you may use the generic method instance method sendEvent(withNameString:infoString:).

    Retrieving Attribution

    Attribution information is assessed and stored within Kochava’s Servers, where it is reported back to you through your Kochava’s account.

    You may also retrieve this information from within your app.

    NOTE: Retrieving the information within your app should only be done if your app makes use of this information, otherwise it causes needless network communication.

    Attribution will performed server-side regardless of the application requesting the results. The tracker will retrieve attribution information if the kKVAParamRetrieveAttributionBoolKey parameter is passed with a value of true during its configuration. It does this usually within about 10 seconds from the initial launch, although it is subject to a variety of conditions which can cause this time interval to be longer. Once attribution information has been retrieved, the result is cached locally. If the KochavaTrackerDelegate instance method tracker(_:didRetrieveAttributionDictionary:) is implemented, it will then also be called and the attribution information is passed as a parameter. Later you may also use the instance method attributionDictionary() method to retrieve the cached information again.

    Requirement(s)

    NSUserDefaults

    The KochavaTracker stores its own information within the same sandbox as its host, and it persists this information in NSUserDefaults standard user defaults. You should be careful not to clear these keys, or the tracker may perform unpredictably. All of the trackers keys are prefaced with “com.kochava.KochavaTracker”. If you wish to remove NSUserDefaults, please be sure to exclude any keys which begin with this prefix.

    Using the Advertising Identifier (IDFA)

    The KochavaTracker class makes use of the Advertising Identifier (IDFA) in order to attribute the host installation to a previously served advertisement. The App Store submission process includes a disclosure concerning the use of the IDFA, whereby you will be asked to note that you use it. For more information see the FAQ concerning IDFA.



    • Why am I getting the error: “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.”

      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.

       

      A. Select for Following.

    Testing the Integration

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

    Symbols

    Getting a Shared Kochava Tracker static var shared

    Returns a shared singleton KochavaTracker.

    Configuring a Kochava Tracker func configure(withParametersDictionary: [AnyHashable: Any], delegate: KochavaTrackerDelegate?)

    The designated configuration method for an instance of class KochavaTracker. This method is used to configure the provided shared instance for use.

    init?(parametersDictionary: [AnyHashable: Any], delegate: KochavaTrackerDelegate?)

    The designated initialization method for an instance of class KochavaTracker. This method is used to configure a newly instantiated KochavaTracker for use when you are not using the provided shared instance.

    func invalidate()

    Invalidates an instance of class KochavaTracker.

    Consent var consent

    An instance of class KVAConsent, providing intelligent consent management.

    Sending Post-Install Events func sendDeepLink(withOpen: URL?, sourceApplicationString: String?)

    Sends a deep link event to Kochava, along with the associated opening URL and source application string.

    func send(KochavaEvent)

    Sends an instance of class KochavaEvent to the Kochava Server.

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

    Creates an instance of class KochavaEvent which has a nameString and an optional infoDictionary, and then sends it to the Kochava Server. A convenience method.

    func sendEvent(withNameString: String, infoString: String?)

    Creates an instance of class KochavaEvent which has a nameString and an optional infoString, and then sends it to the Kochava Server. A convenience method.

    func sendEvent(withNameString: String, infoString: String?, appStoreReceiptBase64EncodedString: String)

    DEPRECATED: This feature will be removed or replaced in a future update. Refer to class KochavaEvent standard parameter appStoreReceiptBase64EncodedString.

    Creates an instance of class KochavaEvent which has a nameString, an optional infoString, and an appStoreReceiptBase64EncodedString, and then sends it to the Kochava Server. A convenience method.

    func sendIdentityLink(with: [AnyHashable: Any])

    Sends identity information to Kochava, where it can be integrated into your Analytics.

    func sendWatchEvent(withNameString: String, infoString: String?)

    Creates an instance of class KochavaEvent for an Apple Watch which has a nameString and an optional infoString, and then sends it to the Kochava Server. A convenience method.

    func setAppLimitAdTrackingBool(Bool)

    Sets a boolean switch which indicates whether a user of the app wants to limit advertising tracking.

    var sleepBool = false

    A boolean which tells the tracker that it should sleep.

    Retrieving Information func attributionDictionary() -> String?

    Gets the attribution dictionary that has already been retrieved by the tracker from the Kochava Server.

    func deviceIdString() -> String?

    Gets the device identification string used by the tracker.

    func sdkVersionString() -> String?

    Gets the SDK version string used by the tracker.

    Apple Watch func handleWatchEvents()

    Associates an Apple Watch with your host.

    func handleWatchEvents(withWatchIdString: String?)

    Associates an Apple Watch which has a specific watch identifier with your host.

    Push Notifications func addRemoteNotificationsDeviceToken(_:)

    Add a remote notifications device token.

    func removeRemoteNotificationsDeviceToken(_:)

    Remove a remote notifications device token.

    Relationships

    Inherits From NSObject

    See Also

    Related Symbols class KochavaEvent

    The class KochavaEvent provides a means of defining the parameters for a post-install event, providing standardized types and key names.

    Integrated Topics Integration Topic Push Notifications

    Integrate your app with Kochava’s Push Notification Service.

  • Class

    KochavaTracker (iOS/tvOS)

    The class KochavaTracker provides an interface between a host application and Kochava’s Attribution and Analytics Servers. A tracker manages the exchange of data between these two entities, along with the associated tasks and network transactions.


    Overview

    The class KochavaTracker is the main interface for the KochavaTracker SDK. If you have not already integrated a KochavaTracker SDK into your project, refer to our KochavaTracker iOS SDK support documentation.

    You rarely create instances of the KochavaTracker class. Instead, you configure a provided shared instance using the designated configuration instance method configureWithParametersDictionary:delegate:.

    From there, the tracker proceeds to initialize immediately and perform its various tasks. This is typically done during the earliest phases of the host’s life-cycle, so that installation attribution can be quickly established and post-install events may immediately begin to be queued.

    You may alternately create an instance of the KochavaTracker class. If you do, it is your responsibility to maintain a strong reference. And if you create multiple instances, it is your responsibility to configure each with a unique storage identifier.

    Initialization and Configuration

    By initializing and configuring a KochavaTracker, you are completing the basic integration with a KochavaTracker SDK. This should be done in the logic of your application where things first start up, such as in your UIApplicationDelegate class’ application:didFinishLaunchingWithOptions: method. You may do this on the main thread, or else on a background thread with iOS SDK v3.1.5 or higher.

     

    1. Import the KochavaTracker SDK’s main header file.
    2. The name of this header file may vary depending on the SDK variant you are using. For Objective-C, you will typically import this file inside of your UIApplicationDelegate class’ implementation file. For Swift, this requirement will have been resolved when you integrated a KochavaTracker SDK variant into your project and imported this file inside of your Objective-C bridging header.

       

      Sample Code:

       

    3. Configure the provided shared instance.
    4. The provided shared instance instance is automatically allocated and initialized (lazily), enabling it to gracefully report and handle unexpected activity prior to the designated configuration method having been called. To configure it, first create a trackerParametersDictionary, and then perform the configuration using the designated configuration instance method configureWithParametersDictionary:delegate:.

       

      Sample Code:

       

    5. Alternate Step – Create and Initialize a New Instance
    6. You may alternatively create and initialize a new instance using the designated initialization method initWithParametersDictionary:delegate:. Using the provided shared instance is recommended for most integrations; however, a designated initialization method is provided for when the provided shared instance may not be suitable. The primary use-case for the designated initialization method is when multiple instances of the tracker are desired. For more information concerning multiple instances see constant kKVAParamStorageIdStringKey. Perform the initialization using the method initWithParametersDictionary:delegate: For a complete list of the supported parameters refer to dictionary trackerParametersDictionary.

       

      Sample Code:

     

    Sending Post-Install Events

    Sending post-install events (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 tracker has been configured, Kochava event tracking methods can be called from anywhere within the application. Events will be coupled with the information sent by the tracker 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.

    There are a variety of methods which can be used to send post-install events, depending on the kind of information you are tracking. If the information you have can be expressed in the standardized parameters of an instance of class KochavaEvent object, it is recommended that you create one and send it to the instance method sendEvent. If the information cannot be expressed in the standardized parameters of KochavaEvent. It is recommended that you next use instance method sendEventWithNameString:infoDictionary:. If you need to only send an event name and a string of associated information (or no information at all), you may use the generic method instance method sendEventWithNameString:infoString:.

    Retrieving Attribution

    Attribution information is assessed and stored within Kochava’s Servers, where it is reported back to you through your Kochava’s account.

    You may also retrieve this information from within your app.

    NOTE: Retrieving the information within your app should only be done if your app makes use of this information, otherwise it causes needless network communication.

    Attribution will performed server-side regardless of the application requesting the results. The tracker will retrieve attribution information if the kKVAParamRetrieveAttributionBoolKey parameter is passed with a value of true during its configuration. It does this usually within about 10 seconds from the initial launch, although it is subject to a variety of conditions which can cause this time interval to be longer.

    Once attribution information has been retrieved, the result is cached locally. If the KochavaTrackerDelegate instance method tracker:didRetrieveAttributionDictionary: is implemented, it will then also be called and the attribution information is passed as a parameter. Later you may also use the instance method attributionDictionary method to retrieve the cached information again.

    Requirement(s)

    NSUserDefaults

    The KochavaTracker stores its own information within the same sandbox as its host, and it persists this information in NSUserDefaults standard user defaults. You should be careful not to clear these keys, or the tracker may perform unpredictably. All of the trackers keys are prefaced with “com.kochava.KochavaTracker”. If you wish to remove NSUserDefaults, please be sure to exclude any keys which begin with this prefix.

    Using the Advertising Identifier (IDFA)

    The KochavaTracker class makes use of the Advertising Identifier (IDFA) in order to attribute the host installation to a previously served advertisement. The App Store submission process includes a disclosure concerning the use of the IDFA, whereby you will be asked to note that you use it. For more information see the FAQ concerning IDFA.



    • Why am I getting the error: “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.”

      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.

       

      A. Select for Following.

    Testing the Integration

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

    Symbols

    Getting a Shared Kochava Tracker + shared

    Returns a shared singleton KochavaTracker.

    Configuring a Kochava Tracker configureWithParametersDictionary:delegate:

    The designated configuration method for an instance of class KochavaTracker. This method is used to configure the provided shared instance for use.

    initWithParametersDictionary:delegate:

    The designated initialization method for an instance of class KochavaTracker. This method is used to configure a newly instantiated KochavaTracker for use when you are not using the provided shared instance.

    – (void)invalidate

    Invalidates an instance of class KochavaTracker.

    Consent property consent

    An instance of class KVAConsent, providing intelligent consent management.

    Sending Post-Install Events sendDeepLinkWithOpenURL:sourceApplicationString:

    Sends a deep link event to Kochava, along with the associated opening URL and source application string.

    sendEvent:

    Sends an instance of class KochavaEvent to the Kochava Server.

    sendEventWithNameString:infoDictionary:

    Creates an instance of class KochavaEvent which has a nameString and an optional infoDictionary, and then sends it to the Kochava Server. A convenience method.

    sendEventWithNameString:infoString:

    Creates an instance of class KochavaEvent which has a nameString and an optional infoString, and then sends it to the Kochava Server. A convenience method.

    – sendEventWithNameString:infoString:appStoreReceiptBase64
    EncodedString:

    DEPRECATED: This feature will be removed or replaced in a future update. Refer to class KochavaEvent standard parameter appStoreReceiptBase64EncodedString.

    Creates an instance of class KochavaEvent which has a nameString, an optional infoString, and an appStoreReceiptBase64EncodedString, and then sends it to the Kochava Server. A convenience method.

    sendIdentityLinkWithDictionary:

    Sends identity information to Kochava, where it can be integrated into your Analytics.

    sendWatchEventWithNameString:infoString:

    Creates an instance of class KochavaEvent for an Apple Watch which has a nameString and an optional infoString, and then sends it to the Kochava Server. A convenience method.

    setAppLimitAdTrackingBool:

    Sets a boolean switch which indicates whether a user of the app wants to limit advertising tracking.

    property sleepBool

    A boolean which tells the tracker that it should sleep.

    Retrieving Information attributionDictionary

    Gets the attribution dictionary that has already been retrieved by the tracker from the Kochava Server.

    deviceIdString

    Gets the device identification string used by the tracker.

    sdkVersionString

    Gets the SDK version string used by the tracker.

    Apple Watch handleWatchEvents

    Associates an Apple Watch with your host.

    handleWatchEventsWithWatchIdString:

    Associates an Apple Watch which has a specific watch identifier with your host.

    Push Notifications addRemoteNotificationsDeviceToken:

    Add a remote notifications device token.

    removeRemoteNotificationsDeviceToken:

    Remove a remote notifications device token.

    Relationships

    Inherits From NSObject

    See Also

    Related Symbols class KochavaEvent

    The class KochavaEvent provides a means of defining the parameters for a post-install event, providing standardized types and key names.

    Integrated Topics Integration Topic Push Notifications

    Integrate your app with Kochava’s Push Notification Service.

 
 

Last Modified: Jul 11, 2018 at 2:44 pm