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.

 

ATT Note: 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.

 


 

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

 

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:

  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.

 

ATT Note: 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.

 

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

 

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):

 

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

 

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:

 

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:

 

Standard Events:

 

Example (Standard Event with Standard Parameters)

 

Example (Standard Event with Standard and Custom Parameters)

 

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)

 

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

 

Example (Send a Custom Event with Event Data)

 

Example (Send a Custom Event with Serialized JSON Data)

 

 


 

Example (Standard Purchase Event):

 

Example (Custom Purchase Event with Serialized JSON Data):

 

Example (Custom Subscription Purchase Event with Serialized JSON Data)


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):

 

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):

 


 

Example (Standard Deeplink Event):

 

Example (Custom Deeplink Event with Serialized JSON Data):


 

SDK VERSION NOTE: Enhanced Deeplinking is available as of Android native SDK version 3.7.0 and iOS native SDK version 3.12.

 

 

Example (Acquire the Deeplink)

 

 

Example (Wait for the Callback)

 

 

Example (Set an Identity Link During Tracker Configuration):

 

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


 

Example (Requesting Attribution Results):

 

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

 

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.

 


 

Example (Getting the Kochava Device ID):

 


 

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

 

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


 

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):

 


 

Example (Enabling Sleep Mode During Tracker Configuration):

 

Example (Enabling Sleep Mode After Starting the Tracker):

 

 

Example (Waking the Tracker from Sleep Mode)

 


 

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)

 

Example (Calling Tracker Methods Only When Consent Allows)


Estimated Time to Complete
1 Day

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.


  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 Free App Analytics integration. For more information see: Testing the Integration.

 

Analyzing SDK Behavior:


 
 

Last Modified: Oct 28, 2021 at 2:37 pm