Aller au contenu principal

Intégration

Comment utiliser AppConsent​

1. Obtenez votre AppKey dans AppConsent : https://app.appconsent.io​

GetAppkey

2. Créez l'instance de AppConsent​

Descriptif complet de l'exemple d'intégration ci-dessous

Dans cet exemple nous nous assurons de l'affichage de la CMP aux utilisateurs au lancement de l'application (démarrage de notre activité).

Voici les différentes étapes de cet exemple au premier lancement​

  1. Vérification du SDK si celui-ci à déjà été initialisé (retour à false)
  2. Initialisation de la CMP avec l'appel de AppConsentSDK#initialize dans le cas contraire
  3. Une fois le SDK démarré, enregistrement des callbacks permettant de savoir quand l'utilisateur aura fini de saisir ses informations.
  4. Appel de la méthode #tryToDisplayNotice(false) qui permet d'afficher la CMP seulement si c'est nécessaire. (dans l'exemple elle s'affichera)
  5. vérification du retour de #tryToDisplayNotice(false) qui permet de savoir si la CMP c'est affiché ou non (retour à true)
  6. Une fois le consentement donnée par l'utilisateur, la méthode #presentConsentGiven sera appelé et vous pouvez par exemple démarrer votre SDK de PUB (AdMob, Vungle, Amazon mobile Ads, etc.)

