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 and Unreal Engine


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 Windows 8.1, Windows Phone 8.1, Xbox One or Windows 10 (UWP) app using the language of your choice.

     

    NuGet Integration:

    For apps targeting Windows 10 (UWP), you may optionally 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.
      • In Visual Studio 2013 Select Project>References>Add New Reference>Browse.

      After clicking Browse, navigate to the downloaded SDK folder and choose the subfolder which matches your desired architecture, then choose the Kochava.winmd file within.

    3. Please note that you will need to remove the current Kochava reference and repeat this process when you target a different build architecture. For Windows 10 (UWP) apps this can be avoided by using the NuGet integration. Otherwise, you can avoid this step by first adding a Kochava reference to your project and then opening your project’s vcproj / vcxproj file. Once open, locate the Kochava reference HintPath and replace the architecture-specific folder name with “$(Platform)”, like so:

    4. For Windows 8.1 C#, VB, and JS projects you must also add a reference to the Microsoft Visual C++ Runtime if not already done so. Right-click your project then Select Add Reference> Windows 8.1 or Universal Windows>Extensions>Microsoft Visual C++ 2013 Runtime Package for Windows.
    5. Continue on to the initialization code samples below.

     

    Xbox One Integration:

    Xbox One integration follows the manual integration steps above. However, for “UWP on Xbox One” apps you will simply use the Windows_UWP folder. The “Windows_XboxOne_ERA” folder is used only for native Xbox One ERA applications.


  • 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

  • Once you have integrated the SDK the Kochava tracker can be up and running with just a few lines 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 utilize the shared instance singleton to avoid creating a Tracker object. Usage of the shared instance is identical to a Tracker object except that you reference the Tracker as SharedInstance::Tracker().

     

    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::logLevel
    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::retrieveAttribution
    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 performed server-side regardless of the application requesting the results.

     

     

    Limit Ad Tracking

    Config::appLimitAdTracking
    Default: false
    Tracker::SetappLimitAdTracking
    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.

     

  • Once you have integrated the SDK the Kochava tracker can be up and running with just a few lines 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 utilize the shared instance singleton to avoid creating a Tracker object. Usage of the shared instance is identical to a Tracker object except that you reference the Tracker as SharedInstance::Tracker().

     

    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::logLevel
    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::retrieveAttribution
    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 performed server-side regardless of the application requesting the results.

     

     

    Limit Ad Tracking

    Config::appLimitAdTracking
    Default: false
    Tracker::SetappLimitAdTracking
    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.

     

  • Once you have integrated the SDK the Kochava tracker can be up and running with just a few lines 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 utilize the shared instance singleton to avoid creating a Tracker object. Usage of the shared instance is identical to a Tracker object except that you reference the Tracker as SharedInstance::Tracker().

     

    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::logLevel
    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::retrieveAttribution
    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 that this should only be done if your application makes use of this information, otherwise it causes needless network communication. Attribution will performed server-side regardless of the application requesting the results.

     

    Limit Ad Tracking

    Config::appLimitAdTracking
    Default: false
    Tracker::SetappLimitAdTracking
    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.

     

    Send Custom Event with Reciept

    Tracker::SendEvent(string, string, string)
    This method allows you to send an app purchase receipt (as an XML string) to Kochava servers.


  • 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.

     

    Send Custom Event with Reciept

    Tracker::SendEvent(string, string, string)
    This method allows you to send an app purchase receipt (as an XML string) to Kochava servers.


  • 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.

     

    Send Custom Event with Reciept

    Tracker::SendEvent(string, string, string)
    This method allows you to send an app purchase receipt (as an XML string) to Kochava servers.


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.


  • (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).


  • (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.


  • 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.


  • 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:
Latest SDK version and release notes:  

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


FAQ

 
 

Last Modified: Oct 19, 2017 at 3:03 pm