[Android] 0. Guide de migration

Ce guide vous aidera à migrer de la version précédente du SDK CMP vers la version actuelle. Nous aborderons les modifications apportées aux noms de méthodes, aux paramètres et aux fonctionnalités nouvelles ou obsolètes. Pour des exemples d'applications de démonstration, veuillez consulter ce lienIl y a deux dossiers, l'un avec une application de démonstration entièrement développée en Java, incluant un wrapper pour Java appelé JavaCMPManager un autre entièrement développé en Kotlin. 

Veuillez noter que cette version du SDK CMP a été entièrement reconstruite à partir de zéro et représente donc une changement majeur de rupture, comme toutes les méthodes ont été renommées, tout comme les signatures, offrant désormais également des rappels à presque toutes les méthodes. Dans tous les cas, vous devrez modifier votre code et mettre à jour vos dépendances pour vous assurer que votre application mobile fonctionne comme prévu. De plus, il convient de mentionner que toutes les données conservées par la version précédente de notre SDK sur les appareils des utilisateurs seront effacées, ce qui forcera l'application à réafficher la couche de consentement.

Dépôts

Veuillez noter que tous nos référentiels ont été modifiés pour le SDK Android. Suivez les instructions ci-dessous pour savoir où pointer votre gestionnaire de dépendances. 

Maven

Dans votre fichier Gradle, remplacez la ligne précédente par celle ci-dessous :

implementation("net.consentmanager.sdkv3:cmsdkv3:3.2.0")

Après avoir modifié, synchronisez votre projet. 

Principaux points de migration

1. Modèle de délégué : Au lieu d'écouteurs individuels, la nouvelle version utilise un protocole de délégué unique (CMPManagerDelegate) pour gérer les événements. Il contient 4 événements principaux :
   1. didReceiveConsent(consent: String, jsonObject: Map<String, Any>)
      Cela se déclenche lorsque la couche de consentement a été fermée après que l'utilisateur a mis à jour ses consentements OU lors de l'appel de méthodes qui provoquent des modifications dans les consentements, comme acceptAll, rejectAll, acceptVendors, rejectVendors, etc. Cela signifie que l'utilisateur a accepté ou rejeté certains des consentements, et que ceux-ci ont été correctement enregistrés dans l'appareil.
   2. didShowConsentLayer
      Cela se déclenche lorsque la couche de consentement a été effectivement affichée. Cela signifie qu'aucun consentement n'était valide sur l'appareil, il faut donc en collecter un nouveau.
   3. didCloseConsentLayer
      Cela se produit lorsque le SDK a vérifié la nécessité d'un consentement, mais que celui-ci n'était pas nécessaire et que la couche n'était pas affichée. Cela signifie qu'il existe déjà une couche valide dans l'appareil, donc une nouvelle couche n'est pas nécessaire et la couche de consentement ne s'affichera pas.
   4. didReceiveError
      Cela est déclenché lorsque l’opération SDK a généré une erreur.
2. Gestionnaires d'achèvement : De nombreuses méthodes incluent désormais des gestionnaires de complétion pour les opérations asynchrones. Mettez à jour votre code pour gérer ces rappels de manière appropriée.
3. Chaîne de consentement : Utilisez exportCMPInfo() au lieu de getConsentString() pour récupérer les informations de consentement.
4. Consentements du fournisseur et de l'objectif : Les méthodes permettant d'obtenir les consentements des fournisseurs et des objectifs renvoient désormais des tableaux d'identifiants. Vous devrez peut-être ajuster votre logique pour gérer ces tableaux.
5. Chaîne de confidentialité américaine : Vue d'ensemble getUSPrivacyString() La méthode est obsolète. Si vous l'utilisiez pour la conformité CCPA, veuillez noter que cette méthode n'est plus disponible.
6. Vérification des exigences de consentement : Utilisez le nouveau checkAndOpen(completion:) méthode permettant de déterminer automatiquement si le consentement est nécessaire avant d'afficher la couche de consentement.

