Mobile SDK (Android)

  • Updated

- Osano Android SDK Deprecated as of 7/1/2024 - 

Documentation for Osano's mobile privacy SDKs for iOS and React Native apps can be found in our Developer Hub. Please refer to react native SDK for android application development until further notice. Android SDK below currently unsupported by Osano.

______________________________________________

Overview

The Osano Android SDK allows developers a simple way to integrate consent capture and consent preferences into their Android applications. In contrast to our web solution, the Android SDK captures only consent records and does not tattle or actively block libraries from loading. Consent record and preference changes are stored remotely through our API and on the device for 365 days. If a user deletes the application, their preferences are deleted as well.

Features Provided

  • UI for end-users
    • Screens:
      • Banner
      • Manage Storage Preferences
    • Translation
    • Detect language and apply the legally required regional consent options 
  • Consent capture

Note: Currently the Android SDK only supports fully native components and will not pass consent preferences to any embedded web views. 

Running the Sample Application

  1. Get the zip file contents provided by Osano’s Sales & Support team.
  2. Extract the zip file contents.
  3. Open Android Studio, and open the extracted folder for the android SDK sample app.
  4. Select a device in Android Studio, and run it.

Installing the Android SDK

Add the following to the build.gradle file in your Android application.

repositories {
    maven { url "https://libraries.osano.com/android" }
}
dependencies {
    implementation "com.osano.android:consent-manager-sdk:2.0.11"  
}

Updating to a New Version

To change the version of the SDK, replace the version to the newer SDK version you wish to use. If we wanted to use the 2.2.0 version of the SDK, replace 2.0.11 with the new version. When the project is built, the new version is downloaded and installed.

How do I use it?

ConsentManager

How to Instantiate a ConsentManager object with ConsentManagerBuilder:

  val consentManager = ConsentManagerBuilder(this)
        .configId("yourConfigId")
        .customerId("yourCustomerId")
        .setCountryCode("us")
        .timeout(3) // default is 10s for timer dialog
        .build();

