Windows – SDK 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:

1. Install the latest version of KochavaWRT via NuGet.
2. KochavaWRT should now appear within your project’s references.

Manual Setup:

1. Download and unzip the Kochava Windows SDK to a known location: (Release Notes)
2. Unzip and locate the folder for your desired build architecture and add the reference:
   • In Visual Studio select Project > Add > Reference > Browse.
3. Navigate to the unzipped Windows_Store folder and add the Kochava.winmd file.
4. 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

The Kochava SDK APIs can be used from within a WebView for scenarios where you have a native app with an embedded WebView. The examples provided in this topic shows the most common usage but additional APIs can be added by following the same pattern.

Calling the SDK from within your WebView requires the following steps.

1. Include the JavaScript snippet within your WebView
2. Add a handler that intercepts the API calls in your native code
3. Call the JavaScript APIs in your WebView

1. Include the JavaScript Snippet

Place the following JavaScript snippet within your website. This must be available in a way where it can be called from your own JavaScript.

Example (JavaScript Snippet)

function registerIdentityLink(name, value) {
    postUrl('kochavameasurement://registerIdentityLink?name='+encodeURIComponent(name)+'&value='+encodeURIComponent(value));
}

function sendEvent(eventName, eventData) {
    postUrl('kochavameasurement://sendEvent?eventName='+encodeURIComponent(eventName)+'&eventData='+encodeURIComponent(JSON.stringify(eventData)));
}

function postUrl(url) {
    var i = document.createElement('iframe');
    i.style.display = 'none';
    i.onload = function() { i.parentNode.removeChild(i); };
    i.src = url;
    document.body.appendChild(i);
}

2. Add Native Handler

Add the native code which interacts with the WebView. This code will handle the API calls from the JavaScript snippet in the WebView and route them to the appropriate native API.

Example (Native Handler)

// NOTE: This is an example code sample, the actual code sample will be provided by the specific SDK documentation.

public final class SampleUtilizationFromAWebView extends WebViewClient {

    /**
     * Override the URL handler and see if we are consuming the url load.
     */
    @Override
    public boolean shouldOverrideUrlLoading(@NonNull final WebView webView, @NonNull final String urlString) {
        if (kochavaMeasurementUrlHandler(urlString)) {
            return true;
        }

        // Handle others as needed
        // ...

        return false;
    }

    /**
     * Checks if the given url is a Kochava command and performs its action as required.
     * <p>
     * @return true if it is Kochava Measurement Command and false for all others.
     */
    private boolean kochavaMeasurementUrlHandler(@NonNull final String urlString) {
        final String kochavaPrefix = "kochavameasurement://";

        if(!urlString.startsWith(kochavaPrefix)) {
            // Not a Kochava Measurement Command
            return false;
        }

        // Handle all Kochava Measurement Commands

        if(urlString.startsWith(kochavaPrefix + "registerIdentityLink")) {
            final Uri url = Uri.parse(urlString);
            final String name = url.getQueryParameter("name");
            final String value = url.getQueryParameter("value");
            Measurement.getInstance().registerIdentityLink(name != null ? name : "", value);

        } else if (urlString.startsWith(kochavaPrefix + "sendEvent")) {
            final Uri url = Uri.parse(urlString);
            final String eventName = url.getQueryParameter("eventName");
            final String eventData = url.getQueryParameter("eventData");
            JSONObject eventDataParsed;
            try {
                eventDataParsed = new JSONObject(eventData);
            } catch (JSONException e) {
                eventDataParsed = new JSONObject();
                // Handle exception as needed
            }
            Event.buildWithEventName(eventName != null ? eventName : "")
                    .mergeCustomDictionary(eventDataParsed)
                    .send();

        } else {
            // Unrecognized Kochava Measurement Command
        }

        // Processed Kochava Measurement Command
        return true;
    }
}

3. Call the JavaScript APIs

From your code in the WebView you can now call the SDK’s JavaScript API as defined in the snippet included above.

Example (Basic Usage)

<button style="width: 100%; font-size: 16pt" onclick='
    registerIdentityLink("user_id", "abcdefg");
    '>Register Identity Link</button>

<p/>

<button style="width: 100%; font-size: 16pt" onclick='
    var eventData = {};
    eventData["user_id"] = "abcdefg";
    eventData["user_name"] = "user_123";
    sendEvent("Registration Complete", eventData);
    '>Send Event</button>

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:

1. Download and unzip the Kochava Windows SDK to a known location: (Release Notes)
2. Add the references:
   1. In Visual Studio 2015/2017 Select Project > Add Reference > Browse.
   2. In Visual Studio 2013 Select Project > References > Add New Reference > Browse.
