Notre univers
Contenu

[Androïde] 1. consentmanager Intégration SDK

Sur ce document, vous trouverez des informations générales sur la façon d'intégrer notre SDK à votre projet. Pour plus de détails, veuillez vous référer à notre Référence de l'API Documentation.

Depuis la version 1.7.0, notre référentiel SDK a été déplacé vers le référentiel officiel Maven. Le guide de migration peut être trouvé ici. Trouver les versions natives du SDK compatibles ici.

1. Installation

Le plus consentmanager Le SDK pour les applications Android implémente et fournit des fonctionnalités pour informer l'utilisateur sur la protection des données et demander et recueillir le consentement de l'utilisateur. Il permet aux développeurs d'applications d'intégrer facilement le consentmanager service dans leur application.

Étapes – Niveau élevé

    1. Intégration et configuration:

      • Intégrez le SDK dans votre application.
      • Configurez les paramètres du SDK en fonction de vos besoins.
    2. Création d'une instance:

      • Au démarrage de l'application, créez une instance du CMPConsentTool classe. Cette instance gérera le processus de consentement.
    3. Initialisation du SDK:
      • Une fois l'instance prête, le SDK récupère automatiquement les informations nécessaires du consentmanager serveurs pour préparer son fonctionnement.
    4. Affichage de l'écran de consentement:

      • Le SDK affichera automatiquement l'écran de consentement si nécessaire lorsque le CMPConsentTool l'instance est créée.
    5. Traitement des données personnelles:

      • Une fois les consentements collectés, les informations sont stockées et sont disponibles pour interrogation via différentes propriétés et méthodes exposées par notre SDK. Vous aurez des informations sur les consentements rejetés ou acceptés, les fournisseurs, les objectifs, etc.

    En suivant ces étapes, vous vous assurez que votre application est conforme aux exigences de consentement et que le consentement de l'utilisateur est correctement géré et stocké.

Consent Manager Diagramme de séquence du SDK du fournisseur

Pour illustrer les étapes ci-dessus, vérifions dans le diagramme ci-dessous trois flux de séquence SDK possibles. 

1. Lors de la création d'une instance à l'aide de initialiser fonction, il y a deux résultats possibles. La première est lorsque l'API Consentmanger informe le SDK que la CMP ne s'ouvrira pas, ce qui déclenche le OnCmpNotOpenedCallbackOnCmpNotOpenedCallback. Le deuxième résultat est lorsque la couche de consentement s'ouvre, permettant à l'utilisateur d'interagir avec elle, et cela déclenche le SurOpenCallback. Une fois que l'utilisateur a donné son consentement et que celui-ci a été traité, le OnCmpCloseCallbackOnCmpCloseCallback est appelé.

S'il vous plaît noter que le SurErreurRappel est représenté par les flèches rouges en pointillés pour fournir des exemples d'erreurs pouvant survenir au cours du processus.

Initialiser-Cmp-Sequence-Diagram.png

2. Créer une instance et appeler le ouvrirAndCheckConsent les fonctions conduiront à un processus similaire. La différence est qu'en dissociant la création de l'instance et la vérification de l'API consentementmanger, vous obtenez la possibilité d'ajouter une logique métier et d'interagir avec l'API des bibliothèques.

3. Créer une instance et appeler le couche ouverte fonction ouvrira le calque sans vérifier le consentmanager, si c'est nécessaire. Si le consentement a déjà été donné, les options et les paramètres seront affichés à l'utilisateur. Le flux de processus ressemblera à ceci :

openlayer-Cmp-Sequence-Diagram-.png

Pour plus d'informations sur la présentation de la version du SDK et le journal des modifications, veuillez vous référer à ce lien.

Ajout de dépendance via Gradle

Ajoutez la dépendance à vos applications build.gradle. (Pour toujours obtenir la dernière version, utilisez le symbole + pour obtenir les mises à jour les plus récentes. Vous pouvez par exemple toujours obtenir les versions les plus récentes pour les mises à jour mineures via 1.x.+)

dependencies {
  implementation 'net.consentmanager.sdk:android:x.xx.x'
}

I

Ajout de dépendance via Maven

Ajoutez la dépendance à vos applications build.gradle. Pour toujours obtenir la dernière version de maven, vous pouvez utiliser différentes méthodes pour refuser la plage de versions. Pour vérifier les versions disponibles du SDK, veuillez vérifier ce lien. Pour plus d'informations, veuillez vous référer ici.

<dependency>
    <groupId>net.consentmanager.sdk</groupId>
    <artifactId>android</artifactId>
    <version>x.xx.x</version>
