Unity – Using the SDK

Estimated Time to Complete

5 Minutes

After integrating the SDK or creating a new App GUID, we suggest performing these tests to ensure the SDK has been integrated successfully and is functioning as expected within your app.

Validate the Install:

The SDK will send an install for the app once, after a fresh install. This test ensures the SDK was configured properly and successfully sent the install to Kochava.

1. Double check the SDK configuration in code, ensuring the correct App GUID.
2. Run the app for approximately 30 seconds, which will allow more than enough time for the SDK to start and send an install to Kochava under typical conditions.
3. Wait a minute or two and visit the Install Feed Validation page for your app within the Kochava dashboard, under Apps & Assets > Install Feed Validation. Within that page, look for the Integration Success! message which indicates integration was successful and that Kochava did receive an install from the SDK. At this point you have confirmed a successful SDK integration and can move ahead to Validate Post Install Events below.
4. If instead you see a Integration Not Complete! message, wait a few more minutes and refresh the page. After refreshing, if the Integration Not Complete! message persists, double check the following, then repeat this test:
• Correct App GUID is used within SDK code configuration.
• Ensure the SDK configuration and startup code is being reached.
• Ensure the network connection from the test device is not limited behind a firewall or otherwise.

Validate Event Tracking:

If you are tracking user events, you can use this test to ensure the SDK was configured properly and is successfully sending these events to Kochava.

1. Double check the SDK configuration in code, ensuring the correct App GUID.
2. Double check your event tracking code and ensure it is reachable.
3. Launch the app and perform necessary actions within the app to trigger the event(s) you wish to test. After performing these actions, wait 60 seconds to allow more than enough time for the SDK to send these events.
4. Wait a minute or two and visit the Event Manager page for your app within the Kochava dashboard, under Apps & Assets > Event Manager. Within that page, ensure the tested event names are displayed here, in which case you have confirmed the SDK is successfully tracking these events.
5. If your event names are not displayed here after waiting a few minutes, double check the following, then repeat this test:
• Correct App GUID is used within SDK code configuration.
• Ensure the SDK configuration and startup code is being reached prior to any event code.
• Ensure the SDK event code is being reached.
• Ensure the network connection from the test device is not limited behind a firewall or otherwise.

Estimated Time to Complete

15 Minutes

Examples include in-app purchases, level completions, or other noteworthy user activity you wish to track. Events can be instrumented either by using the standard format provided by the SDK or using your own custom event name and data.

BEST PRACTICES: Use a standard event type whenever possible.

Standard events are built by first selecting a standard event type and then setting any applicable standard parameters you wish to include with the event. For example, you might choose a Purchase standard event type and set values for the Price and Name parameters. There are a variety of standard event types to choose from and dozens of standard parameters available. When creating a standard event, you only need to set values for the parameters you wish to track. A maximum of 16 parameters can be set.

1. Create an event object using the desired standard event type.
2. Set the desired parameter value(s) within the event object.
3. Pass the event object to the tracker’s Send Event method.

Custom event parameters (which can also be serialized JSON) may also be set within a standard event.

For scenarios where the standard event types and standard parameters do not meet your needs, custom events can be used. To instrument a custom event, pass the event’s name and data (which can also be serialized JSON) to the tracker’s Send Event method.

NOTE: No custom event name pre-registration is required. However, a maximum of 100 unique event names can be tracked within the Kochava dashboard (including any standard event types also used), so keep this in mind as you create new custom event names.

Estimated Time to Complete

10 Minutes

In-app purchases and subscription can be easily tracked and attributed by creating a purchase event. To accomplish this, simply create an event of type Purchase and include the total amount of revenue as the price value within the event data parameters.

BEST PRACTICES: Include the name parameter, so that you can easily identify the SKU from the analytics side. It is also highly recommended to set a currency.

Estimated Time to Complete

5 Minutes

Tracking deeplinks is accomplished similar to any other type of event. In order to track a deeplink event, create a standard event of type Deeplink and set the uri parameter along with any other relevant parameters to the values provided when the deeplink occurred.

Enhanced Deeplinking facilitates the routing of users who are deeplinked into the app, whether through a standard deeplink or deferred deeplink. Re-engagement attribution is also supported for those users.

Use of this feature consists of these steps:

1. Acquire a deeplink and Pass it to the SDK.
2. Wait for the callback and Route the user.

Terminology:

Standard Deeplink: A deeplink into an app which is already installed. The app opens (or is already open) and the deeplink is immediately available.

Deferred Deeplink: A deeplink into an app which is not yet installed. In this case, a deeplink-enabled Kochava tracker is clicked, but the user must first install and then launch the app. The deeplink would have been lost during the installation, but Kochava is able to provide you with the original deeplink.

