Adobe AIR – 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 Adobe AIR 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 Kochava.

  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 Kochava under typical conditions.
  3. Wait a minute or two and visit the Install Feed Validation page for your app within the Kochava dashboard, under Apps & Assets > Install Feed Validation. Within that page, look for the Integration Success! message which indicates integration was successful and that Kochava 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 Measurement:

If you are measuring user events, you can use this test to ensure the SDK was configured properly and is successfully sending these events to Kochava.

  1. Double check the SDK configuration in code, ensuring the correct App GUID.
  2. Double check your event measurement 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 Kochava 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 measuring 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.

 

SDK VERSION NOTE: This feature requires Kochava SDK Version 2.6.0 or higher.

 

NOTE: This feature is applicable to iOS platforms only.

No special code is needed to support SKAdNetwork, beyond tracking your existing events which are eligible for conversion.

 

After setting up SKAdNetwork in your Kochava dashboard, the SDK will automatically:

  1. Call Apple’s SKAdNetwork registration at the first opportunity following launch.
  2. When an eligible conversion event is triggered on iOS 14, the SDK will calculate the appropriate conversion value based on the event’s properties and automatically call Apple’s SKAdNetwork conversion update.

Generating SKAdNetwork Postbacks:

While the SDK automatically makes the necessary Apple API calls for you, a SKAdNetwork postback will only be generated if requirements are met for both the source app and advertised app. The advertised app must have been reviewed and available for download in the App Store, while the source app (where the ad is displayed) can be one that you are currently developing and run from Xcode or through TestFlight. Be sure to use the correct SKStoreProductParameterAdNetworkSourceAppStoreIdentifier per your case.

For testing purposes, you can cut down on the 24 hour postback wait by using the “SKAdNetwork Profile” from the Apple developer console here: https://developer.apple.com/download/more/ (search for “skad”).

 

SDK VERSION NOTE: This feature requires Kochava SDK Version 2.6.0 or higher.

 

NOTE: This feature is applicable to iOS platforms only.

As of iOS 14, IDFA collection is gated behind Apple’s new AppTrackingTransparency (ATT) permission-based authorization. This means that when an app is running on iOS 14, the IDFA is not available for collection until after the user grants permission, similar to any other iOS permission-based collection. However, Apple is delaying enforcement of ATT, which is discussed below.

About ATT Non-Enforcement

In order to allow developers more time to adjust to the changes surrounding IDFA collection, Apple announced that tracking authorization via the ATT framework would not be required to collect the IDFA on iOS 14, until at least 2021. The IDFA will continue to be available for collection on iOS 14 no differently than it was on iOS 13 and prior. However, once an ATT request for authorization is made, IDFA availability then becomes subject to the results of tracking authorization from that point on. This means that you must decide whether to start prompting users for tracking authorization now or wait for Apple to provide a concrete timeline on when they will begin requiring tracking authorization at some time in the future.

If you do not yet wish to prompt the user for tracking authorization and enforce ATT, you do not need to take any additional steps and the SDK will continue to gather the IDFA until Apple begins requiring tracking authorization sometime in 2021.

If you wish to enforce ATT and begin prompting users for tracking authorization, continue reading below.


Enforcing ATT for IDFA Collection

The SDK makes this drop-dead simple for you. All you need to do is tell the SDK you want to enable ATT enforcement during configuration.

As a tracking requirement by Apple, you must include in your info.plist the key NSUserTrackingUsageDescription and a string value explaining why you are requesting authorization to track. This text will be included in the prompt displayed by the operating system when tracking authorization is requested.


Configure the SDK

During SDK configuration, tell the SDK you wish to enable ATT enforcement. By default, the user will be prompted for tracking authorization one time, upon launch, and the SDK will allow up to 30 seconds for the user to answer the tracking authorization prompt. You may adjust this behavior if you wish.

 

Example Enabling ATT with default settings (recommended):

