Ketch Mobile SDK for Android

The Ketch Mobile SDK allows to manage and collect a visitor's consent preferences for an organization on the mobile platforms.

Requirements

The minimum Android API version supported is 26.

The use of the Mobile SDK requires an Ketch organization account with the application property configured.

Adding KetchSDK in your project

1. Using sources

1. Copy and paste ketchsdk module to your project
2. Add "include ':ketchsdk'" to settings.graddle
3. Add dependency into your main module:

 implementation project(':ketchsdk')

2. Using .aar lib

1. Add it in your root build.gradle at the end of repositories:

repositories {
...
maven { url 'https://jitpack.io' }
}

2. Add the dependency:

 implementation 'com.github.ketch-com:ketch-android:main-SNAPSHOT'

If you want you can use our Sample

3. Add user-permissions to AndroidManifest.xml

 <uses-permissionandroid:name="android.permission.INTERNET" />
<uses-permissionandroid:name="com.google.android.gms.permission.AD_ID" />

4. Add constants to companion object of your activity

privateconstvalORG_CODE="<your organization code>"privateconstvalPROPERTY="<property>"privateconstvalENVIRONMENT="production"

5. Add listener and Ketch to your activity

Feel free to skip the listeners you don't really need.

importandroid.util.Logimportcom.ketch.android.Ketchimportcom.ketch.android.KetchSdkimportcom.ketch.android.Consent// ...privateval listener =object:Ketch.Listener {
overridefunonShow() {
Log.d("KetchApp", "Dialog shown") // Called when a consent or preferences dialog is displayed
}
overridefunonDismiss() {
Log.d("KetchApp", "Dialog dismissed") // Called when a dialog is dismissed
}
overridefunonEnvironmentUpdated(environment:String?) {
Log.d("KetchApp", "Environment updated: $environment") // Called when the environment is updated
}
overridefunonRegionInfoUpdated(regionInfo:String?) {
Log.d("KetchApp", "Region info updated: $regionInfo") // Called when region info is updated
}
overridefunonJurisdictionUpdated(jurisdiction:String?) {
Log.d("KetchApp", "Jurisdiction updated: $jurisdiction") // Called when jurisdiction is updated
}
overridefunonIdentitiesUpdated(identities:String?) {
Log.d("KetchApp", "Identities updated: $identities") // Called when identities are updated
}
overridefunonConsentUpdated(consent:Consent) {
Log.d("KetchApp", "Consent updated") // Called when consent preferences are updated// Here you can handle consent changes for your app features// Example: Enable/disable tracking based on consentval hasAnalyticsConsent = consent.purposes["analytics"] ==trueval hasAdvertisingConsent = consent.purposes["advertising"] ==trueif (hasAnalyticsConsent) {
// Enable analytics tracking
} else {
// Disable analytics tracking
}
if (hasAdvertisingConsent) {
// Enable advertising features
} else {
// Disable advertising features
}
}
overridefunonError(errMsg:String?) {
Log.e("KetchApp", "Error: $errMsg") // Called when an error occurs
}
overridefunonUSPrivacyUpdated(values:Map<String, Any?>) {
Log.d("KetchApp", "US Privacy updated") // Called when US Privacy values are updated// You can access the US Privacy stringval privacyString = values["IABUSPrivacy_String"] as?StringLog.d("KetchApp", "US Privacy String: $privacyString")
}
overridefunonTCFUpdated(values:Map<String, Any?>) {
Log.d("KetchApp", "TCF updated") // Called when TCF values are updatedval tcString = values["IABTCF_TCString"] as?String// You can access the TC stringLog.d("KetchApp", "TCF TC String: $tcString")
}
overridefunonGPPUpdated(values:Map<String, Any?>) {
Log.d("KetchApp", "GPP updated") // Called when GPP values are updatedval gppString = values["IABGPP_HDR_GppString"] as?String// You can access the GPP stringLog.d("KetchApp", "GPP String: $gppString")
}
}

6. Create the Ketch Object:

/** * Creates the Ketch * * @param context - an Activity Context to access application assets * @param fragmentManager - The FragmentManager this KetchDialogFragment will be added to. * @param organization - your organization code * @param property - the property name * @param environment - the environment name. * @param listener - Ketch.Listener * @param ketchUrl - Overrides the ketch url * @param logLevel - the log level, can be TRACE, DEBUG, INFO, WARN, ERROR*/privateval ketch:Ketch by lazy {
KetchSdk.create(
this,
supportFragmentManager,
ORG_CODE,
PROPERTY,
ENVIRONMENT,
listener,
ketchUrl,
Ketch.LogLevel.DEBUG
)
}

7. Add your user identities and call load() method

with(ketch) {
setIdentities(
mapOf(
"aaid" to advertisingIdCode,
"email" to "user@mywebsite.com",
"account_id" to "1234"
)
)
load()
}

