Support Home > SDK Integration > Windows and Xbox One SDK Integration

Windows and Xbox One SDK Integration

The Windows SDK is a lightweight plugin which can be easily integrated into your Windows Store, Xbox One or Classic Windows Desktop application.

 

Platforms:

  • Windows 10 (UWP Build 10240+)
  • Windows 8.1
  • Windows Phone 8.1
  • Xbox One (ERA)
  • HoloLens and Mixed Reality
  • Classic Windows Desktop 7+ (.NET 4.5)
  • Steam


Languages:

  • C++
  • C#
  • Visual Basic
  • JavaScript

Integration

Latest SDK version and release notes:  

 


  • Our Windows Store plugin is a lightweight WinRT component written in C#, which can be quickly and easily integrated into your Window 10 UWP or Xbox One app using the language of your choice.

     

    NuGet Integration:

    For apps targeting Windows 10 UWP (WinRT) or Xbox One on UWP, integrate the SDK via NuGet.

     

    Manual Integration:

    1. Download and unzip the Kochava Windows SDK to a known location.
    2. Unzip and locate the folder for your desired build architecture and add the reference:

      • In Visual Studio 2015 Select Project>Add Reference>Browse.
      • Add the unzipped Kochava.winmd file as a reference to your project.

     

    Windows 8.1 and Xbox (ERA):

    If you must build for Windows 8.1, Windows Phone 8.1 or native Xbox One (ERA) architectures, please use the legacy version 3.0.1, which is a WinRT Component written in C++.


  • Our Classic Windows Desktop plugin is a lightweight .DLL written in C#, which can be quickly and easily integrated into any Windows Desktop application targeting Windows 7 or higher (.NET 4.5). Please use the other tab for Windows Store apps.

    Typical .NET App Integration:

    1. Download and unzip the Kochava Windows SDK to a known location.
    2. Add the references:

      • In Visual Studio 2015 Select Project>Add Reference>Browse.
      • In Visual Studio 2013 Select Project>References>Add New Reference>Browse.

      After clicking Browse, navigate to the unzipped “Windows_NET45_Desktop” folder and add both the Kochava.dll and JsonFX.Json.dll files.

    3. Continue on to the initialization code samples below.

     

    NOTE: For Unity desktop apps, we suggest you use our Unity SDK Integration support documentation.

     

    Other Integrations:

    While you may choose to integrate a .NET library like ours a number of ways, please be aware that the Kochava.dll library targets the .NET 4.5 framework and also requires the JsonFx.Json.dll library in the same location for JSON parsing. These two files are found in the unzipped “Windows_NET45_Desktop” folder.