var configMapObject:Object = new Object();
configMapObject[KochavaTracker.PARAM_IOS_APP_GUID_STRING_KEY] = "_YOUR_IOS_APP_GUID_";
configMapObject[KochavaTracker.PARAM_ANDROID_APP_GUID_STRING_KEY] = "_YOUR_ANDROID_APP_GUID_";
configMapObject[KochavaTracker.PARAM_APP_TRACKING_TRANSPARENCY_ENABLED_BOOL_KEY] = true;
KochavaTracker.configure(configMapObject);

 

Example Allow more than the default 30 seconds for the user to respond:

var configMapObject:Object = new Object();
configMapObject[KochavaTracker.PARAM_IOS_APP_GUID_STRING_KEY] = "_YOUR_IOS_APP_GUID_";
configMapObject[KochavaTracker.PARAM_ANDROID_APP_GUID_STRING_KEY] = "_YOUR_ANDROID_APP_GUID_";
configMapObject[KochavaTracker.PARAM_APP_TRACKING_TRANSPARENCY_ENABLED_BOOL_KEY] = true;
configMapObject[KochavaTracker.PARAM_APP_TRACKING_TRANSPARENCY_WAIT_TIME_DOUBLE_KEY] = 90;
KochavaTracker.configure(configMapObject);

 

At this point you are done. The user will be prompted for tracking authorization one time, during the first launch of the app, and the IDFA will be gathered if authorization is granted.

For purposes of testing, you will need to uninstall and reinstall the app each time you wish for the tracking prompt to appear, as Apple will only allow this to be displayed once.

Optionally, if you wish to prompt the user for tracking authorization at a specific moment or you do not want the SDK to trigger the prompt, continue reading below.


Custom Prompt Timing (Optional)

Follow these steps only if you wish for the tracking authorization prompt to be displayed at a time other than when the app is first launched or you do not want the SDK to trigger the prompt.

In order to accomplish this, first configure the SDK so that it does not automatically request authorization and allows enough time for the user to reach the point where tracking authorization will be requested at the moment of your choosing. In this example, we are allowing up to 120 seconds for the user to provide an answer to the tracking authorization request.

 

Example Configure the SDK:

var configMapObject:Object = new Object();
configMapObject[KochavaTracker.PARAM_IOS_APP_GUID_STRING_KEY] = "_YOUR_IOS_APP_GUID_";
configMapObject[KochavaTracker.PARAM_ANDROID_APP_GUID_STRING_KEY] = "_YOUR_ANDROID_APP_GUID_";
configMapObject[KochavaTracker.PARAM_APP_TRACKING_TRANSPARENCY_ENABLED_BOOL_KEY] = true;
configMapObject[KochavaTracker.PARAM_APP_TRACKING_TRANSPARENCY_WAIT_TIME_DOUBLE_KEY] = 120;
configMapObject[KochavaTracker.PARAM_APP_TRACKING_TRANSPARENCY_AUTO_REQUEST_BOOL_KEY] = false;
KochavaTracker.configure(configMapObject);

 

Secondly, add code which requests the tracking authorization at the time of your choosing and then notifies the SDK when the authorization request completes. It is your responsibility to ensure your tracking authorization request code is reached. If it is not, the timeout will be reached and the SDK will proceed without collecting the IDFA.

NOTE: Regardless of how many times you request tracking authorization, the user is only prompted once. This means you can repeatedly request tracking authorization at a specific moment per app launch and the user will only be prompted once, the first time the code is reached.

 

Example Request authorization and notify the SDK upon completion:

// notify the Kochava SDK that it may proceed with tracking authorization
KochavaTracker.enableAppTrackingTransparencyAutoRequest();

 

SDK VERSION NOTE: This feature requires Kochava SDK Version 2.6.0 or higher.

 

NOTE: This feature is applicable to Android platforms only.

The standard SDK is used within your instant app (no special variant of the SDK is needed for an instant app).