3. Navigate to the unzipped Windows_Desktop_NET45 folder and add both the Kochava.dll and JsonFX.Json.dll files.
4. 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:

1. In Project > Properties > General enable Common Language Runtime Support (/clr).
2. In Project > Properties > General > .NET Target Framework Version Enter 4.5
3. 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

The Kochava SDK APIs can be used from within a WebView for scenarios where you have a native app with an embedded WebView. The examples provided in this topic shows the most common usage but additional APIs can be added by following the same pattern.

Calling the SDK from within your WebView requires the following steps.

1. Include the JavaScript snippet within your WebView
2. Add a handler that intercepts the API calls in your native code
3. Call the JavaScript APIs in your WebView

1. Include the JavaScript Snippet

Place the following JavaScript snippet within your website. This must be available in a way where it can be called from your own JavaScript.

Example (JavaScript Snippet)

function registerIdentityLink(name, value) {
    postUrl('kochavameasurement://registerIdentityLink?name='+encodeURIComponent(name)+'&value='+encodeURIComponent(value));
}

function sendEvent(eventName, eventData) {
    postUrl('kochavameasurement://sendEvent?eventName='+encodeURIComponent(eventName)+'&eventData='+encodeURIComponent(JSON.stringify(eventData)));
}

function postUrl(url) {
    var i = document.createElement('iframe');
    i.style.display = 'none';
    i.onload = function() { i.parentNode.removeChild(i); };
    i.src = url;
    document.body.appendChild(i);
}

2. Add Native Handler

Add the native code which interacts with the WebView. This code will handle the API calls from the JavaScript snippet in the WebView and route them to the appropriate native API.

Example (Native Handler)

// NOTE: This is an example code sample, the actual code sample will be provided by the specific SDK documentation.

public final class SampleUtilizationFromAWebView extends WebViewClient {

    /**
     * Override the URL handler and see if we are consuming the url load.
     */
    @Override
    public boolean shouldOverrideUrlLoading(@NonNull final WebView webView, @NonNull final String urlString) {
        if (kochavaMeasurementUrlHandler(urlString)) {
            return true;
        }

        // Handle others as needed
        // ...

        return false;
    }

    /**
     * Checks if the given url is a Kochava command and performs its action as required.
     * <p>
     * @return true if it is Kochava Measurement Command and false for all others.
     */
    private boolean kochavaMeasurementUrlHandler(@NonNull final String urlString) {
        final String kochavaPrefix = "kochavameasurement://";

        if(!urlString.startsWith(kochavaPrefix)) {
            // Not a Kochava Measurement Command
            return false;
        }

        // Handle all Kochava Measurement Commands

        if(urlString.startsWith(kochavaPrefix + "registerIdentityLink")) {
            final Uri url = Uri.parse(urlString);
            final String name = url.getQueryParameter("name");
            final String value = url.getQueryParameter("value");
            Measurement.getInstance().registerIdentityLink(name != null ? name : "", value);

        } else if (urlString.startsWith(kochavaPrefix + "sendEvent")) {
            final Uri url = Uri.parse(urlString);
            final String eventName = url.getQueryParameter("eventName");
            final String eventData = url.getQueryParameter("eventData");
            JSONObject eventDataParsed;
            try {
                eventDataParsed = new JSONObject(eventData);
            } catch (JSONException e) {
                eventDataParsed = new JSONObject();
                // Handle exception as needed
            }
            Event.buildWithEventName(eventName != null ? eventName : "")
                    .mergeCustomDictionary(eventDataParsed)
                    .send();

        } else {
            // Unrecognized Kochava Measurement Command
        }

        // Processed Kochava Measurement Command
        return true;
    }
}

3. Call the JavaScript APIs

From your code in the WebView you can now call the SDK’s JavaScript API as defined in the snippet included above.

Example (Basic Usage)

<button style="width: 100%; font-size: 16pt" onclick='
    registerIdentityLink("user_id", "abcdefg");
    '>Register Identity Link</button>

<p/>

<button style="width: 100%; font-size: 16pt" onclick='
    var eventData = {};
    eventData["user_id"] = "abcdefg";
    eventData["user_name"] = "user_123";
    sendEvent("Registration Complete", eventData);
    '>Send Event</button>

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:

1. Download the legacy SDK: (Release Notes)
2. Unzip and locate the folder for your desired build architecture and add the reference:
   1. In Visual Studio 2015/2017 Select Project > Add Reference > Browse.
   2. In Visual Studio 2013 Select Project > References > Add New Reference > Browse.
   3. Add the unzipped Kochava.winmd file as a reference to your project.
3. 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.