Xamarin – Using the SDK

The following document describes the common use cases for the Kochava SDK after integration is complete. For information on integrating the SDK or configuring and starting the Tracker, refer to our Xamarin SDK Integration support documentation.

 

IMPORTANT NOTE: App Tracking Transparency (ATT) implementation is required for Free App Analytics. ONLY devices that have opted-in and have IDFA available will be measured and available in primary reporting and analytics.

10 Minutes
Estimated Time to Complete
10 Minutes

 

SDK VERSION NOTE: This feature requires Kochava SDK Version 3.1.0 or higher.

SDK PLATFORM NOTE: This feature is applicable to iOS platforms only.

 

No special code is needed to support SKAdNetwork, beyond tracking your existing events which are eligible for conversion. However, events which are to be considered for SKAdNetwork conversion updates must be built using standard parameters, rather than using an existing serialized/stringified json object for event data. See the topic “Tracking Events” for more detail on using standard parameters.

 

After setting up SKAdNetwork in your Free App Analytics’ dashboard, the SDK will automatically:

  1. Call Apple’s SKAdNetwork registration at the first opportunity following launch.
  2. When an eligible conversion event is triggered on iOS 14, the SDK will calculate the appropriate conversion value based on the event’s properties and automatically call Apple’s SKAdNetwork conversion update.

Generating SKAdNetwork Postbacks:

While the SDK automatically makes the necessary Apple API calls for you, a SKAdNetwork postback will only be generated if requirements are met for both the source app and advertised app. The advertised app must have been reviewed and available for download in the App Store, while the source app (where the ad is displayed) can be one that you are currently developing and run from Xcode or through TestFlight. Be sure to use the correct SKStoreProductParameterAdNetworkSourceAppStoreIdentifier per your case.

For testing purposes, you can cut down on the 24 hour postback wait by using the “SKAdNetwork Profile” from the Apple developer console here: https://developer.apple.com/download/more/ (search for “skad”).

30 Minutes
Estimated Time to Complete
30 Minutes

 

SDK VERSION NOTE: This feature requires Kochava SDK Version 3.1.0 or higher.

SDK PLATFORM NOTE: This feature is applicable to iOS platforms only.

 

As of iOS 14, IDFA collection is gated behind Apple’s new AppTrackingTransparency (ATT) permission-based authorization. This means that when an app is running on iOS 14, the IDFA is not available for collection until after the user grants permission, similar to any other iOS permission-based collection. However, Apple is delaying enforcement of ATT, which is discussed below.

Enforcing ATT for IDFA Collection

The SDK makes this very simple for you. All you need to do is tell the SDK you want to enable ATT enforcement during configuration.

As a tracking requirement by Apple, you must include in your info.plist the key NSUserTrackingUsageDescription and a string value explaining why you are requesting authorization to track. This text will be included in the prompt displayed by the operating system when tracking authorization is requested.

Configure the SDK

During SDK configuration, tell the SDK you wish to enable ATT enforcement. By default, the user will be prompted for tracking authorization one time, upon launch, and the SDK will allow up to 30 seconds for the user to answer the tracking authorization prompt. You may adjust this behavior if you wish.

 

Example Enabling ATT with default settings (recommended):

  • KochavaTracker.Instance.EnableIosAtt();

KochavaTracker.Instance.RegisterAndroidAppGuid("YOUR_ANDROID_APP_GUID");
KochavaTracker.Instance.RegisterIosAppGuid("YOUR_IOS_APP_GUID");
KochavaTracker.Instance.Start();


  • Kochava.Tracker.Configuration config = new Kochava.Tracker.Configuration();
config.AppTrackingTransparencyEnabled = true;
config.AndroidAppGuid = "YOUR_ANDROID_APP_GUID";
config.IosAppGuid = "YOUR_IOS_APP_GUID";
Kochava.Tracker.Client.Configure(config);

 

Example Allow more than the default 30 seconds for the user to respond:

  • KochavaTracker.Instance.EnableIosAtt();
KochavaTracker.Instance.SetIosAttAuthorizationWaitTime(90);

KochavaTracker.Instance.RegisterAndroidAppGuid("YOUR_ANDROID_APP_GUID");
KochavaTracker.Instance.RegisterIosAppGuid("YOUR_IOS_APP_GUID");
KochavaTracker.Instance.Start();

  • Kochava.Tracker.Configuration config = new Kochava.Tracker.Configuration();
config.AppTrackingTransparencyEnabled = true;
config.AppTrackingTransparencyWaitTime = 90.0;
config.AndroidAppGuid = "YOUR_ANDROID_APP_GUID";
config.IosAppGuid = "YOUR_IOS_APP_GUID";
Kochava.Tracker.Client.Configure(config);

 

At this point you are done. The user will be prompted for tracking authorization one time, during the first launch of the app, and the IDFA will be gathered if authorization is granted.

For purposes of testing, you will need to uninstall and reinstall the app each time you wish for the tracking prompt to appear, as Apple will only allow this to be displayed once.