In order to properly support user and attribution flow between the instant app and full app, the following steps must be taken.

  1. Create two App GUIDs.
  2. The instant app and full app should not use the same App GUID. For the instant app, create or use a Kochava app of platform type Android – Instant App and pass that App GUID to the SDK during configuration under the InstantAppGuid parameter. For the full app, create or use a Kochava app of platform type Android and pass that App GUID to the SDK during configuration to the AppGuid parameter.

  3. Add Dependencies.
  4. Add the instant apps dependency to your project. This dependency is only required in the instant app.

    com.google.android.gms:play-services-instantapps:17.0.0

     

  5. Supporting Older Android Versions.
  6. Instant Apps are natively supported on Android 8 (API 26) and higher with data being automatically migrated from the instant app to the full app. If supporting Android 7 or lower you are responsible for migrating the data prior to starting the SDK. See the documentation on transferring data.

  7. Configure the SDK.
  8. var configMapObject:Object = new Object();
    configMapObject[KochavaTracker.PARAM_IOS_APP_GUID_STRING_KEY] = "_YOUR_IOS_APP_GUID_";
    configMapObject[KochavaTracker.PARAM_ANDROID_APP_GUID_STRING_KEY] = "_YOUR_ANDROID_APP_GUID_";
    configMapObject[KochavaTracker.PARAM_INSTANT_APP_GUID_STRING_KEY] = "_YOUR_INSTANT_APP_GUID_";
    KochavaTracker.configure(configMapObject);
    

     

  9. Process the Deeplink.
  10. When the instant app is launched, pass the invocation URL to the SDK’s Process Deeplink API as soon as possible, just as you would any other deeplink. See Enhanced Deeplinking below for complete instructions on how to use the Process Deeplink API.

    By taking these steps, all functionality related to attribution, analytics, and measurement will be properly implemented between the instant app and full app.

 

SDK VERSION NOTE: This feature requires Kochava SDK Version 2.6.0 or higher.

 

NOTE: This feature is applicable to iOS platforms only.

The standard SDK is used within your app clip app (no special variant of the SDK is needed for an app clip).

In order to properly support user and attribution flow between the app clip and full app, the following steps must be taken.

  1. Create Two App GUIDs.
  2. The app clip and full app should not use the same App GUID. For the app clip, create or use a Kochava app of platform type iOS – App Clip and pass that App GUID to the SDK during configuration of your app clip. For the full app, create or use a Kochava app of platform type iOS and pass that App GUID to the SDK during configuration of your full app.

  3. Configure the SDK.
  4. You will need to provide an app group identifier string which facilitates shared storage between the app clip and full app.
    To accomplish this, in Xcode under the project Signing & Capabilities, add a new capability for App Groups if you do not have one already using the plus button. For the new identifier, start with your app’s bundle identifier and then prefix it with group. and suffix it with .kochava. Provide this identifier to the SDK by setting the container app group identifier parameter when configuring the SDK. This identifier must be the same between the app clip and full app.

     

    Example Provide a Shared Storage Container Before Starting the Tracker:

    // Example code, Actual code will be provided by the specific SDK doc.
    // Provide an app group identifier string which facilitates shared storage between the app clip and full app
    var configMapObject:Object = new Object();
    configMapObject[KochavaTracker.PARAM_IOS_APP_GUID_STRING_KEY] = "_YOUR_IOS_APP_GUID_";
    configMapObject[KochavaTracker.PARAM_ANDROID_APP_GUID_STRING_KEY] = "_YOUR_ANDROID_APP_GUID_";
    configMapObject[KochavaTracker.PARAM_CONTAINER_APP_GROUP_IDENTIFIER_STRING_KEY] = "group.com.kochava.host.kochava";
    KochavaTracker.configure(configMapObject);
    

    NOTE: The SDK detects your app clip by looking for the bundle identifier’s default .clip suffix.

     

  5. Process the Deeplink.
  6. When the app clip is launched, pass the invocation URL to the SDK’s Process Deeplink API as soon as possible, just as you would any other deeplink. See Enhanced Deeplinking below for complete instructions on how to use the Process Deeplink API.

    By taking these steps, all functionality related to attribution, analytics, and measurement will be properly implemented between the app clip and full app.

Estimated Time to Complete
15 Minutes

Examples include in-app purchases, level completions, or other noteworthy user activity you wish to measure. Events can be instrumented either by using the standard format provided by the SDK or using your own custom event name and data.

 

BEST PRACTICES: Use a standard event type whenever possible.

 

Standard Events:

Standard events are built by first selecting a standard event type and then setting any applicable standard parameters you wish to include with the event. For example, you might choose a Purchase standard event type and set values for the Price and Name parameters. There are a variety of standard event types to choose from and dozens of standard parameters available. When creating a standard event, you only need to set values for the parameters you wish to measure. A maximum of 16 parameters can be set.

  1. Create an event object using the desired standard event type.
  2. Set the desired parameter value(s) within the event object.
  3. Send the event.

 

Example (Standard Event with Standard Parameters)

var eventMapObject:Object = new Object();
eventMapObject["name"] = "Gold Token";
eventMapObject["price"] = 0.99;
KochavaTracker.sendEventMapObject(KochavaTracker.EVENT_TYPE_PURCHASE_STRING_KEY, eventMapObject);

 

Custom event parameters (which can also be serialized JSON) may also be set within a standard event.

 

Example (Standard Event with Standard and Custom Parameters)

var eventMapObject:Object = new Object();
eventMapObject["name"] = "The Deep Dark Forest";
eventMapObject["attempts"] = 3;
eventMapObject["score"] = 12000;
KochavaTracker.sendEventMapObject(KochavaTracker.EVENT_TYPE_LEVEL_COMPLETE_STRING_KEY, eventMapObject);

 

If you wish to use a custom event type with standard parameters, use a custom event name string within your event constructor in place of a standard event type.

 

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


Custom Events:

For scenarios where the standard event types and standard parameters do not meet your needs, custom events can be used. To instrument a custom event, pass the event’s name and data (which can also be serialized JSON) to the method to send the custom event.

 

Example (Custom Event with Custom Parameters)

var eventMapObject:Object = new Object();
eventMapObject["enemy"] = "The Angry Ogre";
eventMapObject["reward"] = "Gold Token";
KochavaTracker.sendEventMapObject("Enemy Defeated", eventMapObject);

 

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

KochavaTracker.sendEventString("Player Defeated","");

 

Example (Send a Custom Event with Event Data)

KochavaTracker.sendEventString("Player Defeated","Angry Ogre");

 

Example (Send a Custom Event with Serialized JSON Data)

KochavaTracker.sendEventString("Player Defeated","{\"enemy\":\"Angry Ogre\"}");

 

NOTE: No custom event name pre-registration is required. However, a maximum of 100 unique event names can be measured within the Kochava dashboard (including any standard event types also used), so keep this in mind as you create new custom event names.

 

Developer API Reference:

KochavaTracker.sendEventMapObject(String, Object)
KochavaTracker.sendEventString(String, String)
Standard Event Types


Estimated Time to Complete
10 Minutes

In-app purchases and subscription can be easily measured and attributed by creating a purchase event. To accomplish this, simply create an event of type Purchase and include the total amount of revenue as the price value within the event data parameters.

 

BEST PRACTICES: Include the name parameter, so that you can easily identify the SKU from the analytics side. It is also highly recommended to set a currency.

 

Example (Standard Purchase Event):

  • var eventMapObject:Object = new Object();
    eventMapObject["name"] = 'Loot Box';
    eventMapObject["price"] = 4.99;
    KochavaTracker.sendEventGooglePlayReceipt(KochavaTracker.EVENT_TYPE_PURCHASE_STRING_KEY, eventMapObject, receiptData, receiptDataSignature);
  • var eventMapObject:Object = new Object();
    eventMapObject["name"] = 'Loot Box';
    eventMapObject["price"] = 4.99;
    KochavaTracker.sendEventAppleAppStoreReceipt(KochavaTracker.EVENT_TYPE_PURCHASE_STRING_KEY, eventMapObject, appStoreReceiptBase64EncodedString);

 

Example (Custom Purchase Event with Serialized JSON Data):

KochavaTracker.sendEventString("Purchase","{\"price\":4.99,\"name\":\"Loot Box\"}");

 

Developer API Reference:

KochavaTracker.sendEventString(String, String)
KochavaTracker.sendEventAppleAppStoreReceipt(String, Object, String)
KochavaTracker.sendEventGooglePlayReceipt(String, Object, String, String)
Standard Event Types


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: When registering an identity link, register the identity link prior to sending the event, otherwise the event will not be properly associated with the user’s identity.

 

