Skip to main content

Integration

How to use AppConsent​

1. Get your AppKey from AppConsent : https://app.appconsent.io​

GetAppkey

2. Create AppConsent Instance​

Full description of the integration example below

In this example, we'll make sure that the CMP is displayed to users when the application is launched (startup of our activity).

Here are the various steps in this example at first launch​

  1. Check SDK if already initialized (return false)
  2. Initialize the CMP by calling AppConsentSDK#initialize if not.
  3. Once the SDK has been started, record callbacks to let you know when the user has finished entering information.
  4. Call the #tryToDisplayNotice(false) method, which displays the CMP only when necessary. (in the example, it will be displayed).
  5. check the return of #tryToDisplayNotice(false) to determine whether the CMP has been displayed or not (return to true).
  6. Once the user has given their consent, the #presentConsentGiven method will be called and you can, for example, start up your PUB SDK (AdMob, Vungle, Amazon mobile Ads, etc.).

Here are the various steps in this example on the next launch (having killed the application)​

  1. Check SDK if it has already been initialized (return false)
  2. Initialize the CMP by calling AppConsentSDK#initialize, if not.
  3. Once the SDK has been started, record callbacks to let you know when the user has finished entering information.
  4. Call the #tryToDisplayNotice(false) method, which displays the CMP only if necessary.
  5. check the return of #tryToDisplayNotice(false) to determine whether or not the CMP has been displayed (result set to false).
  6. Call the #checkForUpdate method to check whether the Notice has been updated from your Dashboard (unless you take action, result is false).
  7. No action is required, so you can start up your PUB SDK (AdMob, Vungle, Amazon mobile Ads, etc.).

Here are the various steps in this example on the next launch (quitting the application and bringing it forward again without killing it)​

  1. Check SDK if it has already been initialized (return to true)
  2. Recover instance for local use in our activity
  3. Call the #tryToDisplayNotice(false) method, which displays the CMP only if necessary.
  4. check the return of #tryToDisplayNotice(false) to determine whether the CMP has been displayed or not (result set to false).
  5. Call the #checkForUpdate method to check whether the Notice has been updated from your Dashboard (unless you take action, result is false).
  6. No action is required, so you can start up your PUB SDK (AdMob, Vungle, Amazon mobile Ads, etc.).

Here are the various steps in this example at the next launch AND after you've modified your Notice from the Dashboard (by quitting the application and bringing it forward again without killing it)​

  1. Check SDK if it has already been initialized (return to true)
  2. Recover instance for local use in our activity
  3. Call the #tryToDisplayNotice(false) method, which displays the CMP only if necessary.
  4. check the return of #tryToDisplayNotice(false) to determine whether the CMP has been displayed or not (result set to false).
  5. Call the #checkForUpdate method to check whether the Notice has been updated from your Dashboard (result is true because your Notice has been updated).
  6. Local deletion of previous user consent #clearConsent
  7. Call the #tryToDisplayNotice(false) method to display the CMP only if necessary. (return to true)
  8. Once the user has given consent, the #presentConsentGiven method will be called and you can, for example, start your PUB SDK (AdMob, Vungle, Amazon mobile Ads, etc.).
import android.content.Intent
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import com.sfbx.appconsent.AppConsent
import com.sfbx.appconsent.ui.AppConsentSDK
import com.sfbx.appconsent.ui.listener.OnPresentNoticeListener
import com.sfbx.appconsent.ui.model.ACConfiguration
import io.sfbx.clearkotlin.databinding.ActivityMainBinding

class MainActivity : AppCompatActivity() {

    private var appConsent: AppConsent? = null
    private lateinit var binding: ActivityMainBinding

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        binding = ActivityMainBinding.inflate(layoutInflater)

        setContentView(binding.root)

        binding.buttonDisplaySecondActivity.setOnClickListener {
            startActivity(Intent(this, SecondActivity::class.java))
        }
        binding.buttonClearCache.setOnClickListener {
            appConsent?.clearCache()
        }
        binding.buttonDisplayNotice.setOnClickListener {
            appConsent?.tryToDisplayNotice(false)
        }