Acquire the Deeplink and Pass it to the SDK:

As a first step, acquire any incoming deeplink on launch or at runtime. If no deeplink exists on launch, pass in an empty string to indicate a deferred deeplink may be present. Remember, you do not need to check whether the deeplink is from Kochava or not; the SDK will do this for you.

A timeout, in seconds, may also be specified with the deeplink, which indicates the maximum amount of time to allow the SDK to attempt to process the deeplink. Typical standard deeplink processing should complete in less than 1 second, but if network connectivity is poor the timeout could be reached. Deferred deeplinking typically completes in 3-7 seconds, but could take longer depending on network connection and attribution processing time. We suggest setting a timeout of at least 10 seconds for standard deeplinks and 15 seconds for deferred deeplinks.

NOTE: Ensure you have started the Kochava Tracker SDK before using this feature.

About Deferred Deeplinking:

By passing an empty string (“”) to the Tracker’s ProcessDeeplink() method, as described in the first example above, the SDK will automatically look for any deferred deeplink from the attribution results and surface it within the callback no differently than a standard deeplink.

This means you do not need to care about where a deeplink is coming from or whether it is deferred or standard. Just pass in the deeplink if it exists or pass in an empty string if it does not, then wait for the callback and route the user.

Enhanced Deeplinking vs. Attribution Retrieval:

If you choose to use this Enhanced Deeplinking functionality for deferred deeplinking, you should not also need to use the SDK’s attribution retrieval feature for deferred deeplinking, unless you want to parse the attribution results for another reason. If you do not want Enhanced Deeplinking checking for a deferred deeplink, do not pass an empty string to the SDK when no deeplink exists. Choose one method or the other, but don’t rely on both for deferred deeplinking as you could end up routing the user twice.

One important difference between these two approaches is that Attribution Retrieval has no timeout and will eventually complete, no matter how much time it takes. If, for example, the network connection is bad and attribution results are not able to be retrieved, they would eventually be retrieved once the network connection was restored or even on a future launch. By contrast, Enhanced Deeplinking is designed with user experience in mind, and will only attempt to retrieve a deferred deeplink on the first launch of the first install, and only up to the timeout you specify. If the SDK is able to detect a reinstall, any deferred deeplink from the original install will be ignored. This is because a user would not expect to be routed to a deeplink destination long after the relevant time window had expired or on a future app launch. Imagine clicking a deeplink on a Monday, and being routed on Friday; it would be a confusing experience.

In summary, if you want to parse the raw attribution results yourself, or you do not care about receiving a deferred deeplink after the relevant time window expires, you may use the Attribution Retrieval (within this page) functionality for deferred deeplinking. If you do not care to parse the raw attribution results and you want to receive a deferred deeplink only when relevant, use the Enhanced Deeplinking functionality described here.

Estimated Time to Complete

10 Minutes

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 ID which you want to connect to a user’s service identifier. Using this feature, you can send both your internal ID and their service identifier to connect them in the Kochava database.

In order to link identities, you will need to pass this identity link information in the form of unique key and value pairs to the tracker as early as possible. This can be done during tracker configuration if the identity link information is already known, or it can be done after starting the tracker using the Set Identity Link method.

BEST PRACTICES: Keep from sending Personal Identifiable Information (PII) such as email addresses or deprecated platform identifiers such as IMEI to Kochava..

Estimated Time to Complete

15 Minutes

Install attribution results can be retrieved from Kochava servers if you wish to use these results within your app. Be aware that attribution results are always determined by Kochava servers; this feature simply provides the app with a copy of whatever the results were.

For example, you may wish to present a user with a different path if you have determined they installed the app from a certain advertising network or source.

Attribution results are fetched by the tracker as soon as requested and returned to the app asynchronously via a callback. This process usually takes about 3-4 seconds but can take longer depending on network latency and other factors. Once attribution results have been retrieved for the first time, they are not retrieved again and the results are persisted. From that point on they can be queried synchronously by calling the attribution data getter which always provides the persisted attribution results from the original retrieval.

NOTE: For purposes of deferred deeplinking, care should be taken to act upon the attribution results only once, as the original results will continue to be reported after the first retrieval, and are not refreshed on a per-launch basis.

BEST PRACTICES: Attribution retrieval does not affect attribution and should only be used if there is a clearly defined use within your app for knowing the attribution results; otherwise this causes needless network activity.

Once you have the attribution results, you will need to parse and handle them in some meaningful way. A variety of data exists within this json object and you will need to determine which data is meaningful for your purposes. For an overview of the attribution dictionary contents, see: Attribution Response Examples.

