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.


Windows Attribution Setup

Apps which advertise inside of the Windows Store ecosystem (using Vungle for example) can reliably make use of all forms of attribution including the WAID, fingerprinting, and IP-based attribution. However, apps which advertise outside of the Windows Store such as through web-based search ads, direct downloads, 3rd party stores like Steam or Oculus, or anyplace else should use only IP based attribution as the WAID is generally not available outside of the Windows Store and the browser user agent relied upon for fingerprinting is inconsistent across these other mediums.

 

NOTE: Due to the tendency for desktop computer clocks to vary in accuracy we recommend setting the Transaction Time for your app to Kochava (rather than Device) under Advanced Settings for your app. This will help to ensure that click and install times remain in sync regardless of the device’s clock.

NOTE: Although Xbox One apps live within the Windows Store ecosystem, no Windows Advertising Identifier is currently available on Xbox One and so IP attribution should be used for Xbox One apps.

 

Windows Campaign ID Attribution (CID):

The CID can be utilized for attribution purposes in scenarios where you’d like to attribute installs from a website link or other external source. To accomplish this, when setting up your tracker choose :

  1. Select Type>Custom.
  2. Append ?cid={click_id} to your Destination URL. Your app in the Windows Store.
  3. Enters Custom Parameters> Key = click_id Value = {click_id} .

 

 

By setting this up, when your tracker link is clicked a dynamically generated CID value will be appended to the Windows Store URL allowing you to properly attribute an installation to the click from an external website or source.

If you have questions, please contact your Client Success Management team.


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 Client Success Managers.

     

    Custom –

    Reserved, may be provided by your Client Success Managers.

     

  • 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 Client Success Managers.

     

    Custom –

    Config::custom
    Default: (empty)
    Reserved, may be provided by your Client Success Managers.

     


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: Apr 11, 2018 at 9:41 am