Optionally, if you wish to prompt the user for tracking authorization at a specific moment or you do not want the SDK to trigger the prompt, continue reading below.

Custom Prompt Timing (Optional)

Follow these steps only if you wish for the tracking authorization prompt to be displayed at a time other than when the app is first launched or you do not want the SDK to trigger the prompt.

In order to accomplish this, first configure the SDK so that it does not automatically request authorization and allows enough time for the user to reach the point where tracking authorization will be requested at the moment of your choosing. In this example, we are allowing up to 120 seconds for the user to provide an answer to the tracking authorization request.

 

Example Configure the SDK:

  • KochavaTracker.Instance.EnableIosAtt();
KochavaTracker.Instance.SetIosAttAuthorizationWaitTime(120);
KochavaTracker.Instance.SetIosAttAuthorizationAutoRequest(false);

KochavaTracker.Instance.RegisterAndroidAppGuid("YOUR_ANDROID_APP_GUID");
KochavaTracker.Instance.RegisterIosAppGuid("YOUR_IOS_APP_GUID");
KochavaTracker.Instance.Start();

  • Kochava.Tracker.Configuration config = new Kochava.Tracker.Configuration();
config.AppTrackingTransparencyEnabled = true;
config.AppTrackingTransparencyWaitTime = 120.0;
config.AppTrackingTransparencyAutoRequest = false;
config.AndroidAppGuid = "YOUR_ANDROID_APP_GUID";
config.IosAppGuid = "YOUR_IOS_APP_GUID";
Kochava.Tracker.Client.Configure(config);

 

Secondly, add code which requests the tracking authorization at the time of your choosing and then notifies the SDK when the authorization request completes. It is your responsibility to ensure your tracking authorization request code is reached. If it is not, the timeout will be reached and the SDK will proceed without collecting the IDFA.

NOTE: Regardless of how many times you request tracking authorization, the user is only prompted once. This means you can repeatedly request tracking authorization at a specific moment per app launch and the user will only be prompted once, the first time the code is reached.

 

Example Request authorization and notify the SDK upon completion:

  • // notify the Kochava SDK that it may proceed with tracking authorization
KochavaTracker.Instance.SetIosAttAuthorizationAutoRequest(true);

  • // notify the Kochava SDK that it may proceed with tracking authorization
Kochava.Tracker.Client.EnableAppTrackingTransparencyAutoRequest();

App Store Submission Guidance and Best Practices

Developing Section: The information contained within this section is subject to change as Apple shares more information and their requirements evolve.

 

If you have added the NSUserTrackingUsageDescription entry to your info.plist and/or are referencing the ATT framework, Apple expects to visibly see the ATT prompt during the review process of your submission. At the time of this writing, the App Store submission guidelines do not state this requirement, but Apple has cited this as cause for rejection.

If the ATT prompt is not automatically triggered upon launch, we suggest that you include instructions for the reviewer detailing the steps they must take to trigger the ATT prompt. If you’ve forcibly disabled the ATT prompt whether through our UI or otherwise, you must add a review note indicating that you are not invoking the ATT consent prompt until the release of iOS 14.5.

NOTE: Apple may reject apps which attempt to preempt the ATT prompt with a soft prompt of any kind. We suggest that you avoid this approach and allow the ATT prompt to be triggered immediately upon launch.

15 Minutes
Estimated Time to Complete
15 Minutes

 

SDK VERSION NOTE: This feature requires Kochava SDK Version 3.1.0 or higher.

SDK PLATFORM NOTE: This feature is applicable to Android platforms only.

 

The standard SDK is used within your instant app (no special variant of the SDK is needed for an instant app).

In order to properly support user and attribution flow between the instant app and full app, the following steps must be taken.

 

Create two App GUIDs:

The instant app and full app should not use the same App GUID. For the instant app, create or use a Free App Analytics app of platform type Android – Instant App. For the full app, create or use a Free App Analytics app of platform type Android.

 

Configure the SDK:

You will need to provide the Instant App GUID to both the instant app and the full app. This must be done prior to starting the SDK. The SDK will automatically choose the correct app GUID to use.

  • KochavaTracker.Instance.EnableAndroidInstantApps("YOUR_ANDROID_INSTANT_APP_GUID");

KochavaTracker.Instance.RegisterAndroidAppGuid("YOUR_ANDROID_APP_GUID");
KochavaTracker.Instance.RegisterIosAppGuid("YOUR_IOS_APP_GUID");
KochavaTracker.Instance.Start();


  • Kochava.Tracker.Configuration config = new Kochava.Tracker.Configuration();
config.AndroidInstantAppGuid = "YOUR_ANDROID_INSTANT_APP_GUID";
config.AndroidAppGuid = "YOUR_ANDROID_APP_GUID";
config.IosAppGuid = "YOUR_IOS_APP_GUID";
Kochava.Tracker.Client.Configure(config);

 

Process the Deeplink:

When the instant app is launched, pass the invocation URL to the SDK’s Process Deeplink API as soon as possible, just as you would any other deeplink. See the topic Enhanced Deeplinking for complete instructions on how to use the Process Deeplink API.

