Info
Contenido

[Androide] 1. consentmanager Integración SDK

En este documento encontrará información general sobre cómo integrar nuestro SDK a su proyecto. Para obtener más detalles, consulte nuestra Referencia de la API documentación.

Desde la versión 1.7.0, nuestro repositorio de SDK se ha trasladado al repositorio oficial de Maven. La guía de migración se puede encontrar aquí. Encuentre las versiones nativas del SDK compatibles aquí.

1. Instalación

La consentmanager SDK para aplicaciones de Android implementa y proporciona funcionalidad para informar al usuario sobre la protección de datos y solicitar y obtener el consentimiento del usuario. Permite a los desarrolladores de aplicaciones integrar fácilmente consentmanager servicio en su aplicación.

Pasos - Nivel alto

    1. Integración y Configuración:

      • Integre el SDK en su aplicación.
      • Configure los ajustes del SDK según sus necesidades.
    2. Creando una instancia:

      • Al iniciar la aplicación, cree una instancia de CMPConsentTool clase. Esta instancia se encargará del proceso de consentimiento.
    3. Inicialización del SDK:
      • Una vez que la instancia está lista, el SDK recupera automáticamente la información necesaria del consentmanager servidores para prepararse para su funcionamiento.
    4. Mostrar la pantalla de consentimiento:

      • El SDK mostrará automáticamente la pantalla de consentimiento si es necesario cuando el CMPConsentTool Se crea la instancia.
    5. Procesamiento de datos personales:

      • Una vez que se recopilan los consentimientos, la información se almacena y está disponible para consultar a través de diferentes propiedades y métodos expuestos por nuestro SDK. Dispondrás de información sobre consentimientos rechazados o aceptados, proveedores, finalidades, etc.

    Al seguir estos pasos, se asegura de que su aplicación cumpla con los requisitos de consentimiento y que el consentimiento del usuario se administre y almacene adecuadamente.

Consent Manager Diagrama de secuencia del SDK del proveedor

Para ilustrar los pasos anteriores, revisemos en el diagrama siguiente tres posibles flujos de secuencia del SDK. 

1. Al crear una instancia usando el inicializar función, hay dos resultados posibles. La primera es cuando la API de consentmanger informa al SDK que el CMP no se abrirá, lo que desencadena el OnCmpNotOpenedDevolución de llamada. El segundo resultado es cuando se abre la capa de consentimiento, lo que permite al usuario interactuar con ella, y esto desencadena la Al abrir devolución de llamada. Una vez que el usuario da su consentimiento y se procesa el consentimiento, el OnCmpCloseDevolución de llamada se llama.

Tenga en cuenta que la Devolución de llamada en error está representado por las líneas de flechas discontinuas rojas para proporcionar ejemplos de cuándo pueden ocurrir errores durante el proceso.

Inicializar-Cmp-Sequence-Diagram.png

2. Creando una instancia y llamando al abrir y comprobar el consentimiento funciones conducirán a un proceso similar. La diferencia es que al desacoplar la creación de la instancia y la verificación de la API de consentmanger, obtiene la capacidad de agregar lógica empresarial e interactuar con la API de las bibliotecas.

3. Creando una instancia y llamando al capa abierta La función abrirá la capa sin verificar el consentmanager, si es necesario. Si ya se ha dado el consentimiento, se mostrarán las opciones y configuraciones al usuario. El flujo del proceso se verá así:

openlayer-Cmp-Secuencia-Diagrama-.png

Para obtener más información sobre nuestra descripción general de la versión del SDK y el registro de cambios, consulte este enlace.

Agregar dependencia a través de Gradle

Agregue la dependencia a sus aplicaciones build.gradle. (Para obtener siempre la última versión, utilice el símbolo + para obtener las actualizaciones más recientes. Por ejemplo, siempre puede obtener las versiones más recientes para actualizaciones menores hasta 1.x.+)

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

I

Agregar dependencia a través de Maven

Agregue la dependencia a sus aplicaciones build.gradle. Para obtener siempre la última versión en maven, puede utilizar diferentes métodos para rechazar el rango de versiones. Para comprobar las versiones disponibles del SDK, consulte este enlace. Para obtener más información, consulte aquí.

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

