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.
Free App Analytics’ Intelligent Consent Management (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 shoulder the burden of determining 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 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 Kochava SDK for consent status and listen for updates as to when consent should be gathered (and re-gathered) from a user, which ultimately takes the guesswork out of GDPR.
Design Considerations
ICM is a robust and dynamic consent system which can be implemented in different ways. As such, it is important to understand how ICM works and what type of implementation will work best for your application.
When using ICM, your code does not need to approach consent from the standpoint of whether the user is in the EU or not. Rather, your code should simply query the Kochava SDK as to whether consent is currently required or not, and if so, whether the user has granted consent or should be newly prompted for consent. The Kochava SDK will keep track of what consent-related actions have taken place and what needs to happen across multiple launches of the app.
Typically, when consent related action is required by your app this can handled this one of two ways:
Query the Kochava SDK:
Take this approach when your app is only able to load other consent-required SDKs or show a consent dialogue prompt at very specific moments, such as during a loading process or when the user has arrived at the Main Menu. This approach does not require providing a consent status update listener during tracking configuration.
Await Notifications from the Kochava SDK:
The Kochava SDK can notify your app of actionable consent-related changes when necessary; however, this could happen at any time. Take this approach if your app is more easily able to dynamically enable or disable other SDKs or show a consent dialogue prompt at any time. This approach requires that you provide a consent status update listener during tracker configuration.
Keep these two approaches in mind going forward (and which one works best for you), as this documentation will distinguish between the two at times.
Enabling ICM
var configMapObject:Object = new Object();
configMapObject[KochavaTracker.PARAM_ANDROID_APP_GUID_STRING_KEY] = "_YOUR_ANDROID_APP_GUID";
configMapObject[KochavaTracker.PARAM_IOS_APP_GUID_STRING_KEY] = "_YOUR_IOS_APP_GUID";
// enable the ICM feature.
configMapObject[KochavaTracker.PARAM_INTELLIGENT_CONSENT_MANAGEMENT_BOOL_KEY] = true;
KochavaTracker.configure(configMapObject);
// if planning to wait for notifications from the Kochava SDK,
// we will optionally provide a listener for consent status changes:
KochavaTracker.setConsentStatusChangeListener(function(event: KochavaTrackerStatusEvent):void {
checkConsentStatus();
});
Developer API Reference:
KochavaTracker.configure(Object)
Configuration Parameters
KochavaTracker.setConsentStatusChangeListener(FunctionKochavaTrackerStatusEvent)
Checking Consent Status
Once you have setup and enabled ICM, your app simply needs to check the most recent consent status when performing consent-required 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 certain moments within the app’s lifecycle or when the Kochava SDK notifies your app of a change to consent status.
Handling the current consent status can be done a variety of ways and should be based on the needs of your app, but a typical check might look like this:
Example (Checking the Consent Status):
// this logic should occur anytime the app is able to take consent-related action, or is notified by the Kochava SDK that consent status has changed
checkConsentStatus() {
// Retrieve the consent json, parse the object, and retrieve the needed values from it.
var consentSerializedJson:String = KochavaTracker.getConsentStatus();
var consent:Object = JSON.parse(consentSerializedJson);
var required:Boolean = consent[KochavaTracker.CONSENT_STATUS_REQUIRED_BOOL_KEY];
var granted:Boolean = consent[KochavaTracker.CONSENT_STATUS_GRANTED_BOOL_KEY];
var shouldPrompt:Boolean = consent[KochavaTracker.CONSENT_STATUS_SHOULD_PROMPT_BOOL_KEY];
if(granted || !required) {
// 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, regardless of how often this check is made)
if(!MyApp.consentInitialized) {
// 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(shouldPrompt) {
// notify the Kochava SDK that we are going to display a consent prompt
KochavaTracker.setConsentPrompted()
// 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, regardless of how often this check is made)
if(MyApp.consentInitialized) {
// consume the flag
MyApp.consentInitialized = false;
// we should disable (and delete where possible) private data from any GDPR-sensitive SDKs, ad networks, etc.
AdProvider.showNonTargetedAds();
CrashSdk.stop();
MyApp.canCollectUserData = false;
MyApp.deleteUserTrackingData();
}
}
}
Developer API Reference:
String KochavaTracker.getConsentStatus()
Consent Status
KochavaTracker.setConsentPrompted()
Prompting for Consent
Once Free App Analytics has determined consent is required for a user, the Kochava SDK can notify the app and surface this through the should-prompt API call. You can check this manually any time or wait for the callback that consent status has changed before checking. 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:
- 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.
- 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.
- When and if the user responds to the consent dialogue, the app tells the Kochava SDK whether consent was granted or declined.
- 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.
- 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 consent-required logic.
Example (Prompting for Consent):
// Retrieve the consent json, parse the object, and retrieve the needed values from it.
var consentSerializedJson:String = KochavaTracker.getConsentStatus();
var consent:Object = JSON.parse(consentSerializedJson);
var shouldPrompt:Boolean = consent[KochavaTracker.CONSENT_STATUS_SHOULD_PROMPT_BOOL_KEY];
if(shouldPrompt) {
// notify the Kochava SDK that we are going to display a consent prompt
// (this also consumes the should prompt flag)
KochavaTracker.setConsentPrompted();
// display my consent prompt
MyApp.showConsentPrompt();
}
Developer API Reference:
String KochavaTracker.getConsentStatus()
Consent Status
KochavaTracker.setConsentPrompted()
Reporting Consent Results
When the user responds to your consent prompt dialogue or if the user otherwise grants or declines 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 be aware that consent has not been granted and will notify the app when to re-prompt at some point in the future, based on the prompt retry time set in the Free App Analytics dashboard.
Example (Reporting the Results of the Consent Prompt to the Kochava SDK):
if(userGrantedConsent) {
// notify the Kochava SDK the user explicitly granted consent
KochavaTracker.setConsentGranted(true);
} else if(!userGrantedConsent) {
// notify the Kochava SDK the user explicitly declined consent
KochavaTracker.setConsentGranted(false);
}
Developer API Reference:
KochavaTracker.setConsentGranted(boolean)
Wrapping Consent Required Code
Any time consent-required logic occurs apart from the Kochava SDK it should be wrapped in a conditional check that ensures consent status currently allows said logic to execute. While you can independently check the status of required and granted, the SDK provides a helper API call to check these conditions together.
Example (Wrapping Consent-Sensative Logic in a Consent Check):
// Retrieve the consent json, parse the object, and retrieve the needed values from it.
var consentSerializedJson:String = KochavaTracker.getConsentStatus();
var consent:Object = JSON.parse(consentSerializedJson);
var required:Boolean = consent[KochavaTracker.CONSENT_STATUS_REQUIRED_BOOL_KEY];
var granted:Boolean = consent[KochavaTracker.CONSENT_STATUS_GRANTED_BOOL_KEY];
if(granted || !required) {
// we can proceed with this GDPR-sensitive logic
collectPrivateUserData();
}
Developer API Reference:
String KochavaTracker.getConsentStatus()
Consent Status
Other Functionality
In addition to the core ICM functionality described above, the Kochava SDK offers other ICM functionality which may be useful for your application.
Checking Consent Requirements:
The tracker can provide whether consent is currently required or not, based on the location of the user and your app’s consent region settings in the Free App Analytics dashboard. This value is typically checked in tandem with whether the user has granted consent.
Example (Checking Consent Required Status) —
// Retrieve the consent json, parse the object, and retrieve the needed values from it.
var consentSerializedJson:String = KochavaTracker.getConsentStatus();
var consent:Object = JSON.parse(consentSerializedJson);
var required:Boolean = consent[KochavaTracker.CONSENT_STATUS_REQUIRED_BOOL_KEY];
if(required) {
// consent is required by this user, do something...
}
Checking Consent Granted Status:
The tracker can provide whether consent is currently granted or not, based on the user’s previous response. This value is typically checked in tandem with whether consent is currently required or not.
Example (Checking Consent Granted Status) —
// Retrieve the consent json, parse the object, and retrieve the needed values from it.
var consentSerializedJson:String = KochavaTracker.getConsentStatus();
var consent:Object = JSON.parse(consentSerializedJson);
var granted:Boolean = consent[KochavaTracker.CONSENT_STATUS_GRANTED_BOOL_KEY];
if(granted) {
// consent has been granted by this user, do something...
}
Getting the Partner List:
The tracker can provide a list of the current partners set within the Kochava dashboard, although typical usage does not warrant accessing this list.
Example (Getting the Partner List and Parsing It) —
// Retrieve the consent json, parse the object, and retrieve the needed values from it.
var consentSerializedJson:String = KochavaTracker.getConsentStatus();
var consent:Object = JSON.parse(consentSerializedJson);
var partners:Object = consent[KochavaTracker.CONSENT_STATUS_PARTNERS_KEY];
for(var i:int=0; i<partners.length; i++) {
var partnerDescription:String = partners[i][KochavaTracker.CONSENT_STATUS_DESCRIPTION_STRING_KEY];
var partnerGranted:Boolean = partners[i][KochavaTracker.CONSENT_STATUS_GRANTED_BOOL_KEY];
var partnerResponseTime:uint = partners[i][KochavaTracker.CONSENT_STATUS_RESPONSE_TIME_LONG_KEY];
var partnerName:String = partners[i][KochavaTracker.CONSENT_STATUS_PARTNER_NAME_STRING_KEY];
// Do something with the partner...
}
Checking if Consent is Ready:
In order for the Kochava SDK to determine consent requirements, a single network call is made to Free App Analytics servers. Before this call has completed at least once, the Kochava SDK will report default consent requirements (consent is always required by default). This may be useful if the app is querying the Kochava SDK for consent status and needs to know whether to wait longer for that initial connection to complete. Alternatively, if you are waiting for consent updated notifications from the Kochava SDK, you do not need to query this method as the notifications will not occur until this network call has completed.
Example (Checking if Consent Requirements are Known) —
// Retrieve the consent json, parse the object, and retrieve the needed values from it.
var consentSerializedJson:String = KochavaTracker.getConsentStatus();
var consent:Object = JSON.parse(consentSerializedJson);
var requirementsKnown:Boolean = consent[KochavaTracker.CONSENT_REQUIREMENTS_KNOWN_BOOL_KEY];
if(requirementsKnown) {
// consent has been granted by this user, do something...
}
Developer API Reference:
String KochavaTracker.getConsentStatus()
Consent Status
Kochava Tracker and Consent
As the arbiter of consent, the Free App Analytics Tracker is at all times fully aware of the current consent status and as such, your app does not need to wrap any Free App Analytics logic in consent-required 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 Free App Analytics Tracker 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.
Frequently Asked Questions
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();
}
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.
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..
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.
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.
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.
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).
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.
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.