By taking these steps, all functionality related to attribution, analytics, and measurement will be properly implemented between the app clip and full app.

 

Supporting Older Android Versions:

Instant Apps are natively supported on Android 8 (API 26) and higher with data being automatically migrated from the instant app to the full app. If supporting Android 7 or lower you are responsible for migrating the SDK’s data prior to starting the SDK. See the documentation on transferring data.

15 Minutes
Estimated Time to Complete
15 Minutes

 

SDK VERSION NOTE: This feature requires Kochava SDK Version 3.1.1 or higher.

SDK PLATFORM NOTE: This feature is applicable to iOS platforms only.

 

The standard SDK is used within your app clip app (no special variant of the SDK is needed for an app clip).

In order to properly support user and attribution flow between the app clip and full app, the following steps must be taken.

 

Create Two App GUIDs:

The app clip and full app should not use the same App GUID. For the app clip, create or use a Free App Analytics app of platform type iOS – App Clip. For the full app, create or use a Free App Analytics app of platform type iOS.

 

Configure the SDK:

You will need to provide an app group identifier string which facilitates shared storage between the app clip and full app. To accomplish this, in Xcode under the project Signing & Capabilities, add a new capability for App Groups if you do not have one already using the plus button. For the new identifier, start with your app’s bundle identifier and then prefix it with group. and suffix it with .kochava. Provide this identifier to the SDK prior to starting the SDK. This identifier must be the same between the app clip and full app.

 

Example Provide a Shared Storage Container Before Starting the Tracker:

  • KochavaTracker.Instance.EnableIosAppClips("group.com.kochava.host.kochava");

KochavaTracker.Instance.RegisterAndroidAppGuid("YOUR_ANDROID_APP_GUID");
KochavaTracker.Instance.RegisterIosAppGuid("YOUR_IOS_APP_GUID");
KochavaTracker.Instance.Start();


  • Kochava.Tracker.Configuration config = new Kochava.Tracker.Configuration();
config.IosContainerAppGroupIdentifier = "group.com.kochava.host.kochava";
config.AndroidAppGuid = "YOUR_ANDROID_APP_GUID";
config.IosAppGuid = "YOUR_IOS_APP_GUID";
Kochava.Tracker.Client.Configure(config);

NOTE: The SDK detects your app clip by looking for the bundle identifier’s default .clip suffix.

 

Process the Deeplink:

When the instant app is launched, pass the invocation URL to the SDK’s Process Deeplink API as soon as possible, just as you would any other deeplink. See the topic Enhanced Deeplinking for complete instructions on how to use the Process Deeplink API.

By taking these steps, all functionality related to attribution, analytics, and measurement will be properly implemented between the app clip and full app.

 

Standard Events:

 

Example (Standard Event with Standard Parameters) —

  • var koEvent = KochavaTracker.Instance.BuildEventWithEventType(KochavaTrackerEventType.Purchase);
koEvent.SetName("Gold Token");
koEvent.SetPrice(0.99);
koEvent.Send();

  • var koEvent = new Kochava.Tracker.Event(Kochava.Tracker.EventType.Purchase);
koEvent.Name = "Gold Token";
koEvent.Price = 0.99;
Kochava.Tracker.Client.SendEvent(koEvent);

 

Example (Standard Event with Standard and Custom Parameters) —

  • var koEvent = KochavaTracker.Instance.BuildEventWithEventType(KochavaTrackerEventType.LevelComplete);
koEvent.SetName("The Deep Dark Forest");
koEvent.SetCustomNumberValue("attempts", 3);
koEvent.SetCustomNumberValue("score", 12000);
koEvent.Send();

  • var koEvent = new Kochava.Tracker.Event(Kochava.Tracker.EventType.LevelComplete);
koEvent.Name = "The Deep Dark Forest";
koEvent.SetCustomValue("attempts", 3);
koEvent.SetCustomValue("score", 12000);
Kochava.Tracker.Client.SendEvent(koEvent);

 

If you wish to use a custom event type with standard parameters, use a custom event name string within your event constructor in place of a standard event type.

 

For a detailed list of standard event types and parameters, see: Post Install Event Examples

Custom Events:

 

Example (Custom Event with Custom Parameters) —

  • var koEvent = KochavaTracker.Instance.BuildEventWithEventName("Enemy Defeated");
koEvent.SetCustomStringValue("enemy", "The Angry Ogre");
koEvent.SetCustomStringValue("reward", "Gold Token");
koEvent.Send();

  • var koEvent = new Kochava.Tracker.Event("Enemy Defeated");
koEvent.SetCustomValue("enemy", "The Angry Ogre");
koEvent.SetCustomValue("reward", "Gold Token");
Kochava.Tracker.Client.SendEvent(koEvent);

 

Example (Send a Custom Event with Only a Name, no Event Data) —

  • KochavaTracker.Instance.SendEvent("Player Defeated");
  • Kochava.Tracker.Client.SendEventString("Player Defeated", "");

 