2. Inicializando el SDK

Permisos

Este SDK requiere los siguientes permisos, asegúrese de agregarlos a su AndroidManifest.xml:

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

Inicializando ConsentTool - Automáticamente

Dentro del inicio de la aplicación (normalmente el habitual override onCreate() función), debes crear una instancia de clase CMPConsentTool. los initialize() La función obtendrá automáticamente los datos necesarios de nuestro servidor y determinará si es necesario mostrar la pantalla de consentimiento o no. Si es así, el SDK mostrará automáticamente la pantalla de consentimiento en este punto, recopilará los datos y los proporcionará a la aplicación. Luego, la instancia se puede usar para obtener detalles de consentimiento del SDK para usarla en la aplicación. Ejemplo de inicialización, usando el comportamiento automático del initialize() método:

Para inicializar ConsentTool, vaya a su clase de destino y cree una instancia de CMPConsentTool como se muestra a continuación:

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

Para crear la instancia de CMPConsentTool, necesita configurar la instancia. Deberá proporcionar el CODE-ID, el dominio del servidor, el nombre de la aplicación y el idioma. El CODE-ID y el dominio del servidor se pueden encontrar en su consentmanager cuenta bajo Menú> Obtener código. El nombre de la aplicación se puede usar para distinguir diferentes aplicaciones en consentmanager informes Para el idioma, puede usar una cadena vacía ("") para la detección automática o un código de idioma de 2 letras ("EN", "DE", "FR", etc.).

Inicialización de ConsentTool: manualmente

El SDK ofrece, en aras de la flexibilidad, una forma de mostrar manualmente la capa de consentimiento, como se muestra a continuación: 

        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)

Crear un diseño personalizado

Para crear un diseño personalizado, puede utilizar el CmpUIConfig Clase con diferentes opciones de estilo. Esta clase también ofrece algunos diseños preestablecidos como 

  • configurar media pantalla inferior
  • configurarHalfScreenTop
  • configurarCenterScreen
  • configurarSmallCenterScreen
  • configurarLargeTopScreen
  • configurar pantalla inferior grande

Para crear un diseño personalizado, CMP SDK también ofrece diferentes estrategias:

  • Ventana de diálogo
  • Ventana emergente
  • fragmento

Puede cambiar la estrategia configurando el parámetro UIConfig: 

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

Recomendamos utilizar una ventana emergente que también está configurada como predeterminada desde la versión 2.3.0.

Dos parámetros importantes determinarán la Emergente y Diálogo comportamiento. En la siguiente tabla, puede comprobar la relación entre los parámetros. isFocusable y isOutsideTouchable

Comportamiento emergente
Parámetro isFocusable = true isFocusable = false
isOutsideTouchable =  true Se despide al tocar el exterior. Puede ganar foco para eventos de entrada. Se despide al tocar el exterior. No obtiene enfoque ni intercepta la entrada del teclado.
isOutsideTouchable = false No se descarta al contacto exterior. Puede ganar foco e interceptar eventos de entrada. No se descarta al contacto exterior. No obtiene enfoque ni intercepta la entrada del teclado.

 

 

 

Comportamiento del diálogo
Parámetro isFocusable = true isFocusable = false
isOutsideTouchable =  true Descarta al tocar el exterior (setCanceledOnTouchOutside(true)). El diálogo se puede enfocar de forma predeterminada. El diálogo no se descarta al tocarlo desde fuera y es posible que no se comporte como se espera, ya que los diálogos normalmente se pueden enfocar.
isOutsideTouchable = false No se descarta al tocar el exterior (setCanceledOnTouchOutside(false)). El diálogo sigue siendo enfocable y puede interceptar eventos de entrada. El diálogo no se descarta al tocar el exterior y es posible que no se comporte como se esperaba debido a la falta de capacidad de enfoque.
Usando la estrategia Fragmento
R.id.cmpContainer es un Framelayout que podría verse así en el xml de diseño de actividad en diseño/{tu_actividad}.xml

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

3. Usando el SDK

