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.
Confirming the SDK Integration:
Ensure the SDK has been properly integrated.
Supporting SKAdNetwork:
Kochava’s SKAdNetwork support is seamlessly integrated with standard event tracking.
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 Kochava dashboard, the SDK will automatically:
- Call Apple’s SKAdNetwork registration at the first opportunity following launch.
- 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.
AppTrackingTransparency and IDFA Collection:
Method for handling Apple’s new IDFA collection model.
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.
About ATT Non-Enforcement
In order to allow developers more time to adjust to the changes surrounding IDFA collection, Apple announced that tracking authorization via the ATT framework would not be required to collect the IDFA on iOS 14, until at least 2021. The IDFA will continue to be available for collection on iOS 14 no differently than it was on iOS 13 and prior. However, once an ATT request for authorization is made, IDFA availability then becomes subject to the results of tracking authorization from that point on. This means that you must decide whether to start prompting users for tracking authorization now or wait for Apple to provide a concrete timeline on when they will begin requiring tracking authorization at some time in the future.
If you do not yet wish to prompt the user for tracking authorization and enforce ATT, you do not need to take any additional steps and the SDK will continue to gather the IDFA until Apple begins requiring tracking authorization sometime in 2021.
If you wish to enforce ATT and begin prompting users for tracking authorization, continue reading below.
Enforcing ATT for IDFA Collection
The SDK makes this drop-dead 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):
|
1 2 3 4 5 |
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:
|
1 2 3 4 5 6 |
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:
|
1 2 3 4 5 6 7 |
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:
|
1 2 |
// notify the Kochava SDK that it may proceed with tracking authorization Kochava.Tracker.Client.EnableAppTrackingTransparencyAutoRequest(); |
Tracking Events:
Track user behavior and actions beyond the install.
Standard Events:
Example (Standard Event with Standard Parameters) —
|
1 2 3 4 |
var myEvent = new Kochava.Tracker.Event(Kochava.Tracker.EventType.Purchase); myEvent.Name = "Gold Token"; myEvent.Price = 0.99; Kochava.Tracker.Client.SendEvent(myEvent); |
Example (Standard Event with Standard and Custom Parameters) —
|
1 2 3 4 5 |
var myEvent = new Kochava.Tracker.Event(Kochava.Tracker.EventType.LevelComplete); myEvent.Name = "The Deep Dark Forest"; myEvent.SetCustomValue("attempts", 3); myEvent.SetCustomValue("score", 12000); Kochava.Tracker.Client.SendEvent(myEvent); |
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) —
|
1 2 3 4 5 |
var myEvent = new Kochava.Tracker.Event("Enemy Defeated"); myEvent.Name = "The Deep Dark Forest"; myEvent.SetCustomValue("enemy", "The Angry Ogre"); myEvent.SetCustomValue("reward", "Gold Token"); Kochava.Tracker.Client.SendEvent(myEvent); |
Example (Send a Custom Event with Only a Name, no Event Data) —
|
1 |
Kochava.Tracker.Client.SendEventString("Player Defeated", ""); |
Example (Send a Custom Event with Event Data) —
|
1 |
Kochava.Tracker.Client.SendEventString("Player Defeated", "Angry Ogre"); |
Example (Send a Custom Event with Serialized JSON Data) —
|
1 |
Kochava.Tracker.Client.SendEventString("Player Defeated", "{\"enemy\":\"Angry Ogre\"}"); |
Purchases:
Track in-app purchases and revenue.
Example (Standard Purchase Event):
-
12345var myEvent = new Kochava.Tracker.Event(Kochava.Tracker.EventType.Purchase);myEvent.Name = "Loot Box";myEvent.Price = 4.99;myEvent.SetReceiptFromGooglePlayStore(receiptData, receiptSignature);Kochava.Tracker.Client.SendEvent(myEvent);
-
12345var myEvent = new Kochava.Tracker.Event(Kochava.Tracker.EventType.Purchase);myEvent.Name = "Loot Box";myEvent.Price = 4.99;myEvent.SetReceiptFromAppleAppStore(appStoreReceiptBase64EncodedString);Kochava.Tracker.Client.SendEvent(myEvent);
Example (Custom Purchase Event with Serialized JSON Data):
|
1 |
Kochava.Tracker.Client.SendEventString("Purchase", "{\"price\":4.99,\"name\":\"Loot Box\"}"); |
Example (Custom Subscription Purchase Event with Serialized JSON Data) —
|
1 |
Kochava.Tracker.Client.SendEventString("Purchase", "{\"price\":9.99,\"name\":\"Monthly Subscription\"}"); |
Tracking Subscriptions and Trials:
Track user subscriptions and free trials.
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)
Example (Identity Link with Subscription):
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
// 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 myEvent = new Kochava.Tracker.Event(Kochava.Tracker.EventType.Subscribe); myEvent.Price = 9.99; myEvent.Currency = "usd"; myEvent.Name = "Monthly Subscription"; myEvent.UserId = "ABCDEF123456789"; myEvent.SetReceiptFromGooglePlayStore(receiptData, receiptSignature); // Android Only myEvent.SetReceiptFromAppleAppStore(appStoreReceiptBase64EncodedString); // iOS Only Kochava.Tracker.Client.SendEvent(myEvent); |
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):
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
// 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 myEvent = new Kochava.Tracker.Event(Kochava.Tracker.EventType.StartTrial); myEvent.Price = 0.0; myEvent.Currency = "usd"; myEvent.Name = "Monthly Subscription"; myEvent.UserId = "ABCDEF123456789"; myEvent.SetReceiptFromGooglePlayStore(receiptData, receiptSignature); // Android Only myEvent.SetReceiptFromAppleAppStore(appStoreReceiptBase64EncodedString); // iOS Only Kochava.Tracker.Client.SendEvent(myEvent); |
Deeplinking:
Track deeplink related actions and user activity.
Example (Standard Deeplink Event):
|
1 2 3 4 |
var myEvent = new Kochava.Tracker.Event(Kochava.Tracker.EventType.Deeplink); myEvent.Uri = "some_deeplink_uri"; myEvent.Source = "some_source_app"; Kochava.Tracker.Client.SendEvent(myEvent); |
Example (Custom Deeplink Event with Serialized JSON Data):
|
1 |
Kochava.Tracker.Client.SendEventString("_Deeplink", "{\"uri\":\"some_deeplink_uri\"}"); |
Enhanced Deeplinking:
Universal click deeplinking and re-engagement attribution.
Example (Acquire the Deeplink) —
-
123456789101112131415161718// Deeplink routing should be performed in a dedicated routing activity that launches the destination activity.protected override void OnStart(){base.OnStart();// acquire a deeplink whenever one is available and pass it to the SDK with a desired timeout.string deeplink = Intent?.DataString;if(!string.IsNullOrEmpty(deeplink)){// a standard deeplink exists, so we'll pass it to the SDK to be processedKochava.Tracker.Client.ProcessDeeplink(deeplink, 10, DeeplinkProcessed);}else{// no deeplink exists, so we'll pass an empty string to retrieve any deferred deeplink with a longer timeoutKochava.Tracker.Client.ProcessDeeplink("", 15, DeeplinkProcessed);}}
-
123456789101112131415// Deeplink routing is done in the AppDelegate class by overriding the appropriate functions.public override bool ContinueUserActivity(UIApplication application, NSUserActivity userActivity, UIApplicationRestorationHandler completionHandler){var url = userActivity.WebPageUrl;Kochava.Tracker.Client.ProcessDeeplink(url.AbsoluteString, DeeplinkProcessed);return base.ContinueUserActivity(application, userActivity, completionHandler);}public override bool OpenUrl(UIApplication application, NSUrl url, string sourceApplication, NSObject annotation){Kochava.Tracker.Client.ProcessDeeplink(url.AbsoluteString, DeeplinkProcessed);return OpenUrl(application, url, sourceApplication, annotation);}
Example (Wait for the Callback) —
|
1 2 3 4 5 6 7 8 9 10 |
public void DeeplinkProcessed(Kochava.Tracker.Deeplink 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 } } |
Identity Linking:
Link existing user identities with kochava devices.
Example (Set an Identity Link During Tracker Configuration):
|
1 2 3 4 5 6 7 8 9 10 |
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 (Set an Identity Link After Starting the Tracker):
|
1 2 3 4 |
IDictionary<string, string> identityLink = new Dictionary<string, string>(); identityLink.Add("User ID", "123456789"); identityLink.Add("Login", "username"); Kochava.Tracker.Client.SetIdentityLink(identityLink); |
Retrieving Attribution:
Access the attribution results within the app.
Example (Requesting Attribution Results):
|
1 2 3 4 5 6 7 8 9 10 |
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):
|
1 2 |
string attribution = Kochava.Tracker.Client.GetAttribution(); // Parse json serialized attribution info. |
The attribution results are provided as a stringified JSON object and can be parsed using a JSONObject or other JSON parsing functionality. If the attribution results have not yet been retrieved, calling the attribution data getter will return an empty string.
Getting The Kochava Device ID:
Obtain the unique device identifier assigned by Kochava.
Example (Getting the Kochava Device ID):
|
1 |
string kochavaDeviceId = Kochava.Tracker.Client.GetDeviceId(); |
Enabling App Limit Ad Tracking:
Limit the ad tracking at the application level.
Example (Enabling App Limit Ad Tracking During Tracker Configuration):
|
1 2 3 4 5 |
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):
|
1 |
Kochava.Tracker.Client.SetAppLimitAdTracking(true); |
Enabling Logging:
Enable logging output from the SDK.
To enable logging, set the desired log level during tracker configuration. When the tracker runs, each log message will be printed to your console log. In this example we’re setting a higher log level only when a debug build is detected, which is suggested but is not required.
Example (Enabling trace logging in a non-production build):
|
1 2 3 4 5 6 7 8 9 10 11 |
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); |
Sleeping the Tracker:
Delay the start of the tracker.
Example (Enabling Sleep Mode During Tracker Configuration):
|
1 2 3 4 5 |
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):
|
1 |
Kochava.Tracker.Client.SetSleep(true); |
Example (Waking the Tracker from Sleep Mode) —
|
1 |
Kochava.Tracker.Client.SetSleep(false); |
Consent — GDPR:
Handle GDPR and consent requirements.
Intelligent Consent Manager:
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 Manager feature. 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 more information on this feature, see: Intelligent Consent Manager.
Self Managed Consent:
Example (Starting the Tracker Only When Consent Allows) —
|
1 2 3 4 5 6 7 8 |
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) —
|
1 2 3 4 5 |
if(!consentRequired || consentGranted) { // we will not call Kochava methods unless consent requirements are met. Kochava.Tracker.Client.SendEventString("My Event", ""); } |
Consent — CCPA:
Handle CCPA and consent requirements.
Intelligent Consent Manager:
Free App Analytics’ fully managed consent solution.
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 Manager feature. 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.
Setting Up a Test Environment:
Create a test environment to ensure the integration is working properly.
- Use an alternate testing App GUID so that your testing activities do not have an impact on your live app analytics.
- Enable Logging, if helpful, to gain insight into the SDK’s behavior during runtime.
- 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.
- Test your Free App Analytics integration. For more information see: Testing the Integration.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
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:
