Introduction
The Osano Consent SDK for Android is a native framework that integrates with the Consent Management Platform on the Osano Website. To use this SDK effectively, you need an Osano account and a published Cookie Consent configuration.
Getting Started
ConsentManager Setup
The ConsentManager
is the core object of the SDK. Here's how to create an instance:
import com.osano.mobile_sdk.ConsentManager
import com.osano.mobile_sdk.ui.consent_variant.ConsentDialog
import com.osano.mobile_sdk.ui.consent_categories.StoragePreferenceDialog
import com.osano.mobile_sdk.data.model.Category
val consentResultListener = object : ConsentDialog.OnConsentResultListener {
override fun onAccept(consentedTo: List<Category>) {
print(consentedTo)
}
override fun onDeny() {
print("Rejected all")
}
}
val consentManager = ConsentManager.Builder(this)
.setConfigId("YOUR_CONFIG_ID")
.setCustomerId("YOUR_CUSTOMER_ID")
.setConsentingDomain("YOUR_CONSENTING_DOMAIN")
.build()
The configId
, customerId
, and consentingDomain
parameters are mandatory and must match your configuration on the Osano website. The consenting domain should be a fully qualified URL.
Optional Configuration
- Enable debug logging:
.setDebugMode(true)
- Additional User Information:
.setExtUsrData("id")
- Override country locale:
.setCountryCode("us")
- Override language:
.setLanguageCode("es")
- Enable consent expiration testing mode:
.setConsentExpirationTestingMode(10)
(debug mode only) - Trigger default UI to appear after ConsentManager initialization:
.setShouldAutoShowDialog(true)
- Set the auto-show dialog
OnConsentResultListener
:.setAutoShowConsentResultListener(consentResultListener)
Using extUsrData
allows you to associate an external user identifier (such as a user ID from your own system) with the consent record. This parameter is required for cross-device consent, which ensures that a user's consent preferences are recognized consistently across multiple apps, devices, or browser sessions.
For example, if a user logs into your service on both web and mobile, providing the same external ID ensures that their consent preferences are unified and respected across all environments.
Important! It is not advisable to use any personally identifiable information as your extUsrData
in order to avoid any privacy violations. Additionally, the provided extUsrData
will not be stored in a consent record unless cross-device consent is enabled.
If not explicitly set the SDK will use country and language defaults as follows:
- Country: Determined from the IP address of the device and provided via a CloudFront geolocation header during the consent configuration network request.
- Language: Device language
Locale.getDefault().language
Deprecated Configuration
- Set banner timeout:
.setTimeoutInSeconds(3)
Please configure the 'Timeout Duration (in seconds)' in the Osano dashboard under your configuration's 'Styles' settings.
Optional UI Implementation
If you'd rather be in more control of when the UI shows and avoid using .setShouldAutoShowDialog(true)
, follow these instructions:
- ConsentDialog
- StoragePreferenceDialog
Both can be displayed in three presentation styles:
- Dialog
showAsDialog()
- Fragment
showAsFragment()
- Bottom Sheet
showAsBottomSheet()
ConsentDialog
val builder = ConsentDialog.Builder(this, consentManager)
.setOnConsentResultListener(object : ConsentDialog.OnConsentResultListener {
override fun onAccept(consentedTo: List<Category>) {
print(consentedTo)
}
override fun onDeny() {
print("Rejected all")
}
})
// Present as dialog
builder.showAsDialog(supportFragmentManager)
By default, the ConsentDialog will show in a banner style best suited to the compliance requirements of the user's region.
Depending on the region, the dialog may have an implied consent with automatic timeout. This behavior is expected and can be configured on my.osano.com.
StoragePreferenceDialog
val builder =
StoragePreferenceDialog
.Builder(this@MainActivity, consentManager)
.setOnConsentStoredListener(
object : ConsentManager.OnConsentStoredListener() {
override fun onSuccess(categories: Set<Category>) {
print(categories)
}
override fun onFailure(throwable: Throwable?) {
print("Failed to store consent)
ConsentState.clearConsent()
}
},
)
// Present as bottom sheet
builder.showAsDialog(supportFragmentManager)
Customization
Customize the appearance using these optional methods:
builder
.setBackgroundColor(getColor(R.color.white))
.setTextColor(getColor(R.color.black))
.setAccentColor(getColor(R.color.blue))
.setPositiveColor(getColor(R.color.blue))
.setNegativeColor(getColor(R.color.gray))
.setPositiveTextColor(getColor(R.color.white))
.setNegativeTextColor(getColor(R.color.white))
The SDK will inherit any text customizations created in the CMP configuration. To update any translations in our supported languages, log into my.osano.com and update the corresponding CMP configuration used by the SDK.
Using Custom UI
If you prefer to use your own UI, you can utilize the ConsentManager
APIs directly:
// Store consent
val categories = setOf(Category.Essential, Category.Analytics)
consentManager.storeConsent(categories, object: OnConsentStoredListener {
override fun onSuccess(categories: Set<Category>) {}
override fun onFailure(t: Throwable) {}
})
// Check if user has consented
val hasConsented = consentManager.hasUserConsented()
// Get consented categories
val consentedCategories = consentManager.getConsentedCategories()
// Clear stored consent
consentManager.clearConsent()
IAB TCF 2.2
IAB is supported without any additional customization as long as the following conditions are met:
- IAB is enabled on the config
- The end user is browsing from Canada or a jurisdiction that has adopted GDPR
TCF Strings will be generated and stored in the IABTCF_TCString
UserPreferences key, and can be accessed with ConsentManager.getTcfString