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 .NET CLR library written in C#, which can be integrated into Windows Desktop applications supporting .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 CID, 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 CID or 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.


Intelligent Consent Management

 

Requirements:

  • Windows 10 SDK version 4.0.1 and higher.

 

When Intelligent Consent Management (ICM) is enabled and configured within your Kochava dashboard, the SDK will indicate when the user should be prompted for consent. The Kochava tracker will only gather, persist and transmit data when consent requirements are met.

Before utilizing the API below, please review the ICM overview, FAQs and examples in our Intelligent Consent Management support documentation.


Configuration – Enabling ICM:

Property: Config.IntelligentConsentManagement
Default: false
Set this boolean to true within the Kochava SDK configuration to enable ICM.

BEST PRACTICES: Ensure you have a full understanding of how ICM will impact your analytics and data before enabling this feature.

 

Configuration – ICM Callback:

Property: Config.SetConsentUpdatedListener
Default: none
Provide a listener within the Kochava SDK configuration if you wish to receive real-time updates to ICM changes in status, such as when the user should be prompted (or reprompted) for consent. When this event fires, the Kochava SDK is indicating that an actionable consent-related change has occurred and that you should check the various consent properties and act accordingly. This callback is optional, as your app can alternatively check the current status of ICM when most appropriate for the app, as you may only be able to show a prompt at specific times.

 

Get Consent Should Prompt:

Method: Tracker.GetConsentShouldPrompt()
This method will return true when new consent must be gathered from the user. Typically this means that a new consent prompt dialogue should be displayed to the user as soon as possible. Once you are ready to show the consent dialogue prompt (or you’ve already shown it), make sure to call the SetConsentPrompted() method below so that this flag is consumed and does not remain true.

 

Set Consent Prompted:

Method: Tracker.SetConsentPrompted()
Call this method immediately before displaying the consent prompt dialogue to the user. By doing so, the Kochava SDK will be aware the user has seen the prompt and will consume the GetShouldPrompt() flag. This ensures the user will not be prompted again until an acceptable amount of time has elapsed, which is set in your Kochava dashboard.

 

Set Consent Granted:

Method: Tracker.SetConsentGranted()
Call this method when the user has explicitly granted (true) or declined (false) consent. This will typically occur after displaying your consent dialogue. Do not call this method if the user does not provide an answer.

 

Get Consent Required:

Method: Tracker.GetConsentRequired()
This method will return whether or not consent is required for this user, which is based on the users location and the region you have chosen when setting up ICM in your Kochava dashboard. If you have set ICM to global, this will always be true. If you have set ICM to EU this will only return true when Kochava has determined the user to be located within the EU (the GDPR coverage area).

 

Get Consent Granted:

Method: Tracker.GetConsentGranted()
This method will return whether or not the user has explicitly granted consent. This should always be checked in tandem with GetConsentRequired() before executing your consent-required logic, as such logic may be executed if either consent is not required or consent has been granted. You can alternatively call the helper method below (GetConsentGrantedOrNotRequired) to accomplish both of these checks.

 

Get Consent Granted or not Required:

Method: Tracker.GetConsentGrantedOrNotRequired()
This helper method returns true if consent is either not required or has been granted (a combination of the two methods listed above). Any consent required logic should be wrapped in this check.

 

Get Consent Partner List:

Method: Tracker.GetConsentPartners()
This method returns a stringified json object which contains the names of partners you have setup in your Kochava dashboard. Unless you have a specific use case for a list of partner names at runtime, you should not need to call this method.


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: Jul 31, 2018 at 9:04 am