Example (Send a Custom Event with Event Data) —

  • KochavaTracker.Instance.SendEventWithString("Player Defeated", "Angry Ogre");
  • Kochava.Tracker.Client.SendEventString("Player Defeated", "Angry Ogre");

 

Example (Send a Custom Event with Serialized JSON Data) —

  • var dictionary = new JObject();
dictionary.Add("enemy", "Angry Ogre");
KochavaTracker.Instance.SendEventWithDictionary("Player Defeated", dictionary);

  • Kochava.Tracker.Client.SendEventString("Player Defeated", "{\"enemy\":\"Angry Ogre\"}");

 

 

10 Minutes
Estimated Time to Complete
10 Minutes

 

Kochava events can include a variety of parameters that are typically set when instrumenting the event. It is sometimes desirable to have parameters included on every event in order to better link multiple events. A common use case for this is to set a User ID for the currently logged in user. The default event parameters support provides this capability by allowing default parameters to be registered that will be included on every future event and be persisted across app launches.

 

SDK Note: This feature requires Kochava SDK Version 4.4.0 or higher.

 

Example (Register a Default User ID):

The default User ID can be set or updated by calling the register method with the desired value.

KochavaTracker.Instance.RegisterDefaultEventUserId("6327adba-a9eb-4bcf-a4ec-b2c8ef1d3fe3");

 

Example (Remove a Default User ID):

The default User ID can be removed by calling the register method with a value of null/nil.

KochavaTracker.Instance.RegisterDefaultEventUserId(null);

 

Example (Register a Default Parameter):

A default parameter can be set or updated by calling the register method with the key name to set and the desired value. The basic types String, Number, and Bool are supported.

KochavaTracker.Instance.RegisterDefaultEventStringParameter("key","value");
KochavaTracker.Instance.RegisterDefaultEventNumberParameter("key", 1234.0);
KochavaTracker.Instance.RegisterDefaultEventBoolParameter("key", true);

 

Example (Remove a Default Parameter):

A default parameter can be removed by calling the register method with the key to remove and a value of null/nil.

KochavaTracker.Instance.RegisterDefaultEventStringParameter("key", null);

NOTE: If the same key name exists as a default parameter and was also directly set on the event, the value set on the event will take precedence over the default value.

 

Example (Standard Purchase Event):

  • var koEvent = KochavaTracker.Instance.BuildEventWithEventType(KochavaTrackerEventType.Purchase);
koEvent.SetName("Loot Box");
koEvent.SetPrice(4.99);
koEvent.SetAndroidGooglePlayReceipt(receiptData, receiptSignature); // Android Only
koEvent.SetIosAppStoreReceipt(appStoreReceiptBase64EncodedString); // iOS Only
koEvent.Send();

  • var koEvent = new Kochava.Tracker.Event(Kochava.Tracker.EventType.Purchase);
koEvent.Name = "Loot Box";
koEvent.Price = 4.99;
koEvent.SetReceiptFromGooglePlayStore(receiptData, receiptSignature); // Android Only
koEvent.SetReceiptFromAppleAppStore(appStoreReceiptBase64EncodedString); // iOS Only
Kochava.Tracker.Client.SendEvent(koEvent);

 

Example (Custom Purchase Event with Additional JSON Data):

  • KochavaTracker.Instance.SendEventWithString("Purchase", "{\"price\":4.99,\"name\":\"Loot Box\"}");
  • Kochava.Tracker.Client.SendEventString("Purchase", "{\"price\":4.99,\"name\":\"Loot Box\"}");

10 Minutes
Estimated Time to Complete
10 Minutes

In order to effectively track user subscriptions and free trials, an event should be instrumented at the time of the subscription purchase or start of the free trial along with an accompanying identity link.

When a subscription or free trial begins, first set an identity link for this subscriber and then instrument a standard Subscription or Trial event populated with the following values:

  • Price
  • Currency
  • Product Name
  • User or Subscriber ID (hash suggested)
  • Receipt (if available)

 

BEST PRACTICES: Always set the identity link before sending the event, otherwise the identity link will not be properly associated with the event.

 

Example (Identity Link with Subscription):

  • // first set an identity link for this user
KochavaTracker.Instance.RegisterIdentityLink("Subscriber ID", "ABCDEF123456789");

// next, instrument the subscription event
var koEvent = KochavaTracker.Instance.BuildEventWithEventType(KochavaTrackerEventType.Subscribe);
koEvent.SetCurrency("usd");
koEvent.SetName("Monthly Subscription");
koEvent.SetPrice(9.99);
koEvent.SetUserId("ABCDEF123456789");
koEvent.SetAndroidGooglePlayReceipt(receiptData, receiptSignature); // Android Only
koEvent.SetIosAppStoreReceipt(appStoreReceiptBase64EncodedString); // iOS Only
koEvent.Send();

  • // first set an identity link for this user
IDictionary<string, string> identityLink = new Dictionary<string, string>();
identityLink.Add("Subscriber ID": "ABCDEF123456789");
Kochava.Tracker.Client.SetIdentityLink(identityLink);

