The Kochava Windows SDK is a lightweight plugin which can be easily integrated into your Windows Store, Xbox One or Windows Desktop project. The entire integration process takes less than five minutes and simply requires adding the SDK reference within your project and then starting the Kochava Tracker in code.
Integrating the SDK
Requirements:
- Visual Studio 2015 or higher
Supported Platforms:
- Windows 10 and Xbox One (UWP Build 10240+)
- Windows 8.1 (WinRT)
- Windows Desktop (CLR .NET 4.5)
- HoloLens and Mixed Reality
Data Privacy:
Integration:
Estimated Time to Complete
5 Minutes
In order to use the Kochava SDK, first add it as a reference within your project. This can be accomplished using NuGet (recommended for Windows 10) or by downloading the SDK files manually and adding references to them.
NuGet Setup:
- Install the latest version of KochavaWRT via NuGet.
- KochavaWRT should now appear within your project’s references.
Manual Setup:
- Download and unzip the Kochava Windows SDK to a known location:
(Release Notes)
- Unzip and locate the folder for your desired build architecture and add the reference:
- In Visual Studio select Project > Add > Reference > Browse.
- Navigate to the unzipped Windows_Store folder and add the Kochava.winmd file.
- KochavaWRT should now appear within your project’s references.
Once you have added the Kochava SDK reference, you are ready to proceed to Starting the Tracker below. All sample code assumes you have added the appropriate #using statement for the KochavaWRT namespace wherever Kochava related code is implemented.
#using KochavaWRT;
Estimated Time to Complete
10 Minutes
Our Classic Windows Desktop plugin is a lightweight .NET CLR library written in C#, which can be integrated into Windows Desktop applications supporting .NET 4.5.
BEST PRACTICES: Use the Windows & Xbox One UWP tab for Windows Store/WinRT apps.
Typical .NET App Integration:
- Download and unzip the Kochava Windows SDK to a known location:
- Add the references:
- In Visual Studio 2015/2017 Select Project > Add Reference > Browse.
- In Visual Studio 2013 Select Project > References > Add New Reference > Browse.
- Navigate to the unzipped Windows_Desktop_NET45 folder and add both the Kochava.dll and JsonFX.Json.dll files.
- KochavaNET should appear under your project’s references and you are ready to proceed to Starting the Tracker section below.
Unmanaged C++ Apps:
A requirement for the the Kochava SDK is support for CLR and .NET 4.5. Your app must be able to support this in order to use the SDK. For an unmanaged C++ app, it is possible to enable this support from within your project settings:
- In Project > Properties > General enable Common Language Runtime Support (/clr).
- In Project > Properties > General > .NET Target Framework Version Enter 4.5
- At this point your app supports CLR and targets the .NET 4.5 framework and you can follow the steps above for a .NET app integration. However, depending on your internal requirements you may or may not be able to support this. If you cannot, a client-built SDK or Server to Server integration would need to be used.
Once you have added the Kochava SDK reference, you are ready to proceed to Starting the Tracker. All sample code assumes you have added the appropriate #using statement for the KochavaNET namespace wherever Kochava related code is implemented.
#using KochavaNET;NOTE: The Windows Desktop version of the SDK does not collect the CID (Windows Store Campaign ID), installation receipt, or other Windows Store specific data points.
Estimated Time to Complete
10 Minutes
If your app is targeting Windows 8.1/Windows Phone 8.1 platforms or otherwise requires a C++ WinRT build of the SDK, please use the legacy Kochava SDK version 3.0.1, which is a WinRT Component written in C++ supporting Windows 8.1 WinRT and Windows 10 UWP.
Manual Setup:
- Download the legacy SDK:
(Release Notes)
- Unzip and locate the folder for your desired build architecture and add the reference:
- In Visual Studio 2015/2017 Select Project > Add Reference > Browse.
- In Visual Studio 2013 Select Project > References > Add New Reference > Browse.
- Add the unzipped Kochava.winmd file as a reference to your project.
- The Kochava SDK should now appear within your project’s references.
NOTE: For this version of the SDK, you must always choose the Kochava reference based on the architecture you are building for. When switching build architectures, you will need to remove the current Kochava reference and re-add the reference from the appropriate architectural folder. For example, when targeting x86 add the WINMD file reference from within the Kochava x86 folder. If you switch to target ARM, remove the current Kochava reference and re-add the reference from the Kochava arm folder. This can also be accomplished other ways, such as manually editing the project file itself to use the appropriate folder.
Once you have added the Kochava SDK reference, you are ready to proceed to Starting the Tracker section. All sample code assumes you have added the appropriate #using statement for the Kochava namespace wherever Kochava related code is implemented.
#using Kochava;NOTE: This is a legacy version of the SDK which is fully functional but is no longer maintained. The overall usage pattern and most API calls are very similar to the modern SDK documentation. However, small differences exist such as slightly different method names or signatures, as well as a lack of support for newer features added after 2017 such as Intelligent Consent Management.
NOTE: The Windows 8.1/Windows Phone 8.1 platform version of the SDK does not include support for CID (Windows Store Campaign ID) collection.
Starting the Tracker
Estimated Time to Complete
1 Minute
Once you have added the Kochava SDK reference to your project, the next step is to configure and start the Kochava Tracker in code. Only your App GUID is required to start the tracker with the default settings, which is the case for typical integrations.
We recommend starting the tracker within the constructor of your App singleton, although this can be done elsewhere if needed. Starting the tracker as early as possible will provide more accurate session reporting and help to ensure the tracker has been started before using it. Keep in mind the tracker can only be configured and started once per launch.
Start the Shared Instance with Default Settings (recommended):
public App()
{
this.InitializeComponent();
this.Suspending += OnSuspending;
// start the Kochava Tracker
SharedInstance.Initialize("_YOUR_APP_GUID_");
}We also recommend that you use the Shared Instance of the tracker, rather than creating your own tracker instance. By doing so you will not need to create or keep track of the instance yourself. In this documentation we will always use the Shared Instance of the tracker and reference it by SharedInstance.Tracker. If you create your own instance you will simply reference it directly in place of SharedInstance.Tracker.
Create Your Own Instance of the Tracker:
// start your own instance of the Kochava Tracker
var myTracker = new Tracker("_YOUR_APP_GUID_", LogLevel.none);Confirm the Integration
After integrating the SDK and adding the code to start the measurement client, launch and run the app for at least 10 seconds or more. During this time the client will start and send an install payload to Kochava. To confirm integration was successful, visit the app’s Install Feed Validation page Apps & Assets > Install Feed Validation. On this page you should see one of two integration messages, indicating integration success or failure.
Integration Successful
Along with this message you will also see a variety of data points associated with the device used for testing. At this point your integration is successful and you can proceed to the next step(s).
NOTE: It may take a few minutes for the first install to appear within the Install Feed Validation page. If you do not see this message immediately, you may simply need to wait a few minutes and check again.
Integration Not Complete
If you encounter this message, please review the integration steps, uninstall and reinstall the app, and check again.
SDK WAYPOINT: At this point basic integration is complete and the Kochava SDK will begin reporting session activity and attributing installs.
Where to Go From Here:
Now that you have completed integration you are ready to utilize the many features offered by the Kochava SDK. Continue on to Using the SDK and choose a topic.
Custom Tracker Configuration
If you would like to make adjustments to the tracker configuration beyond the default settings, use a Config object to start the tracker. To accomplish this, create the config object, set your App GUID and the desired parameters, and then pass it to the tracker’s initialization method.
Starting the Shared Instance Using a Custom Configuration:
public App()
{
this.InitializeComponent();
this.Suspending += OnSuspending;
// initialize the Kochava Tracker
var config = new Config();
config.AppGUID = "_YOUR_APP_GUID_";
config.LogLevel = LogLevel.none;
SharedInstance.Initialize(config);
}Creating Your Own Instance Using a Custom Configuration:
var config = new Config();
config.AppGUID = "_YOUR_APP_GUID_";
config.LogLevel = LogLevel.none;
var myTracker = new Tracker(config);NOTE: Setting values within a configuration object will have no effect after the tracker has been started.
Below is a list of all configuration options and their default settings. Keep in mind that in a typical integration these configuration settings should not be adjusted from their default values.
Setting the AppGUID:
Default — None
This string should be set to your Kochava App GUID, which can be found in your Edit App page within the Kochava dashboard. This value is always required (unless a Partner Name is set).
config.AppGUID = "_YOUR_APP_GUID_";Retrieving Attribution:
Default — None
Provide an attribution event listener if you wish to be notified of attribution results from Kochava servers. This is not necessary unless you wish to parse the attribution results for use within the app.
For complete details and examples, see: Retrieving Attribution
Setting Identity Links:
Default — None
Call this method for each identity link key/value pair which is known before starting the tracker. Identity Links can also be set after starting the tracker using the Tracker.SetIdentityLink method.
For complete details and examples, see: Identity Linking
Setting a Log Level:
Default — LogLevel.info
Set this value to the desired Log Level to be used by the SDK for debugging purposes. You will also need to subscribe to the Tracker.LoggingEvent before starting the tracker to output the messages to a console or elsewhere.
For complete details and examples, see: Enabling Logging
Setting App Limit Ad Tracking:
Default — false
If you wish to limit ad tracking at the application level, with respect to Kochava conversions, set this value to false. It can also be toggled after starting the tracker using the Tracker.SetAppLimitAdTracking setter.
For complete details and examples, see: App Limit Ad Tracking
Setting a Custom Value:
Default — (none)
This is a reserved setting and should not be set unless provided by your Client Success Manager.
Setting a Partner Name:
Default — (none)
This is a reserved value and should not be set unless provided by your Client Success Manager.
Setting a Sleep State:
Default — (false)
Set this value to true if you wish to start the tracker in Sleep mode. This advanced feature prevents the tracker from sending any network transactions and delays collection of the install data until woken.
For complete details and examples, see: Sleeping the Tracker
Setting a Custom User Agent:
Default — (none)
Primarily for purposes of adjusting modeled attribution results, set this string to the desired non-encoded user agent to be used in place of the default user agent which is normally generated by the SDK using a XAML WebView. This may be useful when XAML is otherwise unavailable, such as within a pure DirectX game.
config.CustomUserAgent = "Mozilla/5.0 (Windows NT 6.3; Trident/7.0; rv:11.0) like Gecko";Setting the Development Build Flag:
Default — (false)
Certain data collection such as the campaign id or install receipt can cause sluggish behavior in a development environment, as these items are not available for collection in a sideloaded build and usually require time consuming loading of extra symbols. By setting this flag to true the collection of data like this will be skipped. However, care should be taken that this flag is never set to true for a release build.
#if DEBUG
config.DevelopmentBuild = true;
#endifEnabling Intelligent Consent Management:
Default — (false)
As GDPR compliance can present many challenges during development, Kochava offers a fully managed solution for all your GDPR consent requirements through the use of our Intelligent Consent Management 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.
NOTE: This is an advanced feature requiring additional setup within your Kochava dashboard and should not be enabled without a full and complete understanding of how to use the Intelligent Consent Management feature.
config.IntelligentConsentManagement = true;For complete details and examples, see: Intelligent Consent Management