Example (Identity Link with Subscription):

  • // first set an identity link for this user
    Tracker.setIdentityLink(new Tracker.IdentityLink()
            .add("Subscriber ID","ABCDEF123456789")
    );
    // next, instrument the subscription event
    Tracker.sendEvent(new Tracker.Event(Tracker.EVENT_TYPE_SUBSCRIBE)
            .setPrice(9.99)
            .setCurrency("usd")
            .setName("Monthly Subscription")
            .setUserId("ABCDEF123456789")
            .setGooglePlayReceipt(purchase.getOriginalJson(), purchase.getSignature())
    );
    
  • // first set an identity link for this user
    KochavaTracker.shared.sendIdentityLink(with:  [
        "Subscriber ID": "ABCDEF123456789"
    ])
    
    // next, instrument the subscription event
    if let event = KochavaEvent(eventTypeEnum: .subscribe) {
        event.priceDecimalNumber = 9.99
        event.currencyString = "usd"
        event.nameString = "Monthly Subscription"
        event.appStoreReceiptBase64EncodedString = appStoreReceiptData.base64EncodedString()
                
        KochavaTracker.shared.send(event)
    }
    

 

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):

  • // first set an identity link for this user
    Tracker.setIdentityLink(new Tracker.IdentityLink()
            .add("Subscriber ID","ABCDEF123456789")
    );
    // next, instrument the trial event
    Tracker.sendEvent(new Tracker.Event(Tracker.EVENT_TYPE_START_TRIAL)
            .setPrice(0.0)
            .setCurrency("usd")
            .setName("Monthly Subscription")
            .setUserId("ABCDEF123456789")
            .setGooglePlayReceipt(purchase.getOriginalJson(), purchase.getSignature())
    );
    
  • // first set an identity link for this user
    KochavaTracker.shared.sendIdentityLink(with:  [
        "Subscriber ID": "ABCDEF123456789"
    ])
    
    // next, instrument the subscription event
    if let event = KochavaEvent(eventTypeEnum: .startTrial) {
        event.priceDecimalNumber = 0.0
        event.currencyString = "usd"
        event.nameString = "Monthly Subscription"
        event.userIdString = "ABCDEF123456789"
        event.appStoreReceiptBase64EncodedString = appStoreReceiptData.base64EncodedString()
                
        KochavaTracker.shared.send(event)
    }
    


Estimated Time to Complete
5 Minutes

Measuring deeplinks is accomplished similar to any other type of event. In order to measure a deeplink event, create a standard event of type Deeplink and set the URI parameter along with any other relevant parameters to the values provided when the deeplink occurred.

 

Example (Standard Deeplink Event):

var eventMapObject:Object = new Object();
eventMapObject["uri"] = "some_deeplink_uri";
eventMapObject["source"] = "some_source_app";
KochavaTracker.sendEventMapObject(KochavaTracker.EVENT_TYPE_DEEP_LINK_STRING_KEY, eventMapObject);

 

Developer API Reference:

KochavaTracker.sendEventMapObject(String, Object)
KochavaTracker.sendEventString(String, String)
Standard Event Types


 

SDK VERSION NOTE: Enhanced Deeplinking is available as of Android native SDK version 3.7.0 and iOS native SDK version 3.12.

 

Example (Acquire the Deeplink):

// acquire a deeplink whenever one is available and pass it to the SDK.
var deeplinkUrl:String = "todo";
KochavaTracker.processDeeplink(deeplinkUrl, deeplinkProcessed);

 

Example (Wait for the Callback):

public function deeplinkProcessed(deeplinkString:String):void {
    var deeplink:Object = JSON.parse(deeplinkString);
    var destination:String = deeplink["destination"];
    if(destination) {
        // deeplink exists, parse the destination as you see fit and route the user
    } else {
        // no deeplink to act upon, route to a default destination or take no action
    }
}

 

Developer API Reference:

KochavaTracker.processDeeplink(String, FunctionString)
KochavaTracker.processDeeplinkWithOverrideTimeout(String, Number, FunctionString)
Deeplink