        /*
        Shows whether the SDK has already been initialized
         */
        if (!AppConsentSDK.isSdkInitialized()) {
            initCmpModule()
        } else {
            if (appConsent == null) {
                /*
                Retrieves the AppConsent instance or null if it has not yet been instantiated, for example
                 */
                appConsent = AppConsentSDK.getInstance()
            }
            tryToDisplayCmpAndCheckUpdateIfNeeded()
        }
    }

    private fun checkIfNoticeHasBeenUpdated() {
        appConsent?.checkForUpdate({ isNeedToPresentTheCmp: Boolean ->
            // Your Notice has been updated, you must represent the CMP to your users
            if (true == isNeedToPresentTheCmp) {
                /*
                Deletes old user consent locally.
                This step is not mandatory, but it avoids the need to make another network call
                to check whether the Notice has been updated,
                as no consent will be present on the user's device.
                 */
                appConsent?.clearConsent()
                tryToDisplayCMP()
            } else {
                /*
                The Notice is the same as when it was last checked
                (you have made no changes since the board or
                it has not been updated internally by us, e.g. by updating a vendor)
                 */
            }
        }) { _: Throwable? ->
            /*
             An error has occurred
             */
        }
    }

    /**
     * Try to display the CMP
     *
     * @return true, if the CMP displaying, false otherwise
     */
    private fun tryToDisplayCMP(): Boolean {
        /*
         Try to display the CMP according to certain rules.
         */
        return appConsent?.tryToDisplayNotice(false) ?: false
    }

    private fun tryToDisplayCmpAndCheckUpdateIfNeeded() {
        /*
         Try to display the CMP according to certain rules first.
         */
        if (false == tryToDisplayCMP()) {
            /*
             The user has already given consent;
             The user is not part of an area subject to the application of GDPR;
             etc.
             */

            /*
            The Notice has not been displayed,
            so we'll have to check whether it has been updated
            and whether it needs to be shown to users again.
             */
            checkIfNoticeHasBeenUpdated()
        }
    }

    /*
     Initializes the consent management platform module when the activity is created
     */
    private fun initCmpModule() {
        /*
        ACConfiguration is used to configure the CMP.
        In this example:
        - We set forceApplyGDPR to true to display the CMP regardless of the user's region.
        - Decide to display the CMP in FullScreen rather than modal.
        - CMP is configured so that layer 1 buttons are displayed vertically and not horizontally (except in landscape mode).
         */
        val acConfiguration = ACConfiguration.Builder()
            .setForceApplyGDPR(true)
            .setFullScreenMode(true)
            .setNeedToDisplayValidationButtonsVertically(isNeedToDisplayButtonsAtVertical = true)
            .build()

        AppConsentSDK.initialize(
            appKey = "YOUR_APP_KEY",
            configuration = acConfiguration
        ) { appConsentInitialized ->
            /*
             To avoid certain problems, use the instance received by the onReady callback
             This has been successfully initialized
             */
            appConsent = appConsentInitialized
            /*
             Registers with CMP callback to know when the user
             has given consent, or if an error has occurred
             */
            appConsent?.setOnPresentNoticeListener(object : OnPresentNoticeListener {
                override fun presentConsentError(error: Throwable?) {
                    /*
                     An error has occurred
                     */
                    removeCMPCallback()
                }

                override fun presentConsentGiven() {
                    /*
                    The user has given his consent
                    */
                    removeCMPCallback()
                }
            })
            tryToDisplayCmpAndCheckUpdateIfNeeded()
        }
    }

    private fun removeCMPCallback() {
        /*
        Not mandatory, but avoids keeping a local reference to the callback.
        Of course, it all depends on how your project is implemented.
        For example, with an SOP Activity, a singleton monitored by a flow, etc.
         */
        appConsent?.setOnPresentNoticeListener(null)
    }
}

Visual support​

Here are a few examples of possible renderings linked to the SDK configuration (the highlighting of the Accept All button is configured from the BO - see HighLight mode)

Vertical mode​
Example of rendering configured in the code example above  Example of rendering with vertically aligned buttons and CMP in popup mode  Example of rendering with orientation-dependent button alignment

Mode horizontal​
Example of rendering with buttons aligned horizontally and CMP in full-screen mode   Example of rendering with buttons aligned horizontally and CMP in popup mode
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import com.sfbx.appconsent.ui.AppConsentSDK
import com.sfbx.appconsent.ui.listener.OnPresentNoticeListener
import io.sfbx.clearkotlin.databinding.ActivitySecondBinding

class SecondActivity : AppCompatActivity() {

    private lateinit var binding: ActivitySecondBinding

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        binding = ActivitySecondBinding.inflate(layoutInflater)
        setContentView(binding.root)

