TRUENDO Android SDK Guide

This guide explains how to integrate the TRUENDO Consent Management Platform (CMP) into your Android app to comply with privacy regulations like the IAB Transparency and Consent Framework (TCF) and Google's user consent policies.

Setup#

Place the cmp-release.aar file in the libs folder of your Android project, as shown in the demo app.

Add the AAR library to your dependencies (don't forget to include the libs folder):

dependencies {
    implementation fileTree(dir: "libs", include: ["*.jar"])
    implementation(name: 'cmp-release', ext: 'aar')
}

Usage#

Adding the View to Your Layout

You can add the TruendoView to your layout in XML:

<com.truendo.cmp.TruendoView
    android:id="@+id/vwBanner"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    app:siteId="YOUR_SITE_ID"
/>

Alternatively, you can create it programmatically:

override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
    super.onViewCreated(view, savedInstanceState)
    val truendoView = TruendoView(requireContext()).apply {
        layoutParams = ViewGroup.LayoutParams(MATCH_PARENT, MATCH_PARENT)
        siteId = "YOUR_SITE_ID"
        setCookieResultListener { cookieSettings ->
            // Save cookie settings
        }
        setCloseListener {
            // React to the close event
        }
    }
    binding.root.addView(truendoView)
}

Showing the Banner or Panel

To show the banner:

binding.vwBanner.show() // Show banner

To show the settings panel using stored cookie settings:

binding.vwBanner.show(storedCookie) // Show Settings Panel

Assigning Listeners

You can assign listeners to handle cookie results and close events:

binding.vwBanner.setCookieResultListener { cookieSettings ->
    requireContext().saveCookieSettings(cookieSettings)
    // Store privacy data in application preferences
    // Use it when you need to open the Settings Panel
}

binding.vwBanner.setCloseListener {
    // Called when the Banner or Panel should be closed
}

Note: TruendoView.setCookieResultListener can be called multiple times, depending on user interaction.

Checking If an Update Is Needed

Use the isUpdateNeeded function to determine if an update is required:

suspend fun isUpdateNeeded(siteId: String, cookie: String): Boolean

• siteId: Your site ID.
• cookie: The cookie string received from TruendoView.

Since this is a suspend function that works in the background, it should be called within a coroutine.

Example usage:

binding.btnCheckUpdate.setOnClickListener {
    requireContext().loadCookieSettings()?.let { cookie ->
        lifecycleScope.launch {
            val siteId = "YOUR_SITE_ID"
            val isUpdateNeeded = TruendoUtils.isUpdateNeeded(siteId, cookie)
            Toast.makeText(
                requireContext(),
                if (isUpdateNeeded) "Update is needed for the website" else "No update needed for the website",
                Toast.LENGTH_LONG
            ).show()
        }
    }
}

You should manage the lifecycle of your fragment or activity appropriately. We recommend running this in a ViewModel and using LiveData or Flow for lifecycle awareness.

TRUENDO Data Container#

The SDK provides the TruendoDataContainer class to help you work with the data structure returned by TRUENDO.

Import

import com.truendo.cmp.TruendoDataContainer

Usage

binding.vwBanner.setCookieResultListener { cookieData ->
    val tdc = TruendoDataContainer(cookieData)

    tdc.getPrivacySettings()?.let { privacySettings ->
        Log.d("TRUENDO Settings", privacySettings)
    }

    tdc.getACString()?.let { acString ->
        Log.d("Google Settings", acString)
    }

    tdc.getTCString()?.let { tcString ->
        Log.d("IAB TCF TC String", tcString)
    }
}

Saving Consent Strings to SharedPreferences

To ensure compliance with IAB TCF and integrate with Google's advertising services, you need to save the TC (Transparency and Consent) and AC (Additional Consent) strings to SharedPreferences under the specified keys.

Example:

binding.vwBanner.setCookieResultListener { cookieData ->
    val tdc = TruendoDataContainer(cookieData)

    // Get the IAB TCF Transparency and Consent string
    tdc.getTCString()?.let { tcString ->
        Log.d("IAB TCF TC String", tcString)
        // Save the TC string to SharedPreferences
        val sharedPrefs = requireContext().getSharedPreferences("IABConsent", Context.MODE_PRIVATE)
        sharedPrefs.edit().putString("IABTCF_TCString", tcString).apply()
    }

    // Get the Google Ads Additional Consent string
    tdc.getACString()?.let { acString ->
        Log.d("Google Settings", acString)
        // Save the AC string to SharedPreferences
        val sharedPrefs = requireContext().getSharedPreferences("IABConsent", Context.MODE_PRIVATE)
        sharedPrefs.edit().putString("IABTCF_AddtlConsent", acString).apply()
    }

    // Enable or disable Advertiser Consent Mode based on client choice
    val userConsent = getUserConsentForIntegration() // Implement this method to get client choice
    val sharedPrefs = requireContext().getSharedPreferences("IABConsent", Context.MODE_PRIVATE)
    sharedPrefs.edit().putBoolean("IABTCF_EnableAdvertiserConsentMode", userConsent).apply()
}

Important Notes:

• IABTCF_EnableAdvertiserConsentMode Flag: To comply with Google's policies, if your CMP offers an IAB TCF-compliant mobile or smart/connected TV app banner, you must implement Google's IABTCF_EnableAdvertiserConsentMode flag in SharedPreferences, in the same way specified by IAB for TCF.
• Client Choice: Clients must be given the choice whether to use or not use this integration. You should provide a way for clients to opt-in or opt-out of saving this data to SharedPreferences.

Keys Used in SharedPreferences:

• IABTCF_TCString: Stores the IAB TCF Transparency and Consent string.
• IABTCF_AddtlConsent: Stores the Google Additional Consent string.
• IABTCF_EnableAdvertiserConsentMode: A boolean flag to enable or disable Google's Advertiser Consent Mode.

Providing Client Choice:

Ensure that your app allows clients to decide whether they want to enable this integration. You can achieve this by adding a setting in your app's preferences or by prompting the client during the consent flow.

Example:

fun getUserConsentForIntegration(): Boolean {
    // Implement your logic to retrieve the client's choice
    // For example, read from a stored preference or prompt the client
    return clientPreferenceForAdvertiserConsentMode
}

// Usage within setCookieResultListener
binding.vwBanner.setCookieResultListener { cookieData ->
    // ... (retrieve TC and AC strings)

    // Enable or disable Advertiser Consent Mode based on client choice
    val userConsent = getUserConsentForIntegration()
    val sharedPrefs = requireContext().getSharedPreferences("IABConsent", Context.MODE_PRIVATE)
    sharedPrefs.edit().putBoolean("IABTCF_EnableAdvertiserConsentMode", userConsent).apply()
}

Explanation:

• Saving the TC String: The TC string is required by ad networks to understand the client's consent choices. Saving it under the key IABTCF_TCString allows compliant ad networks to retrieve it automatically.
• Saving the AC String: The AC string provides additional consent information needed by Google. Saving it under the key IABTCF_AddtlConsent ensures compatibility with Google's services.
• IABTCF_EnableAdvertiserConsentMode Flag: This flag tells Google's SDK whether to use the consent information provided via the IAB TCF framework.

Retrieving Client Consent for Integration

Implement a method to obtain the client's choice regarding the use of this integration. This could be through a settings screen or during the initial consent flow.

Example:

fun getUserConsentForIntegration(): Boolean {
    // Access client's preference from SharedPreferences or another storage
    val prefs = requireContext().getSharedPreferences("AppPreferences", Context.MODE_PRIVATE)
    return prefs.getBoolean("EnableAdvertiserConsentMode", false)
}

// Optionally, set the preference based on client interaction
fun setUserConsentForIntegration(consentGiven: Boolean) {
    val prefs = requireContext().getSharedPreferences("AppPreferences", Context.MODE_PRIVATE)
    prefs.edit().putBoolean("EnableAdvertiserConsentMode", consentGiven).apply()
}

Prompting the Client:

You can prompt the client during the consent flow:

// Inside your consent dialog or settings
val consentGiven = // result from client's choice
setUserConsentForIntegration(consentGiven)

Summary#

By following these steps, you ensure that:

• Compliance: Your app adheres to IAB TCF guidelines and Google's policies.
• Transparency: Clients are informed and have control over how their data is used.
• Integration: Ad networks and Google's services can access the necessary consent information automatically.