Para verificar si un proveedor o propósito tiene consentimiento, puede usar los dos métodos:

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

Ambos métodos hasPurposeConsent y hasVendorConsent Tiene dos parámetros, uno obligatorio y otro opcional:

  • id - Cadena del proveedor o ID del propósito. Tenga en cuenta que los ID de proveedor pueden tener diferentes formatos ("123", "s123" y "c123"), verifique con Menú> Proveedores y Menú> Propósitos en tu consentmanager cuenta.
  • isIABVendor / isIABPurpose (Opcional): si el proveedor o el propósito es un proveedor/propósito que sigue el estándar IAB TCF, deberá establecer un valor verdadero; de lo contrario, un valor falso.

Recuerde: Todos los proveedores que no pertenecen al IAB tienen ID que comienzan con una "s" o "c" (por ejemplo, "s123"); Los proveedores que pertenecen a la IAB tienen ID que no comienzan con una "s" o "c".

Reabrir la pantalla de consentimiento

Para permitir que el usuario cambie las opciones, simplemente puede llamar openConsentLayer():

cmpManager?.openConsentLayer(context)

En algunos casos, una aplicación nativa puede contener vistas web para mostrar ciertas cosas como publicidad o contenido. Para transmitir la información de consentimiento del SDK a la vista web, utilice la función:

String consentData = cmpConsentTool?.exportCmpString();

Esto exportará la información de consentimiento y todos los datos adicionales que necesita el CMP. Luego puede pasar esta información al CMP que está en su vista web agregándola a la URL que se llama en la vista web:

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

Oyentes de eventos personalizados

Para agregar una lógica de proceso adicional, puede utilizar los detectores de eventos. Los siguientes detectores de eventos están disponibles:

Nombre Completo

ocurre

 

Al abrir devolución de llamada

Oyente de evento cuando se abrió CMP

OnCMPCoseCallback

Oyente de evento cuando CMP está cerrado

OnCMPNotOpenedDevolución de llamada

Oyente para eventos cuando no es necesario abrir CMP

Devolución de llamada en error

Listener for Event cuando hay un error en el proceso de gestión de consentimiento.

En botón hecho clic en devolución de llamada

Oyente de ButtonEvent

Consentimiento de importación/exportación

Para importar o exportar el consentimiento puede utilizar las funciones exportCMPData() y importCMPData(). Mira el ejemplo a continuación: 

La cadena de consentimiento que necesita pasar debe estar codificada en base64.

Para implementar la funcionalidad donde ciertos dominios están en la lista blanca y, cuando se accede a ellos dentro de la plataforma de consentimiento (CMP) WebView, no se abren en un navegador externo como Chrome sino dentro del propio WebView, puede implementar un mecanismo de devolución de llamada para realizar acciones personalizadas basadas en el dominio, como abrir una actividad de 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
    }

Inicio de sesión

Al utilizar nuestro SDK de Android, es posible que necesite depurar o analizar información de registro para diversos fines. Los registros generados por nuestro SDK están etiquetados con "CMP", lo que le permite filtrar y ver fácilmente solo los registros relevantes. Esta guía proporciona instrucciones paso a paso sobre cómo acceder a estos registros usando Logcat en Android Studio.

Busque la etiqueta: En la barra de búsqueda encima de las declaraciones de registro, escriba CMP para filtrar los registros etiquetados con "CMP".

Opcional: habilitar el modo de depuración

In CMPConfigestablecer isDebugMode = true.

val config = CmpConfig.apply {
    // ... other settings
    isDebugMode = true
}
  • Habilita registros más detallados etiquetados con "CMP".
  • Útil para depuración y análisis.

Solucionando Problemas

Clase no encontrada o NoSuchMethodException:

A veces, ProGuard puede ofuscar nombres de clases o eliminar métodos a los que se hace referencia dinámicamente mediante reflexión. Para solucionar este problema, debe especificar las clases y métodos que deben mantenerse intactos en el archivo de configuración de ProGuard usando el -keep Directiva.

Ejemplo de configuración de ProGuard para mantener una clase específica y sus métodos:

# 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;
#}

 

Volver