        binding.buttonDisplayPrivacyPolicy.setOnClickListener {
            /*
             Registers with CMP callback to know when the user
             has updated consent, or if an error has occurred
             */
            AppConsentSDK.getInstance()
                ?.setOnPresentNoticeListener(object : OnPresentNoticeListener {
                    override fun presentConsentError(error: Throwable?) {
                        /*
                         An error has occurred
                         */
                        removeCMPCallback()
                    }

                    override fun presentConsentGiven() {
                        /*
                        The user has updated his consent
                        */
                        removeCMPCallback()
                    }
                })
            /*
            Display the CMP to allow your users to consult their consent
            */
            val isCmpDisplayed =
                AppConsentSDK.getInstance()?.tryToDisplayNotice(force = true) ?: false
            if (false == isCmpDisplayed) {
                /*
                The CMP is not initialized (getInstance() return null),
                make sure it is initialized (see 2. Create the AppConsent instance).
                Also check that your activity has not been started in a new process
                (new process, new memory stack, uninitialized singleton).
                 */
            }
        }
    }

    private fun removeCMPCallback() {
        /*
        Not mandatory, but avoids keeping a local reference to the callback.
        Of course, it all depends on how your project is implemented.
        For example, with an SOP Activity, a singleton monitored by a flow, etc.
         */
        AppConsentSDK.getInstance()?.setOnPresentNoticeListener(null)
    }
}

4. Then use appConsent object​

  • Check if user gave consent
appConsent.consentGiven()

Return true if consent is given, false otherwise.

  • Consent listener
Add Listener​

When the user has completed his journey and given his consent, it allows to be notified.

appConsent.setOnPresentNoticeListener(object : OnPresentNoticeListener { 
    override fun presentConsentGiven() {
        // ...
    }

    override fun presentConsentError(error: Throwable?) {
        // ...
    }
})
Remove Listener​
appConsent.setOnPresentNoticeListener(null)
  • Try to Display CMP notice

There are 2 display modes:

  1. The first runs only if user consent is required.
  2. The second, which should be used to allow your users to consult/modify their consent (often used from your settings screen to display your user's privacy policy).

By default this method tries to display the CMP. It tries because, depending on the region of your users (if no settings are made via ACConfiguration to force the display) then it will follow its controls and display the CMP only if necessary.



It will also be displayed if the user consent has not yet been given or if it needs to be renewed.
// @return true if the notice display, false otherwise
appConsent.tryToDisplayNotice(false) // display CMP notice only if needed
appConsent.tryToDisplayNotice(true) // force to display CMP notice

It returns 'true' if the CMP is displayed, 'false' otherwise

info

tryToDisplayNotice(force : Boolean) is a local method that only check cache. See checkForUpdate() to fetch a notice update

  • Consentable allowed
appConsent.consentableAllowed(1,0)

Return true if consentable with id = 1 and consentableType = 0 is allowed, false otherwise. The id to pass is the iabId of your purpose and the consentableType is the type, e.g: purpose = 0 .

  • Stack Allowed
appConsent.stackAllowed(1)

Return true if stack with id = 1 is allowed, false otherwise.

  • Vendor allowed
appConsent.vendorAllowed(1)

Return true if vendor with id = 1 is allowed, false otherwise.

  • Set consentable status
appConsent.setConsentableConsents(
    mapOf(1 to ConsentStatus.ALLOWED, 2 to ConsentStatus.DISALLOWED),
    object : AppConsentSetConsentableConsentsCallback {
        override fun onSuccess() {
            // ...
        }

        override fun onError(t: Throwable) {
            // ...
        }
    }
)

Set consentables status, save it and send it to server.

  • Check for update
appConsent.checkForUpdate({ isNeedToPresentTheCmp: Boolean ->
            // Your Notice has been updated, you must represent the CMP to your users
            if (true == isNeedToPresentTheCmp) {
                /*
                Deletes old user consent locally.
                This step is not mandatory, but it avoids the need to make another network call
                to check whether the Notice has been updated,
                as no consent will be present on the user's device.
                 */
                appConsent.clearConsent()
                appConsent.tryToDisplayNotice(false)
            } else {
                /*
                The Notice is the same as when it was last checked
                (you have made no changes since the board or
                it has not been updated internally by us, e.g. by updating a vendor)
                 */
            }
        }) { _: Throwable? ->
            /*
             An error has occurred
             */
        }

Check if consent must be updated (new gvl version, new consentables, updating your Notice, new vendors, changing the duration of consents, etc.).

  • Clear consents
appConsent.clearConsent()

Locally removes user consent, but not on the server (this will allow a new display of the CMP on the next call to tryToDisplayNotice(false) for example)

  • Set external data
DEPRECATED

This method will be removed in the next release, use setExternalIds(ids: Map<String, String>)

val map = mapOf<String, Any>("externalId" to "abze23", "otherData" to "{\"name\": \"test\"}")
appConsent.setExternalData(map)

Allows to define additional Ids that will be taken into account when validating user consent.

  • Get external data
val map: Map<String, Any> = appConsent.getExternalData()

5. Retrieve your consents​

Your consents are saved in SharedPreferences of your application. To know more about keys used to save your consents, please refer to the IAB documentation.

We also provide an additional key for Google Additionnal Consent IABTCF_AddtlConsent returning a String.

Last updated on