Estimated Time to Complete
10 Minutes

Setting an Identity Link provides the opportunity to link different identities together in the form of key and value pairs. For example, you may have assigned each user of your app an internal ID which you want to connect to a user’s service identifier. Using this feature, you can send both your internal ID and their service identifier to connect them in the Kochava database.

In order to link identities, you will need to register this identity link information in the form of unique key and value pair(s) as early as possible. This can be done during the initial configuration of the measurement client if the identity link information is already known, or it can be done after starting the client.

 

BEST PRACTICES: Keep from sending Personal Identifiable Information (PII) such as email addresses or deprecated platform identifiers such as IMEI to Kochava..

 

Example (Register an Identity Link During Tracker Configuration):

var identityLinkMapObject:Object = new Object();
identityLinkMapObject["User ID"] = "123456789";
identityLinkMapObject["Login"] = "username";

var configMapObject:Object = new Object();
configMapObject[KochavaTracker.PARAM_IDENTITY_LINK_MAP_OBJECT_KEY] = identityLinkMapObject;
configMapObject[KochavaTracker.PARAM_ANDROID_APP_GUID_STRING_KEY] = "_YOUR_ANDROID_APP_GUID";
configMapObject[KochavaTracker.PARAM_IOS_APP_GUID_STRING_KEY] = "_YOUR_IOS_APP_GUID";
KochavaTracker.configure(configMapObject);

 

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

var identityLinkMapObject:Object = new Object();
identityLinkMapObject["User ID"] = "123456789";
identityLinkMapObject["Login"] = "username";
KochavaTracker.setIdentityLink(identityLinkMapObject);

 

Developer API Reference:

KochavaTracker.configure(Object)
Configuration Parameters
KochavaTracker.setIdentityLink(Object)


Estimated Time to Complete
15 Minutes

Install attribution results can be retrieved from Kochava servers if you wish to use these results within your app. Be aware that attribution results are always determined by Kochava servers; this feature simply provides the app with a copy of whatever the results were.

For example, you may wish to present a user with a different path if you have determined they installed the app from a certain advertising network or source.

Attribution results are fetched by the measurement client when requested and returned to the app asynchronously via a callback. This process usually takes about 3-4 seconds but can take longer depending on network latency and other factors. Once attribution results have been retrieved for the first time, they are not retrieved again and the results are persisted. From that point on they can be queried synchronously by calling the attribution data getter which always provides the persisted attribution results from the original retrieval.

NOTE: For purposes of deferred deeplinking, care should be taken to act upon the attribution results only once, as the original results will continue to be reported after the first retrieval, and are not refreshed on a per-launch basis.

 

BEST PRACTICES: Attribution retrieval does not affect attribution and should only be used if there is a clearly defined use within your app for knowing the attribution results; otherwise this causes needless network activity.

 

Example (Requesting Attribution Results):

var configMapObject:Object = new Object();
configMapObject[KochavaTracker.PARAM_RETRIEVE_ATTRIBUTION_BOOL_KEY] = true;
configMapObject[KochavaTracker.PARAM_ANDROID_APP_GUID_STRING_KEY] = "_YOUR_ANDROID_APP_GUID";
configMapObject[KochavaTracker.PARAM_IOS_APP_GUID_STRING_KEY] = "_YOUR_IOS_APP_GUID";
KochavaTracker.configure(configMapObject);

KochavaTracker.setAttributionListener(function(event: KochavaTrackerStatusEvent):void {
    var attribution:String = event.level;
    if(attribution) {
        var attributionObject:Object = JSON.parse(attribution);
        // do something with attributionObject...
    }
});

 

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

var attribution:String = KochavaTracker.getAttribution();
if(attribution) {
    var attributionObject:Object = JSON.parse(attribution);
    // do something with attributionObject...
}

 

Once you have the attribution results, you will need to parse and handle them in some meaningful way. A variety of data exists within this json object and you will need to determine which data is meaningful for your purposes. For an overview of the attribution dictionary contents, see: Attribution Response Examples.