Local Development Setup

If you're developing or modifying the SDK and want to test your changes with the sample app, you can use Gradle's composite builds feature to link them together.

Setting up the Sample App for Local Development

1. Clone both repositories:

   • Ketch Android SDK: git clone https://github.com/ketch-com/ketch-android.git
   • Ketch Samples: git clone https://github.com/ketch-sdk/ketch-samples.git

2. In the sample app's settings.gradle file, add the following:

// Include the Ketch SDK from the local repository
includeBuild('../../../../ketch-android') {
dependencySubstitution {
substitute module('com.github.ketch-com:ketch-android') using project(':ketchsdk')
}
}

We use relative path here under assumption that both repositories are in the same parent directory. If using a different structure, adjust the path accordingly.

Troubleshooting

Make sure you're rebuilding the project after making changes to the SDK. If the sample app isn't picking up the local SDK, try running ./gradlew clean in both projects.

Reverting to Remote Dependencies

To revert back to using the remote GitHub dependency:

1. Remove or comment out the includeBuild section in the sample app's settings.gradle file
2. Rebuild the sample app

Developer's Documentations

com.ketch.android.Ketch

class Ketch - Main class where the SDK functionality resides.

Methods:

/** * Loads a web page and shows a popup if necessary*/funload()
/** * Retrieve a String value from the preferences. * * @param key The name of the preference to retrieve. * * @return Returns the preference value if it exists*/fungetSavedString(key:String): String?/** * Retrieve IABTCF_TCString value from the preferences. * * @return Returns the preference value if it exists*/fungetTCFTCString(): String?/** * Retrieve IABUSPrivacy_String value from the preferences. * * @return Returns the preference value if it exists*/fungetUSPrivacyString(): String?/** * Retrieve IABGPP_HDR_GppString value from the preferences. * * @return Returns the preference value if it exists*/fungetGPPHDRGppString(): String?/** * Display the consent, adding the fragment dialog to the given FragmentManager.*/funshowConsent()
/** * Display the preferences, adding the fragment dialog to the given FragmentManager.*/funshowPreferences()
/** * Display the preferences tab, adding the fragment dialog to the given FragmentManager. * * @param tabs: list of preferences tab * @param tab: the current tab*/funshowPreferencesTab(tabs:List<PreferencesTab>, tab:PreferencesTab)
/** * Dismiss the dialog*/fundismissDialog()
/** * Set identities * * @param identities: Map<String, String>*/funsetIdentities(identities:Map<String, String>)
/** * Set the language * * @param language: a language name (EN, FR, etc.)*/funsetLanguage(language:String)
/** * Set the jurisdiction * * @param jurisdiction: the jurisdiction value*/funsetJurisdiction(jurisdiction:String?)
/** * Set Region * * @param region: the region name*/funsetRegion(region:String?)

com.ketch.android.KetchSdk

class KetchSdk - Class used to initialize the Ketch SDK

Methods:

/** * Creates the Ketch * * @param context - an Activity Context to access application assets * @param fragmentManager - The FragmentManager this KetchDialogFragment will be added to. * @param organization - your organization code * @param property - the property name * @param environment - the environment name. * @param listener - Ketch.Listener. Optional * @param ketchUrl - Overrides the ketch url. Optional * @param logLevel - the log level, can be TRACE, DEBUG, INFO, WARN, ERROR. Default is ERROR*/funcreate(
context:Context,
fragmentManager:FragmentManager,
organization:String,
property:String,
environment:String?,
listener:Ketch.Listener?,
ketchUrl:String?,
logLevel:Ketch.LogLevel
): Ketch

com.ketch.android.Ketch.Listener

interface Ketch.Listener - Interface used to list events from the sdk.

Methods:

/** * Called when a dialog is displayed*/funonShow()
/** * Called when a dialog is dismissed*/funonDismiss()
/** * Called when the environment is updated.*/funonEnvironmentUpdated(environment:String?)
/** * Called when the region is updated.*/funonRegionInfoUpdated(regionInfo:String?)
/** * Called when the jurisdiction is updated.*/funonJurisdictionUpdated(jurisdiction:String?)
/** * Called when the identities is updated.*/funonIdentitiesUpdated(identities:String?)
/** * Called when the consent is updated.*/funonConsentUpdated(consent:Consent)
/** * Called on error.*/funonError(errMsg:String?)
/** * Called when USPrivacy is updated.*/funonUSPrivacyUpdated(values:Map<String, Any?>)
/** * Called when TCF is updated.*/funonTCFUpdated(values:Map<String, Any?>)
/** * Called when GPP is updated.*/funonGPPUpdated(values:Map<String, Any?>)

Sample app

We provide a complete sample app to illustrate the integration: here