Properties

  • customerId - This can be retrieved via your consent manager configuration in the web app or via Osano customer support.
    • private const val CUSTOMER_ID = "123456789abcdefghi"
  • configId - Available in your consent manager configuration in the Osano web application (Both the config ID and the customer ID are included in your osano.js src="https://cmp.osano.com/222cpvRm9bbsqngN/22222aa0-c222-2222-81d2-7671fc6e8479/osano.js”)
    • sample: "11111111-2222-3333-4444-555555555555"
  • consentingDomain  - Optional value associated domain that this consent should be associated with.
    • Max characters - 256
    • private const val CONSENTING_DOMAIN = "http://<your-domain>"
  • setCountryCode - Optional character country code. For a list of consent dialog regions based on country, please visit Consent Banner Regions.
    • Ensures the correct variant is displayed in accordance with the laws of the respective country.
    • If not provided the SDK will use the device locale

Consent Dialogue

With ConsentDialogue, you can display user consent dialogues with built-in methods. This object will show timer/consent categories/no-consent-category dialogues based on your given country code. Instantiate a ConsentDialogue object with ConsentDialogue.Builder:

    ConsentDialogue.Builder(this, consentManager)
        .setCountryCode(countryCode) // nullable. Default is the device's country code.
        .setOnConsentResultListener(object : OnConsentResultListener {
            override fun onAccept(consentedTo: List<Category>) {
                Toast.makeText(applicationContext,
                        String.format(getString(R.string.accepted), consentedTo),
                        Toast.LENGTH_SHORT).show()
            }

            override fun onDeny() {
                Toast.makeText(applicationContext, getString(R.string.denied), Toast.LENGTH_SHORT).show()
            }
        })
        .showAsDialogue(supportFragmentManager)

The SDK offers three options for displaying the Consent banner dialogue:

  • As a Fragment
    • R.id.rb_fragment -> consentDialogueBuilder.showAsFragment(supportFragmentManager)
  • As a Dialogue
    • R.id.rb_dialog -> consentDialogueBuilder.showAsDialogue(supportFragmentManager)
  • As a BottomSheet
    • R.id.rb_bottom_sheet -> consentDialogueBuilder.showAsBottomSheet(supportFragmentManager)

You can also show the ConsentDialogue in "full screen" mode instead of a dialogue using :

ConsentDialogue#showAsScreen():
    ConsentDialogue.Builder(this, consentManager)
        .setOnConsentResultListener(listener)
        .showAsScreen(supportFragmentManager)

Personalize the ConsentDialogue UI to your branding using color resources for each of the UI elements. Custom color codes can be added to the colors.xml file and used in the UI. The SDK provides the ability to adjust the colors for the following elements within the consent banner dialog.

   ConsentDialogue.Builder(this, consentManager)
        .setOnConsentResultListener(listener)
        .setBackgroundColor(R.color.blue)
        .setTextColor(R.color.white)
        .setAccentColor(R.color.green)
        .setPositiveColor(R.color.green)
        .setNegativeColor(R.color.gray)
        .showAsDialogue(supportFragmentManager)<br>

Set the data storage policy link to your own valid policy URL. It’s currently set to google.com for testing purposes.

  • .setDataStoragePolicyLink("https://www.google.com")

StoragePreferenceDialogue

Using StoragePreferenceDialogue you can display all consent categories dialog with the built-in UI. With this UI, the user can choose to enable or disable any categories they want. Instantiate a StoragePreferenceDialogue object with 

StoragePreferenceDialogue.Builder:
   StoragePreferenceDialogue.Builder(this, consentManager)
        .setOnConsentStoredListener(object : OnConsentStoredListener() {
            override fun onSuccess(consentedCategories: List<Category>) {
                Toast.makeText(applicationContext,
                    String.format(getString(R.string.consent_stored), consentedCategories),
                    Toast.LENGTH_SHORT).show()
            }
            override fun onFailure(throwable: Throwable?) {
                super.onFailure(throwable)
            }
        })
        .showAsDialogue(supportFragmentManager)<br>

The Osano SDK offers three options for displaying the storage preference dialog:

  • As a Fragment
    • R.id.rb_fragment -> storagePreferenceDialogue.showAsFragment(supportFragmentManager) 
  • As a Dialogue
    • R.id.rb_dialog -> storagePreferenceDialogue.showAsDialogue(supportFragmentManager)
  • As a BottomSheet
    • R.id.rb_bottom_sheet -> storagePreferenceDialogue.showAsBottomSheet(supportFragmentManager)

You can also show the StoragePreferenceDialogue in "full screen" mode instead of a dialog using StoragePreferenceDialogue#showAsScreen():

  StoragePreferenceDialogue.Builder(this, consentManager)
        .setOnConsentStoredListener(listener)
        .showAsScreen(supportFragmentManager)<br>

Personalize the StoragePreferenceDialogue UI using color resources for each of the UI elements. The SDK provides the ability to adjust the colors for the following elements within the Storage Preferences Dialogue:

   StoragePreferenceDialogue.Builder(this, consentManager)
        .setOnConsentStoredListener(listener)
        .setBackgroundColor(R.color.white)
        .setTextColor(R.color.black)
        .setAccentColor(R.color.green)
        .setPositiveColor(R.color.green)
        .showAsDialogue(supportFragmentManager)	<br>

CCPA Opt-Out Mode

Customers who know they are in CCPA opt-out mode may choose to not show the modal and set the end-user consent as accepting cookies

  • In order to provide a link to Collection Preferences, bind the storage preferences dialog to a link.
  • In order to opt users into certain preferences, you should be able to call the consentManager.storeConsent.
  • The consent banner dialog can be disabled in the UI by simply commenting out the following:
    • binding.btnShowMessaging.setOnClickListener{ showConsentDialogue() }
    • private fun showConsentDialogue({...})

 

API Only

You may create your own UI and call our public APIs and integrate them into your view easily:

   // did user consent?
    consentManager.didUserConsent()
    // get list of user-consented categories
    val consentedToCategories = consentManager.userConsentedTo
    // get disclosures based on your customer id and config id
    consentManager.getDisclosures(object : OnDisclosureListener() {
        override fun onSuccess(@Nullable disclosures: List<Disclosure>?) {
            super.onSuccess(disclosures)
        }

        override fun onFailure(throwable: Throwable) {
            super.onFailure(throwable)
        }
    })

    // store consented content remotely and locally
    consentManager.storeConsent(consentedToCategories, object : OnConsentStoredListener() {
        override fun onSuccess(@NonNull consentedCategories: List<Category>) {
            super.onSuccess(consentedCategories)
        }

        override fun onFailure(@Nullable throwable: Throwable?) {
            super.onFailure(throwable)
        }
    })<br>

Blocking Libraries

You should map your libraries to the consent categories. When a user denies consent, those libraries should stop sending data. In addition, the next time the app is closed and opens, those libraries should not initialize. 

Upon request, we can provide our recommendations on what category your libraries map to.