[Androide] 1. consentmanager Integración SDK

Hemos actualizado nuestro SDK. Utilice el SDK v3: https://help.consentmanager.net/books/cmp/page/android-1-consentmanager-sdk-integration-398

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. Para ver nuestra aplicación de demostración que muestra los casos de uso y una implementación que podría servir como punto de partida, consulte Nuestro repositorio con un ejemplo de Java y Kotlin. 

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 Encuentre las versiones nativas del SDK compatibles

1. Instalación

El sistema 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

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.

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í:

Para obtener más información sobre nuestra descripción general de la versión del SDK y el registro de cambios, consulte click en 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 click en este enlace. Para obtener más información, consulte

<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, aunque con el coste de dos vistas de página. Ejemplo: 

// code snippet to manually check the need for consent and manually display the consent layer
// ***********************************************************************
// * ATTENTION: although some users might prefer this                    *
// *            Use Case below instead of the automatic way, it          *
// *            comes with a cost of one page view for the check()       *
// *.           method, and another pageview for the openConsentLayer(), *
// *            so be aware. 											 *
// ***********************************************************************

cmpManager.check({ isConsentRequired ->
  if (isConsentRequired) {
    // Consent is required, handle accordingly
    runOnUiThread {
      // Update UI or show consent dialog
      cmpManager.openConsentLayer()
      }
  } 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

Comportamiento del diálogo

Usando la estrategia Fragmento

<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

Comprobando el consentimiento

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)

Pasar información de consentimiento a otras fuentes

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:

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: 

// Importing consent data if desired
cmpManager.importCmpString("your_base64_encoded_consentString")

// ... Your code here ...

// Exporting consent data
val consentString: String = cmpManager.exportCmpString()

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

Enlaces internos de aplicaciones y lista blanca de dominios

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.

Diagnóstico

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