Modifications des méthodes et des signatures

Initialisation

• Vieux: CmpManager.initialize(context: Context, cmpConfig: CmpConfig)
• Nouveau: CmpManager.createInstance(context: Context, cmpConfig: CmpConfig)

Définir la configuration de l'interface utilisateur

• Vieux: .withCmpViewControllerConfigurationBlock { ... }
• Nouveau : l’option n’est pas fournie, mais vous pouvez créer une activité wrapper et contrôler le cycle de vie et l’apparence de votre côté du code.

Vérification du consentement

• Vieux: check({ ... }, isCached: Bool),
• Nouveau: checkAndOpen(completion: (Error?) -> Void)

Vérification et ouverture de la couche de consentement si nécessaire

• Vieux: checkAndOpenConsentLayer()
• Nouveau: checkAndOpen(completion: (Error?) -> Void)

Ouvrir la couche de consentement

• Vieux: openConsentLayer()
• Nouveau: forceOpen(completion: (Result<Unit>) -> Unit)

Accepter tous les consentements

• Vieux: acceptAll(callback: ConsentCallback)
• Nouveau: cceptAll(completion: (Result<Unit>) -> Unit)

Rejeter tous les consentements

• Vieux: rejectAll(onFinish: () -> Unit)
• Nouveau: rejectAll(completion: (Result<Unit>) -> Unit)

Activer les objectifs

• Vieux: enablePurposeList(purposes: List<String>, updateVendor: Boolean, onConsentReceivedCallback: OnConsentReceivedCallback?)
• Nouveau: acceptPurposes(purposes: List<String>, updatePurpose: Boolean, completion: (Result<Unit>) -> Unit)

Désactiver les fins

• Vieux: disablePurposeList(purposes: List<String>, updateVendor: Boolean, onConsentReceivedCallback: OnConsentReceivedCallback?)
• Nouveau: rejectPurposes(purposes: List<String>, updateVendor: Boolean, completion: (Result<Unit>) -> Unit)

Activer les fournisseurs

• Vieux: enableVendorList(vendors: List<String>, onConsentReceivedCallback: OnConsentReceivedCallback?)
• Nouveau: acceptVendors(vendors: List<String>, completion: (Result<Unit>) -> Unit)

Désactiver les fournisseurs

• Vieux: disableVendorList(vendors: List<String>, onConsentReceivedCallback: OnConsentReceivedCallback?)
• Nouveau: rejectVendors(vendors: List<String>, completion: (Result<Unit>) -> Unit)

Obtenez tous les objectifs

• Vieux: getAllPurposes(): List<String>
• Nouveau: getAllPurposesIDs(): List<String>

Obtenir des objectifs activés

• Vieux: getEnabledPurposes(): List<String>
• Nouveau: getUserStatus(): UserConsentStatus

Obtenir tous les fournisseurs

• Vieux: getAllVendors(): List<String>
• Nouveau: getUserStatus(): UserConsentStatus

Obtenez des fournisseurs activés

• Vieux: getEnabledVendors(): List<String>
• Nouveau: getUserStatus(): UserConsentStatus

Vérifier le consentement à l'objectif

• Vieux: hasPurposeConsent(String): Boolean
• Nouveau: getStatusForPurpose(id: String): ConsentStatus

Vérifier le consentement du fournisseur

• Vieux: hasVendorConsent(String): Boolean
• Nouveau: getStatusForVendor(id: String): ConsentStatus

Exporter la chaîne CMP

• Vieux: exportCmpString() : String
• Nouveau: exportCMPInfo(): String

Importer la chaîne CMP

• Vieux: importCmpString(consentString: String, completionHandler: ((Error?) -> Unit)?)
• Nouveau: importCMPInfo(cmpString: String, completion: (Result<Unit>) -> Unit)

Réinitialiser les données de consentement