Voici les différentes étapes de cet exemple au lancement suivant (en ayant tué l'application)​

  1. Vérification du SDK si celui-ci à déjà été initialisé (retour à false)
  2. Initialisation de la CMP avec l'appel de AppConsentSDK#initialize dans le cas contraire
  3. Une fois le SDK démarré, enregistrement des callbacks permettant de savoir quand l'utilisateur aura fini de saisir ses informations.
  4. Appel de la méthode #tryToDisplayNotice(false) qui permet d'afficher la CMP seulement si c'est nécessaire.
  5. vérification du retour de #tryToDisplayNotice(false) qui permet de savoir si la CMP c'est affiché ou non (résultat à false)
  6. Appel la méthode #checkForUpdate pour vérifier si la Notice a été mise à jour depuis votre Dashboard (sauf action de votre part, résultat à false)
  7. Aucunes action n'est nécessaire, vous pouvez par exemple démarrer votre SDK de PUB (AdMob, Vungle, Amazon mobile Ads, etc.)

Voici les différentes étapes de cet exemple au lancement suivant (en quittant l'application et en la remettant en avant sans la tuée)​

  1. Vérification du SDK si celui-ci à déjà été initialisé (retour à true)
  2. Récupération de l'instance pour l'utiliser localement dans notre activity
  3. Appel de la méthode #tryToDisplayNotice(false) qui permet d'afficher la CMP seulement si c'est nécessaire.
  4. vérification du retour de #tryToDisplayNotice(false) qui permet de savoir si la CMP c'est affiché ou non (résultat à false)
  5. Appel la méthode #checkForUpdate pour vérifier si la Notice a été mise à jour depuis votre Dashboard (sauf action de votre part, résultat à false)
  6. Aucunes action n'est nécessaire, vous pouvez par exemple démarrer votre SDK de PUB (AdMob, Vungle, Amazon mobile Ads, etc.)

Voici les différentes étapes de cet exemple au lancement suivant ET après avoir modifié votre Notice depuis le Dashboard (en quittant l'application et en la remettant en avant sans la tuée)​

  1. Vérification du SDK si celui-ci à déjà été initialisé (retour à true)
  2. Récupération de l'instance pour l'utiliser localement dans notre activity
  3. Appel de la méthode #tryToDisplayNotice(false) qui permet d'afficher la CMP seulement si c'est nécessaire.
  4. vérification du retour de #tryToDisplayNotice(false) qui permet de savoir si la CMP c'est affiché ou non (résultat à false)
  5. Appel la méthode #checkForUpdate pour vérifier si la Notice a été mise à jour depuis votre Dashboard (résultat à true car votre Notice a été mise à jour)
  6. Suppression local du précédent consentement utilisateur #clearConsent
  7. Appel de la méthode #tryToDisplayNotice(false) qui permet d'afficher la CMP seulement si c'est nécessaire. (retour à true)
  8. Une fois le consentement donnée par l'utilisateur, la méthode #presentConsentGiven sera appelé et vous pouvez par exemple démarrer votre SDK de PUB (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)
        }

        /*
        Permet de savoir si le SDK a dors et déjà été initialisé
         */
        if (!AppConsentSDK.isSdkInitialized()) {
            initCmpModule()
        } else {
            if (appConsent == null) {
                /*
                Permet de récupérer l'instance de AppConsent ou null si elle n'a pas encore été instancié par exemple
                 */
                appConsent = AppConsentSDK.getInstance()
            }
            tryToDisplayCmpAndCheckUpdateIfNeeded()
        }
    }

    private fun checkIfNoticeHasBeenUpdated() {
        appConsent?.checkForUpdate({ isNeedToPresentTheCmp: Boolean ->
            // Votre Notice a été mise à jour, vous devez représenter la CMP à vos utilisateurs
            if (true == isNeedToPresentTheCmp) {
                /*
                Permet de supprimer localement l'ancien consentement utilisateur.
                Cette étape n'est pas obligatoire, mais elle permet d'éviter de refaire un appel réseau
                pour vérifier plus tard si la Notice a été mise à jour
                car plus aucuns consentement ne sera présent sur le device de l'utilisateur.
                 */
                appConsent?.clearConsent()
                tryToDisplayCMP()
            } else {
                /*
                La Notice est la même que lors de la dernière vérification
                (vous n'avez apporté aucunes modification depuis le board ou
                celle-ci n'a pas subit de mise à jour interne par nos soins;
                comme par exemple la mise à jour d'un vendor)
                 */
            }
        }) { _: Throwable? ->
            /*
             Une erreur s'est produite
             */
        }
    }

    /**
     * Essaye d'afficher la CMP
     *
     * @return true, si la CMP s'affiche, false sinon
     */
    private fun tryToDisplayCMP(): Boolean {
        /*
         Essaye d'afficher la CMP selon certaines règles.
         */
        return appConsent?.tryToDisplayNotice(false) ?: false
    }

    private fun tryToDisplayCmpAndCheckUpdateIfNeeded() {
        /*
         Dans un premier temps, essaye d'afficher la CMP selon certaines règles.
         */
        if (false == tryToDisplayCMP()) {
            /*
             L'utilisateur a déjà donné son consentement;
             L'utilisateur ne fait pas partie d'une zone sujet à l'application des RGPD;
             etc.
             */

            /*
            La Notice ne c'est pas affiché,
            il nous reste à vérifier dans un second temps si celle-ci a subit une mise à jour
            et que celle-ci doit être de nouveau représenté aux utilisateurs.
             */
            checkIfNoticeHasBeenUpdated()
        }
    }

    /*
     Initialise le module de plateforme de gestion des consentements, lors de la création de l'activity
     */
    private fun initCmpModule() {
        /*
        ACConfiguration permet de configurer la CMP.
        Dans l'exemple ici:
        - On défini forceApplyGDPR à true pour afficher la CMP quelque soit la région des utilisateurs.
        - On décide d'afficher la CMP en FullScreen plutôt qu'en modal.
        - On configure la CMP pour que les boutons du layer 1 s'affichent verticalement et non pas horizontalement (sauf en mode paysage)
         */
        val acConfiguration = ACConfiguration.Builder()
            .setForceApplyGDPR(true)
            .setFullScreenMode(true)
            .setNeedToDisplayValidationButtonsVertically(isNeedToDisplayButtonsAtVertical = true)
            .build()

        AppConsentSDK.initialize(
            appKey = "YOUR_APP_KEY",
            configuration = acConfiguration
        ) { appConsentInitialized ->
            /*
             Pour éviter certains problèmes, utilisez l'instance reçue par le callback onReady
             Celle-ci a été initialisée avec succès
             */
            appConsent = appConsentInitialized
            /*
             S'enregistre au callback de la CMP pour savoir quand l'utilisateur
             aura donné son consentement, ou bien si une erreur survînt
             */
            appConsent?.setOnPresentNoticeListener(object : OnPresentNoticeListener {
                override fun presentConsentError(error: Throwable?) {
                    /*
                     Une erreur s'est produite
                     */
                    removeCMPCallback()
                }

                override fun presentConsentGiven() {
                    /*
                    L'utilisateur a donné son consentement
                    */
                    removeCMPCallback()
                }
            })
            tryToDisplayCmpAndCheckUpdateIfNeeded()
        }
    }

    private fun removeCMPCallback() {
        /*
        Non obligatoire, mais cela permet d'éviter de garder une référence locale au callback.
        Bien entendu, tout dépend de l'implémentation faite sur votre projet.
        Exemple avec une SOP Activity, un singleton surveillé parc un flow, etc.
         */
        appConsent?.setOnPresentNoticeListener(null)
    }
}

