Support Home > SDK Integration > SDK – Intelligent Consent Manager

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 Free App Analytics 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 Free App Analytics dashboard, this information is communicated back to the Kochava SDK and surfaced to your app. This allows your app to simply query the Free App Analytics 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 Free App Analytics 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 Free App Analytics 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)
  3. …App continues to run.

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

  7. Kochava SDK notifies the app of consent status change.
  8. Check consent. (see example code below)
  9. …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 Free App Analytics 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 Free App Analytics 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 Free App Analytics 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 Free App Analytics 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.

 

Example Game

 

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 Free App Analytics dashboard.
  • If consent is required and a new consent prompt id has been entered in the Free App Analytics 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 Free App Analytics 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 Free App Analytics 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



  • How can I find out from the Kochava SDK if the user is in the EU and/or if GDPR applies?

    The Kochava SDK talks to Kochava servers to determine if consent is required for this user. Multiple factors are used to determine this including locale, timezone, IP address, etc.. Kochava surfaces this to the app under the consent required boolean, which takes the guesswork out of this process and simply indicates whether consent is required or not for this user.

  • How does the app know it can proceed or not with GDPR-sensitive logic?

    When the consent callback is triggered or at any time, the app can check the values of both consent-required and consent-granted before proceeding with GDPR-protected logic. Both of these values must be checked as restrictions are lifted if either consent has been granted OR consent is not required. This type of logic can be wrapped in a statement like so:

     

    Pseudocode:

    if(Kochava.Consent.Granted == true || Kochava.Consent.Required == false) {
    // we know consent is either not required or has been granted at this point
    ShowTargetedAds();
    }

  • When does the prompt retry interval apply?

    This value defines the amount of time that must elapse before re-prompting the user for consent after the last prompt was displayed, and only if consent is unknown or declined. If consent has been granted the retry interval does not apply.

  • Does the Kochava SDK display a the consent prompt dialogue?

    No. The SDK notifies the app that a consent prompt should be displayed. It is then up to the app to display said prompt and notify the Kochava SDK whether the user grants or declines consent. Based on the response (or lack of response), the Kochava SDK will notify the app when to show the prompt again. It's important to note that the Kochava SDK handles everything other than displaying the prompt, which includes tracking partner changes, determining whether this user is in a GDPR region, etc..

  • How does the Kochava SDK behave when consent is required but the user has not yet granted or declined consent?

    This is considered a consent-unknown state and occurs when consent is required but the user has not yet answered a consent prompt. In this state the Kochava SDK will queue the install and events temporarily in local memory but will not populate any data points and will not write any analytics data to disk. While in this state, the Kochava SDK will eventually notify the app to re-prompt at the retry interval set in the Kochava dashboard. If consent is eventually granted, any queued install & events from this session will be populated and sent. If the app terminates during this session without consent being granted any queued events will be lost and will not be persisted to disk.

  • How does the Kochava SDK behave when consent is explicitly declined?

    This is considered a consent-declined state and occurs only when consent is required and the user has explicitly declined consent (answered "no" to a consent prompt). In this state the Kochava SDK will immediately drop installs & events, will not collect data points and will not write any analytics data to disk -- the Kochava SDK is essentially off. The Kochava SDK will sit idle and notify the app to re-prompt at the retry interval set in the Kochava dashboard. If consent is eventually granted in the future, a new install will be sent (and deduped if previously sent) and events from that moment on will be sent. Events which were attempted while consent was declined were dropped and will not be re-sent.

  • What happens when the user travels from a GDPR region like Germany to a non-GDPR region like the US?

    In this case consent is required while in Germany and as such the app is notified to prompt for consent and Kochava SDK data is restricted until consent has been granted. When the user leaves Germany and travels to the US, the Kochava SDK will notify the app that consent is no longer required and regardless of previous consent status the Kochava SDK will no longer restrict data.

  • What happens when the user travels from a non-GDPR region like the US to a GDPR region like Germany?

    In this case consent is not required in the US and as such the app is never instructed to prompt for consent. Once the user travels to Germany consent becomes required and the app the instructed to prompt for consent (and data is restricted until consent is granted).

  • How long does it take for ICM changes made in the Kochava dashboard to propagate?

    After making a change within the dashboard, such as changing your consent region or partner list, the changes will typically surface to the app within 15 minutes.

  • How can I test ICM outside of the EU?

    While testing, we suggest you set your ICM region to global, so that consent is always required just as it would be in the EU, although keep in mind that changing the region may take up to 15 minutes to surface within the app. Alternately, you can use a VPN to force an EU-based IP address while testing.

 
 
Last Modified: Oct 18, 2023 at 8:02 am