NOTE: If you wish to send attribution results to your own server, this should be done directly through Kochava’s postback system, rather than retrieving attribution in the app and then sending the results to your own server.

 

Developer API Reference:

KochavaTracker.configure(Object)
Configuration Parameters
String KochavaTracker.getAttribution()
KochavaTracker.setAttributionListener(FunctionKochavaTrackerStatusEvent)
KochavaTrackerStatusEvent


Estimated Time to Complete
1 Minute

If at any time after starting the measurement client you would like to get the universally unique identifier assigned to this install by Kochava, this identifier can be obtained by calling the retrieve function.

 

Example (Getting the Kochava Device ID):

var deviceId:String = KochavaTracker.getDeviceId();
//Do something with the device id...

 

NOTE: If you have enabled the Intelligent Consent Management feature, this unique device ID may change between consent status changes when consent is required and has not been granted.

 

Developer API Reference:

String KochavaTracker.getDeviceId()


Estimated Time to Complete
1 Minute

If you wish to limit ad tracking at the application level, with respect to Kochava conversions, you can set this value during or after configuration. By default the limit ad tracking state is not enabled (false).

For example, you might provide an option for a user to indicate whether or not they wish to allow this app to use their advertising identifier for tracking purposes. If they do not wish to be tracked, this value would be set to true.

 

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

var configMapObject:Object = new Object();
configMapObject[KochavaTracker.PARAM_APP_LIMIT_AD_TRACKING_BOOL_KEY] = true;
configMapObject[KochavaTracker.PARAM_ANDROID_APP_GUID_STRING_KEY] = "_YOUR_ANDROID_APP_GUID";
configMapObject[KochavaTracker.PARAM_IOS_APP_GUID_STRING_KEY] = "_YOUR_IOS_APP_GUID";
KochavaTracker.configure(configMapObject);

 

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

KochavaTracker.setAppLimitAdTracking(true);

 

Developer API Reference:

KochavaTracker.configure(Object)
Configuration Parameters
KochavaTracker.setAppLimitAdTracking(boolean)


Estimated Time to Complete
5 Minutes

Logging provides a text-based log of the SDK’s behavior at runtime, for purposes of debugging.

For example, while testing you may wish to see the contents of certain payloads being sent to Kochava servers, in which case you would enable logging at a debug (or higher) level.

Six different log levels are available, each of which include all log levels beneath them. Info log level is set by default, although trace log level should be used when debugging so that all possible log messages are generated.

 

Log Level: none

No logging messages are generated.

Log Level: error

Errors which are usually fatal to the tracker.

Log Level: warn

Warnings which are not fatal to the tracker.

Log Level: info

Minimal detail, such as tracker initialization.

Log Level: debug

Granular detail, including network transaction payloads.

Log Level: trace

Very granular detail, including low level behavior.

 

Example (Enabling trace logging in a non-production build):

var configMapObject:Object = new Object();
if (DEBUG) {
    configMapObject[KochavaTracker.PARAM_LOG_LEVEL_ENUM_KEY] = KochavaTracker.LOG_LEVEL_ENUM_TRACE_VALUE;
} else {
    configMapObject[KochavaTracker.PARAM_LOG_LEVEL_ENUM_KEY] = KochavaTracker.LOG_LEVEL_ENUM_INFO_VALUE;
}
configMapObject[KochavaTracker.PARAM_ANDROID_APP_GUID_STRING_KEY] = "_YOUR_ANDROID_APP_GUID";
configMapObject[KochavaTracker.PARAM_IOS_APP_GUID_STRING_KEY] = "_YOUR_IOS_APP_GUID";
KochavaTracker.configure(configMapObject);

 

BEST PRACTICES: Logging should be set to info log level or lower for production builds. This will limit the log messages generated by the SDK to errors, warnings, and basic information messages which contain no sensitive information.

 

Developer API Reference:

KochavaTracker.configure(Object)
Configuration Parameters
Log Levels


Estimated Time to Complete
10 Minutes

Placing the measurement client into sleep mode, the client will enter a state where all non-essential network transactions will be held and persisted until the client is woken up. This can be useful if you wish to start the client early but need the measurement client to wait before sending install data or events to Kochava servers.