NOTE: If you wish to send attribution results to your own server, this should be done directly through Kochava’s postback system, rather than retrieving attribution in the app and then sending the results to your own server.

Estimated Time to Complete

1 Minute

If at any time after starting the tracker you would like to get the unique identifier assigned to this device by Kochava, this string (represented as a GUID) can be obtained by calling the device id getter.

Estimated Time to Complete

1 Minute

If you wish to limit ad tracking at the application level, with respect to Kochava conversions, you can set this value during or after configuration. By default the limit ad tracking state is not enabled (false).

For example, you might provide an option for a user to indicate whether or not they wish to allow this app to use their advertising identifier for tracking purposes. If they do not wish to be tracked, this value would be set to true.

Estimated Time to Complete

5 Minutes

Logging provides a text-based log of the SDK’s behavior at runtime, for purposes of debugging.

For example, while testing you may wish to see the contents of certain payloads being sent to Kochava servers, in which case you would enable logging at a debug (or higher) level.

Six different log levels are available, each of which include all log levels beneath them. Info log level is set by default, although trace log level should be used when debugging so that all possible log messages are generated.

BEST PRACTICES: Logging should be set to info log level or lower for production builds. This will limit the log messages generated by the tracker to errors, warnings, and basic tracker initialization messages which contain no sensitive information.

Estimated Time to Complete

10 Minutes

Placing the tracker into sleep mode, the tracker will enter a state where all non-essential network transactions will be held and persisted until the tracker is woken up. This can be useful if you wish to start the tracker early and begin tracking events but need the tracker to wait before sending events or the install data to Kochava servers.

For example, if you wanted the tracker startup process to have little or no impact on your own loading process, you might start the tracker in sleep mode during the app launch but wait while your app’s resource-intensive loading process completes. When the app’s loading process completes, the tracker can be woken and will continue with its own startup process without losing any events that may have been queued beforehand.

Once you are ready to wake the tracker simply set the sleep state to false. At that point the tracker will wake up and continue as normal, sending any queued events or install data.

NOTE: For every call to set sleep to true, there should be a matching call at some point setting sleep to false. While these calls do not necessarily have to be balanced, care should be taken to not inadvertently leave the tracker asleep permanently. This allows the tracker to wake up and continue with necessary logic and processing of data. Any events or other activity queued while sleeping will be held but not sent until sleep mode is set to false. This means that if the tracker is never woken from sleep mode, events and other activity will continue to build up in the queue, causing undesirable results and resource usage.

The SDK can be shut down after starting, which will completely disable the SDK and stop all tracking from continuing.

The SDK should not be shutdown in typical scenarios, but this may be useful during consent-applicable instances when consent has been declined or revoked after starting the SDK and you wish to completely stop tracking the user.

After shutting down, all network communication with Kochava will cease, events will no longer queue, and any API calls will fail just as if the SDK had never been started. The SDK must be configured and started again if you wish for tracking to resume.

Example (Shut Down the SDK) —

Shutdown vs. Sleep:

The SDK’s sleep functionality can also be used to temporarily prevent the SDK from sending data to Kochava. However, sleep will continue to queue events and track the user, but will simply not send that data to Kochava until awoken. For this reason, sleep should not be used as a solution for consent-applicable situations because tracking is still queuing locally and may be sent on the next app launch.

Shutting down the SDK, on the other hand, completely stops the SDK from functioning and no tracking will occur until it is configured and started again.

The Kochava SDK does deal with GDPR-sensitive data, such as device identifiers. Care should be taken to ensure that your use of the Kochava SDK remains GDPR compliant when applicable.

GDPR applies to users within the EU and requires users to opt-in to data collection. For common questions and answers regarding both GDPR and CCPA consent models, refer to our Handling Consent support documentation.

CCPA applies to users within California and allows users to opt out of the sale of their data.

For purposes of CCPA, the Kochava Tracker SDK follows IAB’s CCPA Compliance Framework by reading the U.S. Privacy String from local storage, when present. The app or any entity within the app can set this string any time.

This means that if IAB’s U.S. Privacy String has been set within the app, the Kochava Tracker SDK will automatically adorn installs and post-install events with it’s value, when present. By doing so, CCPA consent status via the U.S. Privacy String can be associated with all user tracking and syndicated downstream for interested 3rd parties.

You do not need to take any action in the Kochava Tracker SDK for this functionality. However, it is your responsibility to ensure the U.S. Privacy String has been set within local storage when appropriate. The SDK will look for the U.S. Privacy String in local app storage under the key ‘IABUSPrivacy_String’ within default shared preferences on Android and default NSUserDefaults on iOS. As long as the value is present, the SDK will pick it up.

For more information regarding SDK-based solutions for CCPA, refer to our Handling Consent support documentation.