// next, instrument the subscription event
var koEvent = new Kochava.Tracker.Event(Kochava.Tracker.EventType.Subscribe);
koEvent.Currency = "usd";
koEvent.Name = "Monthly Subscription";
koEvent.Price = 9.99;
koEvent.UserId = "ABCDEF123456789";
koEvent.SetReceiptFromGooglePlayStore(receiptData, receiptSignature); // Android Only
koEvent.SetReceiptFromAppleAppStore(appStoreReceiptBase64EncodedString); // iOS Only
Kochava.Tracker.Client.SendEvent(koEvent);

 

A free trial is handled in a similar way, although the price should be set to 0 and the event type should indicate Trial rather than Subscription. The product name should remain the same, as the event type indicates whether this was free trial or subscription.

 

Example (Identity Link with Free Trial):

  • // first set an identity link for this user
KochavaTracker.Instance.RegisterIdentityLink("Subscriber ID", "ABCDEF123456789");

// next, instrument the trial event
var koEvent = KochavaTracker.Instance.BuildEventWithEventType(KochavaTrackerEventType.StartTrial);
koEvent.SetCurrency("usd");
koEvent.SetName("Monthly Subscription");
koEvent.SetPrice(0.0);
koEvent.SetUserId("ABCDEF123456789");
koEvent.SetAndroidGooglePlayReceipt(receiptData, receiptSignature); // Android Only
koEvent.SetIosAppStoreReceipt(appStoreReceiptBase64EncodedString); // iOS Only
koEvent.Send();

  • // first set an identity link for this user
IDictionary<string, string> identityLink = new Dictionary<string, string>();
identityLink.Add("Subscriber ID": "ABCDEF123456789");
Kochava.Tracker.Client.SetIdentityLink(identityLink);

// next, instrument the trial event
var koEvent = new Kochava.Tracker.Event(Kochava.Tracker.EventType.StartTrial);
koEvent.Currency = "usd";
koEvent.Name = "Monthly Subscription";
koEvent.Price = 0.0;
koEvent.UserId = "ABCDEF123456789";
koEvent.SetReceiptFromGooglePlayStore(receiptData, receiptSignature); // Android Only
koEvent.SetReceiptFromAppleAppStore(appStoreReceiptBase64EncodedString); // iOS Only
Kochava.Tracker.Client.SendEvent(koEvent);

 

 

Example (Standard Deeplink Event):

  • var koEvent = KochavaTracker.Instance.BuildEventWithEventType(KochavaTrackerEventType.Deeplink);
koEvent.SetUri("some_deeplink_uri");
koEvent.Send();

  • var koEvent = new Kochava.Tracker.Event(Kochava.Tracker.EventType.Deeplink);
koEvent.Uri = "some_deeplink_uri";
Kochava.Tracker.Client.SendEvent(koEvent);

10 Minutes
Estimated Time to Complete
10 Minutes

 

SDK VERSION NOTE: This feature requires Kochava SDK Version 3.0.0 or higher.

 

 

Example (Acquire the Deeplink) —

  • // acquire a deeplink whenever one is available and pass it to the SDK.
var deeplinkUrl = "todo";
KochavaTracker.Instance.ProcessDeeplink(deeplinkUrl, (deeplink) =>
{
    // deeplink result handler.
});

  • // acquire a deeplink whenever one is available and pass it to the SDK.
var deeplinkUrl = "todo";
Kochava.Tracker.Client.ProcessDeeplink(deeplinkUrl, (deeplink) =>
{
    // deeplink result handler.
});

 

Example (Wait for the Callback) —

  • KochavaTracker.Instance.ProcessDeeplink(deeplinkUrl, (deeplink) =>
{
    var destination = deeplink.Destination;
    if (destination != "")
    {
        // deeplink exists, parse the destination as you see fit and route the user
    }
    else
    {
        // no deeplink to act upon, route to a default destination or take no action
    }
});

  • Kochava.Tracker.Client.ProcessDeeplink(deeplinkUrl, (deeplink) =>
{
    if (!string.IsNullOrEmpty(deeplink.Destination))
    {
        // deeplink exists, parse the destination as you see fit and route the user
    }
    else
    {
        // no deeplink to act upon, route to a default destination or take no action
    }
});

 

 

Example (Register an Identity Link During Tracker Configuration):

  • KochavaTracker.Instance.RegisterIdentityLink("User ID", "123456789");
KochavaTracker.Instance.RegisterIdentityLink("Login", "username");

KochavaTracker.Instance.RegisterAndroidAppGuid("YOUR_ANDROID_APP_GUID");
KochavaTracker.Instance.RegisterIosAppGuid("YOUR_IOS_APP_GUID");
KochavaTracker.Instance.Start();

  • IDictionary<string, string> identityLink = new Dictionary<string, string>();
identityLink.Add("User ID", "123456789");
identityLink.Add("Login", "username");

Kochava.Tracker.Configuration config = new Kochava.Tracker.Configuration();
config.AndroidAppGuid = "YOUR_ANDROID_APP_GUID";
config.IosAppGuid = "YOUR_IOS_APP_GUID";
config.LogLevel = Kochava.Tracker.LogLevel.Trace;
config.IdentityLink = identityLink;
Kochava.Tracker.Client.Configure(config);

 

Example (Register an Identity Link After Starting the Tracker):

  • KochavaTracker.Instance.RegisterIdentityLink("User ID", "123456789");
KochavaTracker.Instance.RegisterIdentityLink("Login", "username");

  • IDictionary<string, string> identityLink = new Dictionary<string, string>();
identityLink.Add("User ID", "123456789");
identityLink.Add("Login", "username");
Kochava.Tracker.Client.SetIdentityLink(identityLink);

 

Example (Requesting Attribution Results):

  • // This callback handler will fire on every launch. Optionally check the retrievedBool if you wish to only parse these results once.
var currentInstallAttribution = KochavaTracker.Instance.GetInstallAttribution();
if (!currentInstallAttribution.Retrieved)
{
    KochavaTracker.Instance.RetrieveInstallAttribution((installAttribution) => {
        // do something with the attribution result
    });
}

  • Kochava.Tracker.Configuration config = new Kochava.Tracker.Configuration();
config.AndroidAppGuid = "YOUR_ANDROID_APP_GUID";
config.IosAppGuid = "YOUR_IOS_APP_GUID";
config.RetrieveAttribution = true;
Kochava.Tracker.Client.Configure(config);

Kochava.Tracker.Client.SetAttributionListener((string attribution) =>
{
    // Parse json serialized attribution info.
});

 

Example (Using the Getter After Attribution Results Have Been Retrieved):

  • var installAttribution = KochavaTracker.Instance.GetInstallAttribution();
  • string attribution = Kochava.Tracker.Client.GetAttribution();
// Parse json serialized attribution info.

 

 

 

Example (Getting the Kochava Device ID):

  • var deviceId = KochavaTracker.Instance.GetDeviceId();
  • string deviceId = Kochava.Tracker.Client.GetDeviceId();

 

Example (Enabling App Limit Ad Tracking During Tracker Configuration):

  • KochavaTracker.Instance.SetAppLimitAdTracking(true);

KochavaTracker.Instance.RegisterAndroidAppGuid("YOUR_ANDROID_APP_GUID");
KochavaTracker.Instance.RegisterIosAppGuid("YOUR_IOS_APP_GUID");
KochavaTracker.Instance.Start();

  • Kochava.Tracker.Configuration config = new Kochava.Tracker.Configuration();
config.AndroidAppGuid = "YOUR_ANDROID_APP_GUID";
config.IosAppGuid = "YOUR_IOS_APP_GUID";
config.AppLimitAdTracking = true;
Kochava.Tracker.Client.Configure(config);

 

Example (Enable App Limit Ad Tracking After Starting the Tracker):

  • KochavaTracker.Instance.SetAppLimitAdTracking(true);
  • Kochava.Tracker.Client.SetAppLimitAdTracking(true);

 

Example (Enabling trace logging in a non-production build):

  • if(DEBUG)
{
    KochavaTracker.Instance.SetLogLevel(KochavaTrackerLogLevel.Trace);
} else
{
    KochavaTracker.Instance.SetLogLevel(KochavaTrackerLogLevel.Info);
}

KochavaTracker.Instance.RegisterAndroidAppGuid("YOUR_ANDROID_APP_GUID");
KochavaTracker.Instance.RegisterIosAppGuid("YOUR_IOS_APP_GUID");
KochavaTracker.Instance.Start();

  • Kochava.Tracker.Configuration config = new Kochava.Tracker.Configuration();
config.AndroidAppGuid = "YOUR_ANDROID_APP_GUID";
config.IosAppGuid = "YOUR_IOS_APP_GUID";
if(DEBUG)
{
    config.LogLevel = Kochava.Tracker.LogLevel.Trace;
} else
{
    config.LogLevel = Kochava.Tracker.LogLevel.Info;
}
Kochava.Tracker.Client.Configure(config);

 

 

Example (Enabling Sleep Mode During Tracker Configuration):

  • KochavaTracker.Instance.SetSleep(true);

KochavaTracker.Instance.RegisterAndroidAppGuid("YOUR_ANDROID_APP_GUID");
KochavaTracker.Instance.RegisterIosAppGuid("YOUR_IOS_APP_GUID");
KochavaTracker.Instance.Start();

  • Kochava.Tracker.Configuration config = new Kochava.Tracker.Configuration();
config.AndroidAppGuid = "YOUR_ANDROID_APP_GUID";
config.IosAppGuid = "YOUR_IOS_APP_GUID";
config.Sleep = true;
Kochava.Tracker.Client.Configure(config);

 

Example (Enabling Sleep Mode After Starting the Tracker):

  • KochavaTracker.Instance.SetSleep(true);
  • Kochava.Tracker.Client.SetSleep(true);

 

 