Support visuel​

Voici divers exemple de rendu possibles lié à la configuration du SDK (la mise en évidence du bouton Accept All est configuré depuis le BO - voir le mode HighLight)

Mode vertical​
Exemple de rendu configuré dans l'exemple de code ci-dessus  Exemple de rendu avec les boutons alignés verticallement et la CMP en mode popup  Exemple de rendu avec l'alignement des boutons dépendant de l'orientation  

Mode horizontal​
Exemple de rendu configuré dans l'exemple de code ci-dessus   Exemple de rendu configuré dans l'exemple de code ci-dessus

3. Proposer à vos utilisateurs de consulter leur consentement​

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 {
            /*
             S'enregistre au callback de la CMP pour savoir quand l'utilisateur
             aura modifié son consentement, ou bien si une erreur survînt
             */
            AppConsentSDK.getInstance()
                ?.setOnPresentNoticeListener(object : OnPresentNoticeListener {
                    override fun presentConsentError(error: Throwable?) {
                        /*
                         Une erreur s'est produite
                         */
                        removeCMPCallback()
                    }

                    override fun presentConsentGiven() {
                        /*
                        L'utilisateur a modifié son consentement
                        */
                        removeCMPCallback()
                    }
                })
            /*
            Affiche la CMP pour permettre à vos utilisateurs de consulter leur consentement
            */
            val isCmpDisplayed =
                AppConsentSDK.getInstance()?.tryToDisplayNotice(force = true) ?: false
            if (false == isCmpDisplayed) {
                /*
                La CMP n'est pas initialisée (getInstance() return null), assurez vous que celle-ci
                est bien initialisé (voir 2. Créez l'instance de AppConsent).
                Vérifiez également que votre activity n'a pas été démarré dans un nouveau process
                (nouveau process, nouvelle stack mémoire, singleton non initialisé).
                 */
            }
        }
    }

    private fun removeCMPCallback() {
        /*
        Non obligatoire, mais cela permet d'éviter de garder une référence locale au callback.
        Bien entendu, tout dépend de l'implémentation faite sur votre projet.
        Exemple avec une SOP Activity, un singleton surveillé parc un flow, etc.
         */
        AppConsentSDK.getInstance()?.setOnPresentNoticeListener(null)
    }
}

4. Utilisation de l'objet appConsent​

  • Permet de savoir si l'utilisateur a donné son consentement
appConsent.consentGiven()

Returne true si le consentement a été donné, false sinon.

  • Consent listener
définir le listener lié au consentement utilisateur​

Lorsque l'utilisateur a terminé son parcours et donné son consentement, celui-ci permet d'être prévenu.

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

    override fun presentConsentError(error: Throwable?) {
        // ...
    }
})
Remove Listener​
appConsent.setOnPresentNoticeListener(null)
  • Essaye d'afficher la CMP