</dependency>

2. Initialisation du SDK

Permissions

Ce SDK nécessite les autorisations suivantes, veuillez vous assurer de les ajouter à votre AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.INTERNET" />

Initialisation du ConsentTool - automatiquement

Dans le démarrage de l'application (généralement le override onCreate() fonction), vous devez créer une instance de classe CMPConsentTool. le initialize() La fonction récupérera automatiquement les données nécessaires de notre serveur et déterminera si l'écran de consentement doit être affiché ou non. Si tel est le cas, le SDK affichera automatiquement l'écran de consentement à ce stade, collectera les données et fournira les données à l'application. L'instance peut ensuite être utilisée afin d'obtenir les détails du consentement du SDK afin de l'utiliser dans l'application. Exemple d'initialisation, en utilisant le comportement automatique du initialize() méthode:

Pour initialiser ConsentTool, accédez à votre classe ciblée et créez une instance de CMPConsentTool comme indiqué ci-dessous :

// Kotlin example of initialization of the consent layer
class CmpDemoActivity : FragmentActivity() {

    private lateinit var cmpManager: CmpManager

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        val config = CmpConfig.apply {
            id = "<YOUR-CONSENTMANAGER-APP-ID>" // example: b238acdf1a
            domain = "<YOUR-CONSENTMANAGER-APP-DOMAIN>" // example: delivery.consentmanager.net
            appName = "<YOUR-CONSENTMANAGER-APP-NAME>" // example: testApp
            language = "<YOUR-CONSENTMANAGER-APP-LANGUAGE>" // example: DE
        }
        
        cmpManager = CmpManager.createInstance(this, config)
        cmpManager.initialize(this)
    }
}
// Java example of initialization of the consent layer
public class CmpDemoActivity extends AppCompatActivity {

    private CmpManager cmpManager;

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        CmpConfig cmpConfig = CmpConfig.INSTANCE;
        cmpConfig.setId("<YOUR-CONSENTMANAGER-APP-ID>"); // example: a000aaaa1a
        cmpConfig.setDomain("<YOUR-CONSENTMANAGER-APP-DOMAIN>"); // example: delivery.consentmanager.net
        cmpConfig.setAppName("<YOUR-CONSENTMANAGER-APP-NAME>"); // example: testApp
        cmpConfig.setLanguage("<YOUR-CONSENTMANAGER-APP-LANGUAGE>"); // example: EN
        cmpConfig.setTimeout(4000);

        cmpManager = CmpManager.createInstance(this, cmpConfig);
        cmpManager.initialize(this)
    }
}

Afin de créer l'instance de CMPConsentTool, vous devez configurer l'instance. Vous devrez fournir le CODE-ID, le domaine du serveur, un nom d'application et une langue. Le CODE-ID et le domaine du serveur se trouvent dans votre consentmanager compte sous Menu> Obtenir le code. Le nom de l'application peut être utilisé pour distinguer différentes applications dans le consentmanager rapports. Pour la langue, vous pouvez utiliser une chaîne vide ("") pour la détection automatique ou un code de langue à 2 lettres ("EN", "DE", "FR" et ainsi de suite).

Initialisation du ConsentTool - manuellement

Le SDK offre, par souci de flexibilité, un moyen d'afficher manuellement la couche de consentement, comme illustré ci-dessous : 

        cmpManager.check({ isConsentRequired ->
            if (isConsentRequired) {
                // Consent is required, handle accordingly
                runOnUiThread {
                    // Update UI or show consent dialog
                    cmpManager.openLayer()
                }
            } else {
                // Consent is not required, proceed with application logic
            }
        }, isCached = true)

Création d'une mise en page personnalisée

Pour créer une mise en page personnalisée, vous pouvez utiliser le CmpUIConfig classe avec différentes options de style. Cette classe propose également des mises en page prédéfinies comme 

  • configurerHalfScreenBottom
  • configurerHalfScreenTop
  • configurerCenterScreen
  • configurerSmallCenterScreen
  • configurerLargeTopScreen
  • configurerLargeBottomScreen

Pour créer une mise en page personnalisée, le SDK CMP propose également différentes stratégies :

  • Fenêtre de dialogue
  • Fenêtre Popup
  • Fragment

Vous pouvez modifier la stratégie en définissant le paramètre UIConfig : 

CmpUIConfig.uiStrategy = CmpUIStrategy.DIALOG
CmpUIConfig.uiStrategy = CmpUIStrategy.POPUP
CmpUIConfig.uiStrategy = CmpUIStrategy.ACTIVITY
CmpUIConfig.uiStrategy = CmpUIStrategy.FRAGMENT

