SDK – Intelligent Consent Manager

SDK

Intelligent Consent Manager

Kochava’s Intelligent Consent Manager (ICM) feature can be leveraged to fully manage your consent requirements for GDPR and other consent-related applications. By using this feature the Kochava SDK will determine if and when a user should be prompted for consent, and in the case of GDPR, will dynamically handle tracking and management of your partner list.

---

How it Works

When this feature is enabled the Kochava SDK communicates with Kochava servers to determine whether GDPR policy applies to a user using a variety of factors such as locale, timezone and IP address. Along with your current partner list, which is managed through the Kochava dashboard, this information is communicated back to the Kochava SDK and surfaced to your app. This allows your app to simply query the Kochava SDK for consent status and listen for notifications as to when consent should be gathered (and re-gathered) from a user, which ultimately takes the guesswork out of GDPR.

NOTE: Consent will be syndicated to network and publisher partners who have had their integrations updated to receive the consent status parameter. Check with your Client Success Management team if you have questions about your partners.

---

Setup

In order to utilize Intelligent Consent Manager, the feature is first setup through the Kochava dashboard and then enabled at the code level during Kochava SDK configuration.

 

BEST PRACTICES: The proper use of Intelligent Consent Manager requires that the Kochava SDK act as the authority regarding when consent is required, and when to prompt for consent. If you intend to determine consent requirements independently, the ICM feature and any related API calls should not be used and doing so may result in the loss of installs or other telemetry.

 

1. Within the Kochava dashboard enable Intelligent Consent Manager, construct your partner list and adjust other related settings. For more information, refer to our Create/Edit Apps support documentation.
2. Within your app code, enable the Intelligent Consent Manager boolean when configuring the Kochava SDK. See the API section below for specifics on enabling this feature.
3. At this point the Kochava SDK will surface to your app at runtime whether or not consent is required, whether the user has granted or declined consent, as well as when the user should be prompted for consent.

---

Handling Consent

Once you have setup and enabled Intelligent Consent Manager, your app simply needs to check the most recent consent status when performing GDPR-sensitive logic, or when notified by the Kochava SDK that an actionable change has occurred.

In a typical integration, your app should run through the same consent checking logic any time consent-related actions should occur, such as during initialization or when the Kochava SDK signals a change to consent status. For example, a typical integration would look like this:

1. App launches.
2. Check consent. (see example code below)

…App continues to run.

3. App reaches a state, such as the Main Menu, when a new consent prompt could be displayed if needed.
4. Check consent. (see example code below)

…App continues to run.

5. Kochava SDK notifies the app of consent status change.
6. Check consent. (see example code below)

…App continues to run.

 

Pseudocode:

// this logic should be called when the app launches, is able to take consent-related action based on the state of the app, or is notified by the Kochava SDK that consent status has changed
void CheckConsent() {

	if(Kochava.Consent.Required == false || Kochava.Consent.Granted == true) {
    	    // consent is either not required or has been granted
    	    // (we can proceed with GDPR-sensitive logic)

    	    // have we initialized our consent-restricted libraries and other logic yet?
    	    // (use a flag to ensure this only happens when necessary)
    	    if(MyApp.ConsentInitialized == false) {
        	    // set the flag
        	    MyApp.ConsentInitialized = true;
        	    // we are now ok to initialize any GDPR-sensitive SDKs, ad networks, etc.    	
        	    AdProvider.ShowTargetedAds();
        	    CrashSDK.Start();
        	    MyApp.CanCollectUserData = true;     	
    	    }

	} else {
    	    // consent is required and has not been granted
    	    // (we need to ensure that any GDPR-sensitive logic is disabled)

    	    // should a new consent prompt be displayed to the user?
    	    if(Kochava.Consent.ShouldPrompt == true) {
        	    // notify the Kochava SDK that we're going to display a consent prompt
        	    // (this also consumes the Kochava.Consent.ShouldPrompt flag)
        	    Kochava.Consent.Prompted();
        	    // display my consent prompt
        	    MyApp.ShowConsentPrompt();
    	    }

    	    // if we previously initialized consent-restricted libraries or other logic it should be disabled now
    	    // (use a flag to ensure this only happens when necessary)
    	    if(MyApp.ConsentInitialized == true) {
        	    // consume the flag
        	    MyApp.ConsentInitialized = false;
        	    // we should disable and delete private data from any GDPR-sensitive SDKs, ad networks, etc.    	
        	    AdProvider.ShowNonTargetedAds();
        	    CrashSDK.Stop();
        	    MyApp.CanCollectUserData = false;            	
    	    }
	}
}

 

In addition to the logic above, if and when the user responds to your consent prompt dialogue or if the user otherwise opts out of consent the Kochava SDK must be notified of the result. If the user dismisses or ignores the dialogue and does not provide a response, no action needs to be taken as the Kochava SDK is still aware that consent has not been granted and will notify the app when to re-prompt, based on the prompt retry time set in the Kochava dashboard.

 

Pseudocode:

if(UserGrantedConsent == true)
 	// notify the Kochava SDK the user explicitly granted consent
 	Kochava.Consent.Granted(true);
} else {
 	// notify the Kochava SDK the user explicitly declined consent
 	Kochava.Consent.Granted(false);
}

 

Most importantly, any time GDPR-sensitive logic occurs it should be wrapped in a conditional check.

 

Pseudocode:

if(Kochava.Consent.Required == false || Kochava.Consent.Granted == true) {
 	// we can proceed with this GDPR-sensitive logic 
 	CollectPrivateUserData();
}

 

For more platform specific code documentation see the Public API section below.

---

Prompting for Consent

Once Kochava has determined consent is required for a user, the Kochava SDK will notify your app through a callback that consent status has changed and that the app should prompt for consent (see the Should Prompt API item). You can also check this manually any time if you are only able to show a consent prompt at certain times. At this point you are ready to create and present the user with a consent dialogue and partner list. As the presentation of any dialogue must factor in your branding, your messaging, and your desired user experience, we leave the presentation of a consent dialogue up to you (although the Kochava SDK dynamically provides the partner list that you have setup through the Kochava dashboard, should you wish to use it). Below are the steps your app should take when prompting for consent:

1. The Kochava SDK signals to the app that consent status has changed. As a result of this signal, or anytime the app checks consent status and recognizes that the user should be prompted for consent.
2. The app presents a consent dialogue prompt to the user and tells the Kochava SDK that a prompt was displayed. By doing so, the Kochava SDK will clear the flag indicating the user should be prompted and will not ask the app to prompt again until an acceptable amount of time has elapsed, even if the user does not respond.
3. When and if the user responds to the consent dialogue, the app tells the Kochava SDK whether consent was granted or declined.
4. If the user does not respond, consent will remain un-granted and the Kochava SDK will notify the app when to re-prompt (based on the retry time value set in your Kochava dashboard). This functionality means that the app does not need to worry about when the user was last prompted or prompting the user too often, as the Kochava SDK will handle this silently and simply notify the app when a new prompt is warranted.
5. After prompting, regardless of the response, the app can continue to run as normal, making sure to check the Kochava SDK consent status when executing GDPR-sensitive logic.

 

Creating a Prompt Dialogue:

A consent collection dialogue can be constructed a number of ways, using different techniques and the most appropriate wording for your application. Below is a very basic example of how a consent dialogue might look. In this example we are stating why we share data, who we share the data with and a button to provide more information for each partner. We also provide clear and concise options for the user to decline or grant consent and even allow the user to ignore the prompt all together should they not wish to answer either way.

 

 

NOTE: This example is for illustrative purposes only and is not intended to be construed as legal advice.

---

Consent Factors

The status of consent is based on many factors, all of which the Kochava SDK handles for you. For reference purposes, listed below are various conditions which will affect the status of consent:

 

Consent Required:

• The user has entered or see their locale a GDPR-applicable region within the EU, such as Germany.

 

New Consent Prompt Required:

• Consent is required and the user has not yet been prompted.
• If consent is required and a new partner has been added to the partner list in the Kochava dashboard.
• If consent is required and a new consent prompt id has been entered in the Kochava dashboard, a one-time re-prompt for any user who has currently granted consent will be triggered.

 

New Consent Prompt Not Required:

• A partner was removed from the partner list in the Kochava dashboard. This change does not warrant new consent if the user has currently granted consent as their consent is still applicable to the current partners.

 

Consent Not Required Scenarios:

• The user has both entered and set their locale to a region outside of the EU, such as the United States.

---

Public API

All Kochava SDKs which offer the Intelligent Consent Manager (ICM) feature include a common API, as well as additional API not listed here which may vary by platform. Below are the commonly used methods and properties available to all SDKs and which should be used for typical integrations:

 

Set this boolean during SDK configuration to enable ICM.

Subscribe to this callback for real-time notifications to consent status changes. Alternatively, your app can poll the Kochava SDK for the current status or only check when desired.

Boolean indicating whether consent is required for this user. This is true when the user is determined to be in the EU.

Boolean indicating whether consent is granted by the user. This should be checked in tandem with the Required boolean to determine if your app can proceed with GDPR-sensitive logic.

Call this method or set this property after displaying a consent dialogue to tell the Kochava SDK whether the user has granted consent (true) or declined consent (false).

When this boolean is true, the Kochava SDK has determined that this user must be prompted for consent.

Call this method or set this property immediately before your app displays the consent dialogue prompt, regardless of the response. This will also clear the Should Prompt flag.

Returns the current list of partners, as set within your Kochava dashboard. This list can also be used to dynamically populate your consent dialogue.

 

BEST PRACTICES: This document is a high level overview, please refer to the appropriate SDK documentation for specific Intelligent Consent Manager API documentation details.

 

Android: Intelligent Consent Manager
iOS/tvOS: Intelligent Consent Manager
Unity: Intelligent Consent Manager
Adobe Air: Intelligent Consent Manager

---

Kochava Tracker Consent Awareness

As the arbiter of consent, the Kochava SDK is at all times fully aware of the current consent status and as such, your app does not need to wrap any Kochava logic in GDPR or other consent checks when this feature is enabled. Specifically, if your app attempts to send an event (which may include private user data) while consent is required but not granted, the Kochava SDK will simply drop the event or queue the event to be sent if and when consent is granted or no longer required; no private user data or telemetry will be sent or collected until acceptable consent conditions have been met.

---

The Kochava Device ID and Consent

When ICM is enabled within the SDK, the Kochava Device ID value should be considered temporary and may change each session until consent is either granted or is not required. This means that querying the Kochava Device ID from the SDK while consent is required and has not been granted will return a value that may or may not change based on the future status of consent. In summary, when ICM is enabled, the Kochava Device ID should not be used or relied upon until consent is either not required or has been granted.

---

FAQs