Il existe 2 modes d'affichages:

  1. Le premier qui s'exécute seulement si un consentement utilisateur est nécessaire.
  2. Le second qui est à utiliser, pour permettre à vos utilisateurs de consulter / modifier leur consentement (souvent utiliser depuis votre écran de paramétrage pour afficher la politique de vie privée de votre utilisateur)

Par défaut cette méthode essaye d'afficher la CMP. Elle essaye car, selon la région de vos utilisateurs (si aucun paramétrage n'est effectué via ACConfiguration pour forcer l'affichage) alors elle suivra ses contrôles et affichera la CMP que si nécessaire.



Elle s'affichera également si le consentement utilisateur n'a pas encore été donné ou si celui-ci doit être renouvellé.
// @return true si la notice s'affiche, false sinon
appConsent.tryToDisplayNotice(false) // affiche la CMP seulement si besoin
appConsent.tryToDisplayNotice(true) // force l'affichage de la CMP

Elle retourne 'true' si la CMP s'affiche, 'false' sinon

info

tryToDisplayNotice(force : Boolean) est une méthode qui vérifie seulement le cache de l'appareil. Voir checkForUpdate() pour vérifier si une mise à jour est nécessaire.

  • Consentable allowed
appConsent.consentableAllowed(1,0)

Retourne true si le consentable avec id = 1 et consentableType = 0 est autorisé, false sinon. Le id à passer est le iabId de votre purpose et le consentableType est le type, par exemple purpose = 0.

  • Stack Allowed
appConsent.stackAllowed(1)

Retourne true si la stack avec id = 1 est autorisée, false sinon.

  • Vendor allowed
appConsent.vendorAllowed(1)

Retourne true si le vendor avec id = 1 est autorisée, false sinon.

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

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

Définissez l’état des consentements, enregistrez-le et envoyez-le au serveur.

  • Check for update
appConsent.checkForUpdate({ isNeedToPresentTheCmp: Boolean ->
            // Votre Notice a été mise à jour, vous devez représenter la CMP à vos utilisateurs
            if (true == isNeedToPresentTheCmp) {
                /*
                Permet de supprimer localement l'ancien consentement utilisateur.
                Cette étape n'est pas obligatoire, mais elle permet d'éviter de refaire un appel réseau
                pour vérifier plus tard si la Notice a été mise à jour
                car plus aucuns consentement ne sera présent sur le device de l'utilisateur.
                 */
                appConsent.clearConsent()
                appConsent.tryToDisplayNotice(false)
            } else {
                /*
                La Notice est la même que lors de la dernière vérification
                (vous n'avez apporté aucunes modification depuis le board ou
                celle-ci n'a pas subit de mise à jour interne par nos soins;
                comme par exemple la mise à jour d'un vendor)
                 */
            }
        }) { _: Throwable? ->
            /*
             Une erreur s'est produite
             */
        }

Vérifiez si le consentement doit être mis à jour (nouvelle version de gvl, nouveaux consentants, mise à jour de votre Notice, nouveaux vendors, modification de la durée des consentements, etc.).

  • Clear consents
appConsent.clearConsent()

Supprime localement le consentement utilisateur, mais pas sur le serveur (cela permettra un nouvelle affichage de la CMP lors du prochain appel a tryToDisplayNotice(false) par exemple)

  • Set external data
DÉPRÉCIÉ

Cette méthode sera supprimé dans les prochaines release, utilisez setExternalIds(ids: Map<String, String>)

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

Permets de définir des Ids supplémentaires qui seront pris en compte lors de la validation du consentement utilisateur.

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

5. Récupérez vos consentements​

Vos consentements sont enregistrés dans SharedPreferences de votre application. Pour en savoir plus sur les clés utilisées pour sauvegarder vos consentements, veuillez vous référer à la documentation IAB.

Nous mettons également à dispositions une clé pour récupérer les Google Additional Consent IABTCF_AddtlConsent qui renvoie une String.

Dernière mise à jour le