Nous recommandons d'utiliser une fenêtre contextuelle qui est également définie par défaut depuis la version 2.3.0

Deux paramètres importants détermineront le Apparaitre et Dialogue comportement. Dans le tableau ci-dessous, vous pouvez vérifier la relation entre les paramètres isFocusable et isOutsideTouchable

Comportement des popups
Paramètre isFocusable = true isFocusable = false
isOutsideTouchable =  true Rejette sur contact extérieur. Peut obtenir le focus pour les événements d’entrée. Rejette sur contact extérieur. N'obtient pas le focus et n'intercepte pas la saisie au clavier.
isOutsideTouchable = false Ne rejette pas sur contact extérieur. Peut obtenir le focus et intercepter les événements d’entrée. Ne rejette pas sur contact extérieur. N'obtient pas le focus et n'intercepte pas la saisie au clavier.

 

 

 

Comportement du dialogue
Paramètre isFocusable = true isFocusable = false
isOutsideTouchable =  true Rejette sur contact extérieur (setCanceledOnTouchOutside(true)). La boîte de dialogue est focalisable par défaut. La boîte de dialogue ne se ferme pas lors d'un contact extérieur et peut ne pas se comporter comme prévu car les boîtes de dialogue peuvent généralement être focalisées.
isOutsideTouchable = false Ne rejette pas sur contact extérieur (setCanceledOnTouchOutside(false)). La boîte de dialogue reste focalisable et peut intercepter les événements d'entrée. La boîte de dialogue ne se ferme pas lors d'un contact extérieur et peut ne pas se comporter comme prévu en raison du manque de focalisation.
Utiliser la stratégie Fragment
R.id.cmpContainer est un Framelayout qui pourrait ressembler à ceci dans le XML de présentation d'activité dans layout/{your_activity}.xml

<FrameLayout
    android:id="@+id/cmpContainer"
    android:layout_width="match_parent"
    android:layout_height="400dp"
    android:translationZ="90dp"
    app:layout_constraintTop_toTopOf="parent" />

3. Utilisation du SDK

Afin de vérifier si un fournisseur ou un objectif a son consentement, vous pouvez utiliser les deux méthodes:

if (cmpManager.hasPurposeConsent("52")) {
    if (cmpManager.hasVendorConsent("s26")) {
        // Add your logic here
    }
}

Les deux méthodes hasPurposeConsent et hasVendorConsent avoir deux paramètres, un obligatoire et un facultatif :

  • id - Chaîne de l'ID du fournisseur ou de l'objectif. Veuillez noter que les identifiants de fournisseurs peuvent avoir des formats différents ("123", "s123" et "c123"), veuillez vérifier auprès de Menu> Fournisseurs et Menu> Objectifs dans votre consentmanager compte.
  • isIABVendor / isIABPurpose (Facultatif) - Si le fournisseur ou l'objectif est un fournisseur/objectif qui suit la norme IAB TCF, vous devrez définir un vrai, sinon un faux.

N'oubliez pas: tous les fournisseurs qui n'appartiennent pas à l'IAB ont des ID commençant par un "s" ou "c" (par exemple, "s123"); les fournisseurs qui appartiennent à l'IAB ont des ID ne commençant pas par un «s» ou «c».

Réouverture de l'écran de consentement

Afin de permettre à l'utilisateur de modifier les choix, vous pouvez simplement appeler openConsentLayer():

cmpManager?.openConsentLayer(context)

Dans certains cas, une application native peut contenir des vues Web afin d'afficher certaines choses comme de la publicité ou du contenu. Afin de transmettre les informations de consentement du SDK à la vue Web, veuillez utiliser la fonction :

String consentData = cmpConsentTool?.exportCmpString();

Cela exportera les informations de consentement et toutes les autres données nécessaires au CMP. Vous pouvez ensuite transmettre ces informations au CMP qui se trouve dans votre vue Web en l'ajoutant à l'URL appelée dans la vue Web:

myWebView.loadURL("https://mywebsite.com/....#cmpimport=" + consentData);

Écouteurs d'événements personnalisés

Pour ajouter une logique de processus supplémentaire, vous pouvez utiliser des écouteurs d'événement. Les écouteurs d'événement suivants sont disponibles :

Prénom

Se produit

 

SurOpenCallback

Écouteur d'événement à l'ouverture du CMP

OncmpcloseCallback

Écouteur d'événement lorsque CMP est fermé

SurCMPNotOpenedCallback

Écouteur d'événement lorsque CMP n'a pas besoin d'être ouvert

SurErreurRappel