For example, if you wanted the measurement startup process to wait for permission prompts, you might start the measurement client in sleep mode during the app launch but wait while the user provides input. Once ready, the measurement client can be woken and will continue with its own startup process without losing any events that may have been queued beforehand.

 

Example (Enabling Sleep Mode During Tracker Configuration):

var configMapObject:Object = new Object();
configMapObject[KochavaTracker.PARAM_SLEEP_BOOL_KEY] = true;
configMapObject[KochavaTracker.PARAM_ANDROID_APP_GUID_STRING_KEY] = "_YOUR_ANDROID_APP_GUID";
configMapObject[KochavaTracker.PARAM_IOS_APP_GUID_STRING_KEY] = "_YOUR_IOS_APP_GUID";
KochavaTracker.configure(configMapObject);

 

Example (Enabling Sleep Mode After Starting the Tracker):

KochavaTracker.setSleep(true);

 

Once you are ready to wake the measurement client simply set the sleep state to false. At that point the client will wake up and continue as normal, sending any waiting install data or queued events.

 

Example (Waking the Tracker from Sleep Mode)

KochavaTracker.setSleep(false);

 

NOTE: For every call to set sleep to true, there should be a matching call at some point setting sleep to false. While these calls do not necessarily have to be balanced, care should be taken to not inadvertently leave the measurement client sleeping permanently. This allows the client to wake up and continue with necessary logic and processing of data. Any events or other activity queued while sleeping will be held but not sent until sleep mode is set to false. This means that if the client is never woken from sleep mode, events and other activity will continue to build up in the queue, causing undesirable results.

 

Developer API Reference:

KochavaTracker.configure(Object)
Configuration Parameters
KochavaTracker.setSleep(boolean)
Boolean getSleep()


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.

 

Example (Starting the Tracker Only When Consent Allows)

if(!consentRequired || consentGranted) {
    // we will not initialize Kochava unless consent requirements are met
    var configMapObject:Object = new Object();
    configMapObject[KochavaTracker.PARAM_ANDROID_APP_GUID_STRING_KEY] = "_YOUR_ANDROID_APP_GUID";
    configMapObject[KochavaTracker.PARAM_IOS_APP_GUID_STRING_KEY] = "_YOUR_IOS_APP_GUID";
    KochavaTracker.configure(configMapObject);
}

 

Example (Calling Tracker Methods Only When Consent Allows)

if(!consentRequired || consentGranted) {
    // we will not call Kochava methods unless consent requirements are met.
    KochavaTracker.sendEventString("My Event","");
}

 


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.

 


Refer to the Intelligent Consent Manager support documentation.


Estimated Time to Complete
5 Minutes

During testing, debugging, and non-production app development, the following steps will help you get the most out of your test environment and help to ensure your integration is working properly.

  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 Kochava integration. For more information see: Testing the Integration.
var configMapObject:Object = new Object();
if (DEBUG) {
    configMapObject[KochavaTracker.PARAM_LOG_LEVEL_ENUM_KEY] = KochavaTracker.LOG_LEVEL_ENUM_TRACE_VALUE;
    configMapObject[KochavaTracker.PARAM_ANDROID_APP_GUID_STRING_KEY] = "_YOUR_TEST_ANDROID_APP_GUID";
    configMapObject[KochavaTracker.PARAM_IOS_APP_GUID_STRING_KEY] = "_YOUR_TEST_IOS_APP_GUID";
} else {
    configMapObject[KochavaTracker.PARAM_LOG_LEVEL_ENUM_KEY] = KochavaTracker.LOG_LEVEL_ENUM_INFO_VALUE;
    configMapObject[KochavaTracker.PARAM_ANDROID_APP_GUID_STRING_KEY] = "_YOUR_PRODUCTION_ANDROID_APP_GUID";
    configMapObject[KochavaTracker.PARAM_IOS_APP_GUID_STRING_KEY] = "_YOUR_PRODUCTION_IOS_APP_GUID";
}
KochavaTracker.configure(configMapObject);

 

 
 

Last Modified: Jan 24, 2024 at 3:47 pm