Example (Waking the Tracker from Sleep Mode) —

  • KochavaTracker.Instance.SetSleep(false);
  • Kochava.Tracker.Client.SetSleep(false);

 

5 Minutes
Estimated Time to Complete
5 Minutes

 

SDK VERSION NOTE: This feature requires Kochava SDK Version 4.0.0 or higher.

 

KochavaTracker.Instance.Shutdown(false);

 

Clearing SDK Data:

The shutdown() method accepts a boolean indicating whether you wish to also clear all persisted SDK data from disk when shutting down. This should always be set to false and should never be set to true without a complete understanding of the ramifications of clearing this data, as it could create duplicate user metrics or worse.

 

Example (Shut Down the SDK and Clear Data) —

// WARNING: This is a destructive action, ensure you understand the ramifications of deleting data before using.
KochavaTracker.Instance.Shutdown(true);

 

5 Minutes
Estimated Time to Complete
5 Minutes

 

Example (Starting the Tracker Only When Consent Allows) —

  • if (!consentRequired || consentGranted)
{
    // we will not initialize Kochava unless consent requirements are met.
    KochavaTracker.Instance.RegisterAndroidAppGuid("YOUR_ANDROID_APP_GUID");
    KochavaTracker.Instance.RegisterIosAppGuid("YOUR_IOS_APP_GUID");
    KochavaTracker.Instance.Start();
}

  • if (!consentRequired || consentGranted)
{
    // we will not initialize Kochava unless consent requirements are met.
    Kochava.Tracker.Configuration config = new Kochava.Tracker.Configuration();
    config.AndroidAppGuid = "YOUR_ANDROID_APP_GUID";
    config.IosAppGuid = "YOUR_IOS_APP_GUID";
    Kochava.Tracker.Client.Configure(config);
}

 

Example (Calling Tracker Methods Only When Consent Allows) —

  • if (!consentRequired || consentGranted)
{
    // we will not call Kochava methods unless consent requirements are met.
    KochavaTracker.Instance.SendEvent("My Event");
}

  • if(!consentRequired || consentGranted)
{
    // we will not call Kochava methods unless consent requirements are met.
    Kochava.Tracker.Client.SendEventString("My Event", "");
}

5 Minutes
Estimated Time to Complete
5 Minutes

 

1 Day
Estimated Time to Complete
1 Day

 

SDK VERSION NOTE: This feature has been deprecated as of Kochava SDK version 4.0.0.

 

As GDPR can present many challenges during development, Free App Analytics offers a fully managed solution for all your GDPR consent requirements through the use of our Intelligent Consent Managerfeature. By using this feature the Kochava SDK will handle determining when consent is required for any user while shouldering much the GDPR burden for you. For complete details on how this feature works, see: Intelligent Consent Manager.

10 Minutes
Estimated Time to Complete
10 Minutes

 

SDK Version Note: This feature requires Kochava SDK Version 4.4.0 or higher.

This topic describes how to restrict data egress from the device and is considered an advanced feature which is unnecessary for a typical SDK integration. Improper usage could detrimentally impact measurement and attribution and should be avoided unless you have a specific need.

For purposes of measurement and attribution, the SDK automatically transmits certain device information and device identifiers which are commonly referred to as ‘datapoints’. For privacy reasons or otherwise, there may be times you wish to restrict these datapoints from egressing from the device. For more information around what datapoints the SDK transmits, view the Data Privacy and Safety document.

Restricting the egress of a datapoint can be done one of two ways and is dependent on whether you want the restriction to apply to all users of the app or conditionally on a per-user basis.

 

App Wide Restriction

If you wish to unconditionally prevent the collection and egress of a datapoint for all users of your app, this can be done by disabling the desired datapoint within the Advanced section of the edit app page in your Kochava dashboard. Disabling a datapoint in this manner will automatically instruct the SDK not to collect or allow egress of said datapoint from the device for all users. No code is required for this approach and if this satisfies your requirements there is no need to read any further.

 

Conditional Restriction

If you wish to conditionally restrict datapoint egress on a per-user basis, or you wish to restrict egress of a datapoint not available in your Free App Analytics dashboard, follow the steps below. For example, you may wish to restrict the egress of the device identifiers only for child users or only for users who do not meet other criteria.

Conditionally restricting datapoint egress requires two steps in code:

  1. Create a privacy profile with a list of datapoint key names to restrict.
  2. Enable the privacy profile if restrictions should apply to this user.

 

Create a Privacy Profile:

A privacy profile is a named collection of datapoints which may be restricted for the current user. Privacy profiles must be both created and then enabled before datapoint restriction will take place. Typically, you will create all possible privacy profiles when starting the SDK, and then enable only those which apply to the current user.

You may create multiple privacy profiles, one for each category of restriction you would like to apply. For example, you might create a privacy profile named “child” which includes datapoints you would like to restrict for children. Or, you might create a privacy profile named “always” which includes datapoints you’d like to always restrict for all users. The name of the privacy profile may not begin with an underscore “_” and must be a non-empty string, but is otherwise arbitrary and may be anything you like.

 