Using the SDK

  • After integrating the SDK, the Kochava tracker can be up and running with just one line of code:

     

    NOTE: Now that the tracker is initialized you can send events and interact with this tracker object. The tracker is initialized only once and should be done so alongside initialization of your application.

     

    Alternatively, you may create and manage your own Tracker object, although we suggest you always use the SharedInstance. If you choose to create your own tracker object, simply create a new instance of the Tracker class. Keep in mind that while all code samples here show usage of the SharedInstance, the same methods and properties can be accessed from your own tracker instance.

     

    Advanced Initialization

    If you wish to initialize your tracker with more options, such as debugging or attribution retrieval, you can optionally create a configuration object and pass it to the tracker constructor. To accomplish this, create a Kochava.Config object and set the options you would like, then pass it to your tracker’s constructor.

     

    Configuration Options

    Listed below are the various configuration options available if you choose to initialize your tracker with a configuration object.

     

    Debugging

    Config.LoggingEvent
    Default: none
    This will allow you to receive debug output text which you can display in your own development environment. This option also requires that you subscribe to the logging event to receive lines of debug text as they become available. NOTE: Debugging should not be used in Release builds.

     

    Attribution Retrieval

    Config.SetAttributionResultsListener
    Default: false
    You may wish to retrieve attribution results from the server after initialization. Your app can be notified when attribution is available and/or request attribution any time if available.

     

    NOTE: This should only be done if your application makes use of this information, otherwise it causes needless network communication. Attribution will be performed server-side regardless of the application requesting the results.

     

     

    For a detailed explanation of attribution responses, refer to our Attribution Response Examples support documentation.

     

    Limit Ad Tracking

    Config.AppLimitAdTracking
    Default: false
    Tracker.AppLimitAdTracking
    If you wish to limit ad tracking at the application level, with respect to Kochava conversions, you can turn off ad tracking when you initialize Kochava or by an individual method for the purpose of changing the limit ad tracking state, which will be off by default.

     

    Custom User Agent

    Config.CustomUserAgent
    Default: null
    For pure DirectX games with no XAML support we suggest you provide a decoded custom user agent string as the SDK will not be able to retrieve an up-to-date user agent from a webview. An accurate user agent for the device will help with attribution accuracy. If XAML is not available and no custom user agent is supplied a last-known user agent string will be used, which may not be ideal.

     

    Partner Name

    Reserved, may be provided by your Account Manager.

     

    Custom

    Reserved, may be provided by your Account Manager.

     

  • After integrating the SDK, the Kochava tracker can be up and running with just one line of code:

     

    NOTE: Now that the tracker is initialized you can send events and interact with this tracker object. The tracker is initialized only once and should be done so alongside initialization of your application.

     

    Alternatively, you may create and manage your own Tracker object, although we suggest you always use the SharedInstance. If you choose to create your own tracker object, simply create a new instance of the Tracker class. Keep in mind that while all code samples here show usage of the SharedInstance, the same methods and properties can be accessed from your own tracker instance.

     

    Advanced Initialization

    If you wish to initialize your tracker with more options, such as debugging or attribution retrieval, you can optionally create a configuration object and pass it to the tracker constructor. To accomplish this, create a Kochava.Config object and set the options you’d like, then pass it to your tracker’s constructor.

     

    Configuration Options

    Listed below are the various configuration options available if you choose to initialize your tracker with a configuration object.

     

    Debugging

    Config.LoggingEvent
    Default: none
    This will allow you to receive debug output text which you can display in your own development environment. This option also requires that you subscribe to the logging event to receive lines of debug text as they become available. NOTE: Debugging should not be used in Release builds.

     

    Attribution Retrieval

    Config.SetAttributionResultsListener
    Default: false
    You may wish to retrieve attribution results from the server after initialization. Your app can be notified when attribution is available and/or request attribution any time if available.

     

    NOTE: This should only be done if your application makes use of this information, otherwise it causes needless network communication. Attribution will be performed server-side regardless of the application requesting the results.

     

     

    For a detailed explanation of attribution responses, refer to our Attribution Response Examples support documentation.

     

    Limit Ad Tracking

    Config.AppLimitAdTracking
    Default: false
    Tracker.AppLimitAdTracking
    If you wish to limit ad tracking at the application level, with respect to Kochava conversions, you can turn off ad tracking when you initialize Kochava or by an individual method for the purpose of changing the limit ad tracking state, which will be off by default.

     

    Custom User Agent

    Config.CustomUserAgent
    Default: null
    For pure DirectX games with no XAML support we suggest you provide a decoded custom user agent string as the SDK will not be able to retrieve an up-to-date user agent from a webview. An accurate user agent for the device will help with attribution accuracy. If XAML is not available and no custom user agent is supplied a last-known user agent string will be used, which may not be ideal.

     

    Partner Name

    Config::partnerName
    Default: null
    Reserved, may be provided by your Account Manager.

     

    Custom

    Config::custom
    Default: (empty)
    Reserved, may be provided by your Account Manager.

     