Écouteur d'événement lorsqu'il y a une erreur dans le processus de gestion des consentements.

OnButtonClickedCallback

Écouteur pour ButtonEvent

Autorisation d'importation/exportation

Pour importer ou exporter le consentement vous pouvez utiliser les fonctions exportCMPData() et importCMPData(). Vérifiez l'exemple ci-dessous : 

La chaîne de consentement que vous devez transmettre doit être encodée en base64.

Pour implémenter la fonctionnalité selon laquelle certains domaines sont sur liste blanche et, lorsqu'ils sont accessibles dans la WebView de la plate-forme de consentement (CMP), ne sont pas ouverts dans un navigateur externe comme Chrome mais dans la WebView elle-même, vous pouvez implémenter un mécanisme de rappel pour effectuer des actions personnalisées basées sur le domaine, comme l'ouverture d'une activité Android.

// apply the domains to be whitelisted
CmpConfig.apply {
            id = cmpId
            domain = cmpDomain
            appName = cmpAppName
            language = cmpLanguage
            domainWhitelist = cmpDomainWhitelist
        }


// implement the callback: CmpOnClickLinkCallback
    override fun onClickLink(url: String): Boolean {
        Log.d("CMP", url)
        // Business logic
        return true // return handleWebViewInteraction boolean
    }

Journal

Lorsque vous utilisez notre SDK Android, vous devrez peut-être déboguer ou analyser les informations du journal à diverses fins. Les journaux générés par notre SDK sont étiquetés avec « CMP », ce qui vous permet de filtrer et d'afficher facilement uniquement les journaux pertinents. Ce guide fournit des instructions étape par étape sur la façon d'accéder à ces journaux à l'aide de Logcat dans Android Studio.

Rechercher la balise : Dans la barre de recherche au-dessus des instructions du journal, saisissez CMP pour filtrer les journaux marqués avec "CMP".

Facultatif : activer le mode débogage

In CMPConfig, ensemble isDebugMode = true.

val config = CmpConfig.apply {
    // ... other settings
    isDebugMode = true
}
  • Active des journaux plus détaillés marqués avec « CMP ».
  • Utile pour le débogage et l'analyse.

Dépannage

Classe introuvable ou NoSuchMethodException :

ProGuard peut parfois masquer les noms de classe ou supprimer les méthodes référencées dynamiquement via la réflexion. Pour résoudre ce problème, vous devez spécifier les classes et méthodes qui doivent rester intactes dans le fichier de configuration ProGuard à l'aide du -keep Directive.

Exemple de configuration ProGuard pour conserver une classe spécifique et ses méthodes :

# Kotlin serialization looks up the generated serializer classes through a function on companion
# objects. The companions are looked up reflectively so we need to explicitly keep these functions.
-keepclasseswithmembers class **.*$Companion {
    kotlinx.serialization.KSerializer serializer(...);
}
# If a companion has the serializer function, keep the companion field on the original type so that
# the reflective lookup succeeds.
-if class **.*$Companion {
  kotlinx.serialization.KSerializer serializer(...);
}
-keepclassmembers class <1>.<2> {
  <1>.<2>$Companion Companion;
}

# If your project uses WebView with JS, uncomment the following
# and specify the fully qualified class name to the JavaScript interface
# class:
-keepclassmembers class * {
    @android.webkit.JavascriptInterface <methods>;
}

-keepattributes JavascriptInterface

-keepclassmembers class net.consentmanager.sdk.common.callbacks.* {
   public *;
}

-keepclassmembers class net.consentmanager.sdk.consentlayer.ui.consentLayer.CmpWebView {
   public *;
}

-keepclassmembers class net.consentmanager.sdk.consentlayer.ui.CmpLayerAppInterface {
   public *;
}
-keep class net.consentmanager.sdk.CMPConsentTool {
                                                      *;
                                                  }

-keepclassmembers class * {
    @android.webkit.JavascriptInterface <methods>;
}

-keepattributes JavascriptInterface

# Serializer for classes with named companion objects are retrieved using `getDeclaredClasses`.
# If you have any, uncomment and replace classes with those containing named companion objects.
#-keepattributes InnerClasses # Needed for `getDeclaredClasses`.
#-if @kotlinx.serialization.Serializable class
#com.example.myapplication.HasNamedCompanion, # <-- List serializable classes with named companions.
#com.example.myapplication.HasNamedCompanion2
#{
#    static **$* *;
#}
#-keepnames class <1>$$serializer { # -keepnames suffices; class is kept when serializer() is kept.
#    static <1>$$serializer INSTANCE;
#}

 

Retour en haut de la page