Enable a Privacy Profile:

Privacy profiles are not enabled by default, and datapoint egress is not restricted until the privacy profile is enabled. Once you have created a privacy profile, at some point you must also enable it in order to restrict datapoint egress for the current user. A privacy profile is enabled or disabled through a single API call by referencing its name.

Once a privacy profile is enabled, from that moment on its datapoints will no longer egress from the device. Restrictions are enforced from the moment a privacy profile is enabled and are not applied retroactively; it is your responsibility to ensure applicable privacy profiles are enabled prior to the moment when datapoint egress would take place. For example, if you queue an event but do not enable a privacy profile until after queuing the event, the event will egress with all datapoints intact because the privacy profile was not enabled at the time of egress.

If necessary, a privacy profile may be disabled via the same API call used to enable it.

NOTE: The lifecycle of a privacy profile and its enabled status is limited to the current tracker instance and does not persist between app launches or SDK tracker instances. Privacy profiles must be created and enabled each time the SDK is started.

 

Example (Always Restrict Device Identifier Egress) —

In this example, we want to prevent the device identifiers from being transmitted from the device for all users. Start the tracker and then immediately create and enable a privacy profile named “restrict ids” with the datapoint keys for your platform’s device identifiers.

// create the privacy profile
KochavaTracker.Instance.RegisterPrivacyProfile("restrict_ids", new[] { "adid", "android_id", "idfa" })

// enable the privacy profile for this user
KochavaTracker.Instance.SetPrivacyProfileEnabled("restrict_ids", true)

// start the tracker
KochavaTracker.Instance.RegisterAndroidAppGuid("YOUR_ANDROID_APP_GUID");
KochavaTracker.Instance.RegisterIosAppGuid("YOUR_IOS_APP_GUID");
KochavaTracker.Instance.Start();

// ...for the remainder of this app launch, measurement signal from the SDK will not include the ADID, Android ID, or IDFA

 

Example (Restrict Device Identifier Egress for Children) —

In this example, we want to prevent the device identifiers from being transmitted from the device only for children. This concept works for any scenario where conditional restriction is necessary.

In order to accomplish this, the SDK must not be started until we know whether the user is a child. Once we know that, we start the SDK and then enable our “child” privacy profile only if the user was determined to be a child. For this scenario, it’s important not to start the tracker until child status is known, because the SDK would otherwise immediately begin transmitting measurement signal including datapoints you may wish to restrict.

bool isChild = isChild()

// create a privacy profile for children
KochavaTracker.Instance.RegisterPrivacyProfile("child", new[] { "adid", "android_id", "idfa" })

// enable the privacy profile only if this user is a child
KochavaTracker.Instance.SetPrivacyProfileEnabled("child", isChild)

// start the tracker
KochavaTracker.Instance.RegisterAndroidAppGuid("YOUR_ANDROID_APP_GUID");
KochavaTracker.Instance.RegisterIosAppGuid("YOUR_IOS_APP_GUID");
KochavaTracker.Instance.Start();

  1. Use an alternate testing App GUID so that your testing activities do not have an impact on your live app analytics.
  2. Enable Logging, if helpful, to gain insight into the SDK’s behavior during runtime.
  3. If you would like the SDK to behave as it would during a new install, be sure to un-install the app before each test.
  4. Test your Kochava integration. For more information see: Testing the Integration.
  • if(DEBUG)
{
    KochavaTracker.Instance.SetLogLevel(KochavaTrackerLogLevel.Trace);

    KochavaTracker.Instance.RegisterAndroidAppGuid("YOUR_TEST_ANDROID_APP_GUID");
    KochavaTracker.Instance.RegisterIosAppGuid("YOUR_TEST_IOS_APP_GUID");
} else
{
    KochavaTracker.Instance.SetLogLevel(KochavaTrackerLogLevel.Info);

    KochavaTracker.Instance.RegisterAndroidAppGuid("YOUR_PRODUCTION_ANDROID_APP_GUID");
    KochavaTracker.Instance.RegisterIosAppGuid("YOUR_PRODUCTION_IOS_APP_GUID");
}
KochavaTracker.Instance.Start();

  • Kochava.Tracker.Configuration config = new Kochava.Tracker.Configuration();
if (DEBUG)
{
    config.LogLevel = Kochava.Tracker.LogLevel.Trace;
    config.AndroidAppGuid = "YOUR_TEST_ANDROID_APP_GUID";
    config.IosAppGuid = "YOUR_TEST_IOS_APP_GUID";          
}
else
{
    config.LogLevel = Kochava.Tracker.LogLevel.Info;
    config.AndroidAppGuid = "YOUR_PRODUCTION_ANDROID_APP_GUID";
    config.IosAppGuid = "YOUR_PRODUCTION_IOS_APP_GUID";
}
Kochava.Tracker.Client.Configure(config);

 

Analyzing SDK Behavior:

 
 
Last Modified: Oct 23, 2023 at 2:31 pm