[Android] 0. Guía de migración

Esta guía le ayudará a migrar de la versión anterior del SDK de CMP a la versión actual. Cubriremos los cambios en los nombres de los métodos, los parámetros y las funciones nuevas o en desuso. Para ver ejemplos de aplicaciones de demostración, consulte este enlaceHay dos carpetas, una con una aplicación de demostración completamente desarrollada en Java, que incluye un contenedor para Java llamado JavaCMPManager Otro completamente desarrollado en Kotlin. 

Tenga en cuenta que esta versión del SDK de CMP se reconstruyó completamente desde cero, por lo que representa una cambio importante y revolucionario, ya que se cambiaron el nombre de todos los métodos y de las firmas, y ahora también se ofrecen devoluciones de llamadas a casi todos los métodos. En todos los casos, deberá modificar su código y actualizar sus dependencias para garantizar que su aplicación móvil funcione como se espera. Además, vale la pena mencionar que Se borrarán todos los datos que la versión anterior de nuestro SDK conservaba en los dispositivos de los usuarios., lo que obligará a la aplicación a volver a mostrar la capa de consentimiento.

Repositorios

Tenga en cuenta que todos nuestros repositorios cambiaron para el SDK de Android. Siga las instrucciones a continuación para averiguar dónde apuntar su administrador de dependencias. 

Maven

En su archivo Gradle, reemplace la línea anterior por la siguiente:

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

Después de cambiar, sincronice su proyecto. 

Puntos clave de migración

1. Patrón de delegado: En lugar de oyentes individuales, la nueva versión utiliza un único protocolo de delegado (CMPManagerDelegate) para gestionar eventos. Contiene 4 eventos principales:
   1. didReceiveConsent(consent: String, jsonObject: Map<String, Any>)
      Esto se activa cuando la capa de consentimiento se cerró después de que el usuario actualizó sus consentimientos O cuando se invocan métodos que provocan cambios en los consentimientos, como acceptAll, rejectAll, acceptVendors, rejectVendors, etc. Significa que el usuario aceptó o rechazó algunos o todos los consentimientos, y que estos se guardaron correctamente en el dispositivo.
   2. didShowConsentLayer
      Esto se activa cuando se muestra realmente la capa de consentimiento. Significa que no había un consentimiento válido en el dispositivo, por lo que se debe recopilar uno nuevo.
   3. didCloseConsentLayer
      Esto se activa cuando el SDK verificó la necesidad de un consentimiento, pero no fue necesario y la capa no se mostró. Significa que ya existe uno válido en el dispositivo, por lo que no es necesario uno nuevo y la capa de consentimiento no se mostrará.
   4. didReceiveError
      Esto se activa cuando la operación del SDK ha generado algún error.
2. Manejadores de finalización: Muchos métodos ahora incluyen controladores de finalización para operaciones asincrónicas. Actualice su código para manejar estas devoluciones de llamadas de manera adecuada.
3. Cadena de consentimiento: Use exportCMPInfo() en lugar de getConsentString() para recuperar la información del consentimiento.
4. Consentimientos del proveedor y finalidad: Los métodos para obtener los consentimientos de los proveedores y de los propósitos ahora devuelven matrices de identificadores. Es posible que deba ajustar su lógica para manejar estas matrices.
5. Cadena de privacidad de EE. UU.: El getUSPrivacyString() El método ha quedado obsoleto. Si lo utilizaba para cumplir con la CCPA, tenga en cuenta que este método ya no está disponible.
6. Comprobación del requisito de consentimiento: Usa el nuevo checkAndOpen(completion:) método para determinar automáticamente si es necesario el consentimiento antes de mostrar la capa de consentimiento.

Cambios en métodos y firmas

Inicialización

• Old: CmpManager.initialize(context: Context, cmpConfig: CmpConfig)
• Nuevo: CmpManager.createInstance(context: Context, cmpConfig: CmpConfig)

Establecer la configuración de la interfaz de usuario

• Old: .withCmpViewControllerConfigurationBlock { ... }
• Nuevo: no se proporciona la opción, pero puede crear una actividad contenedora y controlar el ciclo de vida y la apariencia en su extremo del código.

Comprobación del consentimiento

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

Comprobación y apertura de la capa de consentimiento si es necesario

• Old: checkAndOpenConsentLayer()
• Nuevo: checkAndOpen(completion: (Error?) -> Void)

Abrir capa de consentimiento

• Old: openConsentLayer()
• Nuevo: forceOpen(completion: (Result<Unit>) -> Unit)

Aceptar todos los consentimientos

• Old: acceptAll(callback: ConsentCallback)
• Nuevo: cceptAll(completion: (Result<Unit>) -> Unit)

Rechazar todos los consentimientos

• Old: rejectAll(onFinish: () -> Unit)
• Nuevo: rejectAll(completion: (Result<Unit>) -> Unit)

Habilitar propósitos

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

Deshabilitar propósitos

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

Habilitar proveedores

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

Deshabilitar proveedores

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

Obtener todos los propósitos

• Old: getAllPurposes(): List<String>
• Nuevo: getAllPurposesIDs(): List<String>

Obtener propósitos habilitados

• Old: getEnabledPurposes(): List<String>
• Nuevo: getUserStatus(): UserConsentStatus

Obtener todos los proveedores

• Old: getAllVendors(): List<String>
• Nuevo: getUserStatus(): UserConsentStatus

Obtener proveedores habilitados

• Old: getEnabledVendors(): List<String>
• Nuevo: getUserStatus(): UserConsentStatus

Verificar el consentimiento de propósito

• Old: hasPurposeConsent(String): Boolean
• Nuevo: getStatusForPurpose(id: String): ConsentStatus

Verificar el consentimiento del proveedor

• Old: hasVendorConsent(String): Boolean
• Nuevo: getStatusForVendor(id: String): ConsentStatus

Exportar cadena CMP

• Old: exportCmpString() : String
• Nuevo: exportCMPInfo(): String

Importar cadena CMP

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

Restablecer datos de consentimiento

• Old: reset()
• Nuevo: resetConsentManagementData(completion: (Result<Unit>) -> Unit)

Cómo gestionar el estado del modo de consentimiento de Google

• Old: withGoogleAnalyticsCallback(analyticsListener: CmpGoogleAnalyticsInterface)
• Nuevo: getGoogleConsentModeStatus

Cómo manejar la devolución de llamada onLinkClick

• Antigua: La versión 2 solía tener una función de lista blanca. En la versión actual, el proceso se ha simplificado y el usuario tiene control total sobre el comportamiento según la URL devuelta por el método.

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

• Nuevo: El usuario tiene control total sobre el comportamiento a seguir según la URL. Por lo tanto, las URL previamente permitidas deben migrarse al método de devolución de llamada.

        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étodos obsoletos:

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

Ejemplos de migración

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

    }
}