• Vieux: reset()
• Nouveau: resetConsentManagementData(completion: (Result<Unit>) -> Unit)

Gestion du statut du mode consentement de Google

• Vieux: withGoogleAnalyticsCallback(analyticsListener: CmpGoogleAnalyticsInterface)
• Nouveau: getGoogleConsentModeStatus

Gestion du rappel onLinkClick

• Ancienne version : la version 2 disposait auparavant d'une fonctionnalité de liste blanche. Dans la version actuelle, le processus a été simplifié et l'utilisateur a un contrôle total sur le comportement à adopter en fonction de l'URL renvoyée par la méthode.

cmpConfig.domainWhitelist = ["add your domains to be whitelisted"]

cmpManager.withOnCmpLinkClickListener({ url, decisionHandler in
//check URL and add the nav action
decisionHandler!.pointee = WKNavigationActionPolicy.allow
decisionHandler!.pointee = WKNavigationActionPolicy.cancel
// return shouldCloseWebView (true) or stay open (false)
return true
})

• Nouveau : L'utilisateur a un contrôle total sur le comportement à adopter en fonction de l'URL. Ainsi, les URL précédemment autorisées doivent être migrées vers la méthode de rappel.

        cmpManager.setOnClickLinkCallback { url ->
            if (url.contains("google.com")) {
                // Open Google URLs in external browser
                try {
                    startActivity(Intent(Intent.ACTION_VIEW, url.toUri()))
                    true // Return true to indicate we handled the URL
                } catch (e: Exception) {
                    Log.e("DemoApp", "Error opening URL: $url", e)
                    false
                }
            } else {
                // Let other URLs load in the WebView
                false
            }
        }

Méthodes déconseillées :

• checkIfConsentIsRequired(completion: @escaping (Bool) -> Void)

• hasUserChoice() -> Bool

• hasPurposeConsent(id: String) -> Bool

• hasVendorConsent(id: String) -> Bool

• openConsentLayer(completion: @escaping (NSError?) -> Void)

• getAllPurposesIDs() -> [String]

• getEnabledPurposesIDs() -> [String]

• getDisabledPurposesIDs() -> [String]

• getAllVendorsIDs() -> [String]

• getEnabledVendorsIDs() -> [String]

• getDisabledVendorsIDs() -> [String]

• getUSPrivacyString()
• calledThisDay(): Boolean
• getConsentstring(): String
• getGoogleACString(): String
• getUSPrivacyString(): String
• initialize(context: Context, cmpConfig: CmpConfig)
• setCallbacks(...)
• withGoogleAnalyticsCallback(analyticsListener: CmpGoogleAnalyticsInterface)

Exemples de migration

Kotlin