Sending Events


  • Sending Kochava post-install events is not a requirement. To track installation information, you need only call the initializer. 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.

    After initialization, the event tracking methods can be called from anywhere within the application. Events will be coupled with the information sent by the initializer to report events, based on user device and application information.

    Events are batched and sent at timed intervals. This helps to lower resource usage and increase efficiency. Events triggered when a user is offline are persisted and will be sent the next time the user is online.

     

    Send a Standard Event

    Tracker::SendEvent(Kochava::EventParameters)
    No event pre-registration is required. Standard events with commonly used parameters may be sent using the SendEvent(Kochava::EventParameters) method. To instrument a standard event, simply create a new EventParameters object with a chosen EventType and populate only the fields you would like to include with the event, if any. You may then pass the EventParameters object to the SendEvent().

     

    Send a Custom Event

    Tracker::SendEvent(string, string)
    No event pre-registration is required. To instrument a custom event simply send an event name and optionally an event value. The optional event value parameter can also be used to gather in-app purchase information that can be used for LTV calculation.

     


  • Sending Kochava post-install events is not a requirement. To track installation information, you need only call the initializer. 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.

    After initialization, the event tracking methods can be called from anywhere within the application. Events will be coupled with the information sent by the initializer to report events, based on user device and application information.

    Events are batched and sent at timed intervals. This helps to lower resource usage and increase efficiency. Events triggered when a user is offline are persisted and will be sent the next time the user is online.

     

    Send a Standard Event

    Tracker::SendEvent(Kochava::EventParameters)
    No event pre-registration is required. Standard events with commonly used parameters may be sent using the SendEvent(Kochava::EventParameters) method. To instrument a standard event, simply create a new EventParameters object with a chosen EventType and populate only the fields you would like to include with the event, if any. You may then pass the EventParameters object to the SendEvent().

     

    Send a Custom Event

    Tracker::SendEvent(string, string)
    No event pre-registration is required. To instrument a custom event simply send an event name and optionally an event value. The optional event value parameter can also be used to gather in-app purchase information that can be used for LTV calculation.

     


Get Attribution Data


  • (string) Tracker::attributionData
    If you want to ask what attribution data has been retrieved from the server, at any time you can query this property. This also requires setting config.RetrieveAttribution = true during initialization.


  • (string) Tracker::attributionData
    If you want to ask what attribution data has been retrieved from the server, at any time you can query this property. This also requires setting config.RetrieveAttribution = true during initialization.


Get Device ID


  • (string) Tracker::deviceId
    If you would like to retrieve the Kochava Device ID from the SDK for your own use, you can call the following method (if a Kochava Device ID has not yet been generated it will return an empty string).


  • (string) Tracker::deviceId
    If you would like to retrieve the Kochava Device ID from the SDK for your own use, you can call the following method (if a Kochava Device ID has not yet been generated it will return an empty string).


Send a Deep Link


  • Tracker::SendDeepLink(string)
    The SDK provides a specific event to use when tracking deep links. The method is as follows, where “a_deeplink_uri” is a string object that could hold the incoming deeplink uri.


  • Tracker::SendDeepLink(string)
    The SDK provides a specific event to use when tracking deep links. The method is as follows, where “a_deeplink_uri” is a string object that could hold the incoming deeplink uri.


Identity Link


  • Config::SetIdentityLink(string, string)
    Tracker::SetIdentityLink(string, string)

    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 userid which you want to connect to a user’s service identifier. Using the IdentityLink method, you can send both your internal id and their service identifier and connect them in the Kochava database. SetIdentityLink() can be called multiple times to set multiple values.
    Kochava reports can be output to show additional identity information for devices in the Kochava database so that you can supplement your reports with internal identifiers that are useful to you and your application.


  • Config::SetIdentityLink(string, string)
    Tracker::SetIdentityLink(string, string)

    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 userid which you want to connect to a user’s service identifier. Using the IdentityLink method, you can send both your internal id and their service identifier and connect them in the Kochava database. SetIdentityLink() can be called multiple times to set multiple values.
    Kochava reports can be output to show additional identity information for devices in the Kochava database so that you can supplement your reports with internal identifiers that are useful to you and your application.


Additional Xbox One (ERA) Setup

The SDK requires that Xbox One (ERA) projects add the Storage extension to their manifest, if not done so already. Enter this XML manually rather than copying and pasting to avoid encoding related schema and layout errors.


Files for Download

 

Manual Integration:

  1. Download and unzip the Kochava Windows SDK to a known location.  
  2. Add the unzipped Kochava.winmd file as a reference to your project.

Windows 10 (UWP) – NuGet:
https://www.nuget.org/packages/KochavaWRT/

NuGet Package Manager Console:

Install-Package KochavaWRT


FAQ

 
 

Last Modified: Feb 14, 2018 at 10:11 am