// ============================================
// Previous versions
// ============================================

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)
    }
}
// ============================================
// SDK v3 implementation
// ============================================
                                           
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()

        val urlConfig = UrlConfig(
            id = "09cb5dca91e6b",
            domain = "delivery.consentmanager.net",
            language = "EN",
            appName = "CMDemoAppKotlin"
        )

        // This UI Config for Android is limited, but you have the option to create an activity wrapper
        // to have full control over the appearance and the position
        val webViewConfig = ConsentLayerUIConfig(
            position = ConsentLayerUIConfig.Position.FULL_SCREEN, // that's the only position available for Android
            backgroundStyle = ConsentLayerUIConfig.BackgroundStyle.dimmed(Color.BLACK, 0.5f),
            cornerRadius = 10f,
            respectsSafeArea = true,
            isCancelable = false
        )

        cmpManager = CMPManager.getInstance(
            context = this,
            urlConfig = urlConfig,
            webViewConfig = webViewConfig,
            delegate = this
        )

        cmpManager.setActivity(this)

        checkAndOpen()
    }

    private fun checkAndOpenConsentLayer() {
        cmpManager.checkWithServerAndOpenIfNecessary { result ->
            result.onSuccess {
                showCMPDemoScreen()
            }.onFailure { error ->
                Log.e("DemoApp", "Check and open consent layer failed with error: $error")
            }
        }
    }

    private fun showCMPDemoScreen() {
        setContent {
            MaterialTheme {
                Surface(
                    modifier = Modifier.fillMaxSize(),
                    color = MaterialTheme.colorScheme.background
                ) {
                    CMPDemoScreen(cmpManager)
                }
            }
        }
    }

    override fun onConfigurationChanged(newConfig: Configuration) {
        Log.d("CMP DemoApp", "Configuration changed")
        super.onConfigurationChanged(newConfig)
        cmpManager.onApplicationResume()
    }

    override fun onPause() {
        Log.d("CMP DemoApp", "Activity paused")
        super.onPause()
        cmpManager.onApplicationPause()
    }

    override fun onDestroy() {
        Log.d("CMP DemoApp", "Activity destroyed")
        super.onDestroy()
        cmpManager.onActivityDestroyed()
    }

    override fun didReceiveConsent(consent: String, jsonObject: Map<String, Any>) {
        Log.d("CMP DemoApp", "Consent Layer successfully received consent message.")
        runOnUiThread {
            showCMPDemoScreen()
        }
    }

    override fun didShowConsentLayer() {
        Log.d("CMP DemoApp", "Consent Layer open message received.")
    }

    override fun didCloseConsentLayer() {
        Log.d("CMP DemoApp", "Consent Layer close message received.")
        runOnUiThread {
            showCMPDemoScreen()
        }
    }

    override fun didReceiveError(error: String) {
        Log.e("CMP DemoApp", "SDK error: $error")
    }
}

Java 

// ===================================================
// Previuous versions
// ===================================================

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)
    }
}

// ===========================================
// SDK v3 implementation
// ===========================================

    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_cmp_demo);

        UrlConfig urlConfig = new UrlConfig(
                "09cb5dca91e6b",
                "delivery.consentmanager.net",
                "EN",
                "CMDemoAppJava"
        );

      // This UI Config for Android is limited, but you have the option to create an activity wrapper
      // to have full control over the appearance and the position

        ConsentLayerUIConfig webViewConfig = new ConsentLayerUIConfig(
                ConsentLayerUIConfig.Position.FULL_SCREEN,
                ConsentLayerUIConfig.BackgroundStyle.dimmed(Color.BLACK, 0.5f),
                10f,
                true,
                false
        );

        JavaCMPManager cmpManager = JavaCMPManager.getInstance(this, urlConfig, webViewConfig, this);
        cmpManager.setActivity(this);

        cmpManager.checkAndOpen(result -> {
            if (result.isSuccess()) {
            } else {
                Log.e("JavaDemoAp", "Initialize method failed with error: " + result.exceptionOrNull());
            }
            return null;
        });
    }

    private void showCMPDemoScreen() {
        Intent intent = new Intent(this, CMPDemoActivity.class);
        startActivity(intent);
        finish();
    }

    @Override
    public void didShowConsentLayer() {
        Log.d("CMP JavaDemoAp", "Consent Layer open message received.");
    }

    @Override
    public void didCloseConsentLayer() {
        Log.d("CMP JavaDemoAp", "Consent Layer close message received.");
    }

    @Override
    public void didReceiveError(@NonNull String error) {
        Log.e("CMP JavaDemoAp", "SDK error: " + error);
    }

    @Override
    public void didReceiveConsent(@NonNull String consent, @NonNull Map<String, Any> jsonObject) {
        Log.d("CMP JavaDemoAp", "Consent received: " + consent);
        runOnUiThread(this::showCMPDemoScreen);
    }

    @Override
    public void onPointerCaptureChanged(boolean hasCapture) {
        super.onPointerCaptureChanged(hasCapture);
    }

    @Override
    public void addMenuProvider(@NonNull MenuProvider provider, @NonNull LifecycleOwner owner, @NonNull Lifecycle.State state) {

    }
}