[IOS] 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. 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.
1. Instalación
El consentmanager El SDK para aplicaciones de iOS 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: descripción de alto nivel
-
Integración y Configuración:
- Integre el SDK en su aplicación.
- Configure los ajustes del SDK según sus necesidades.
-
Creando una instancia:
- Al iniciar la aplicación, cree una instancia de
CMPManager
clase. Esta instancia se encargará del proceso de consentimiento.
- Al iniciar la aplicación, cree una instancia de
-
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.
-
Mostrar la pantalla de consentimiento:
- El SDK mostrará automáticamente la pantalla de consentimiento si es necesario cuando el
CMPManager
Se crea la instancia.
- El SDK mostrará automáticamente la pantalla de consentimiento si es necesario cuando el
-
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.
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 este enlace.
Instalación a través de Cocoapod
Puedes instalar el consentmanager SDK agregando CmpSdk
a su Podfile como se explica en el siguiente ejemplo:
target 'YourProject' do
# Comment the next line if you don't want to use dynamic frameworks
use_frameworks!
pod 'CmpSdk'
target 'YourProjectTests' do
inherit! :search_paths
# Pods for testing
end
...
end
Una vez hecho esto, debe ejecutar pod install
en el directorio de su proyecto para instalar el consentmanager SDK. Después de esto, abra el *.xcworkspace
y construir.
Una vez que haya seguido todos los pasos, su dependencia debe estar instalada y puede continuar y usarla en su proyecto.
Instalación a través de Swift Package Manager
- Abra el Administrador de paquetes Swift.
- Vaya a
File
>Swift Packages
>Add Package Dependency
. - Agregue la URL del repositorio del SDK
Ahora verá una nueva ventana donde puede ingresar la URL del repositorio del SDK. La mayoría de los SDK están alojados en GitHub, por lo que la URL a menudo se verá como
https://github.com/iubenda/cm-sdk-xcframework.git
Después de ingresar la URL, haga clicNext
. - Seleccione la versión del SDK
SPM ahora buscará el repositorio y le pedirá que seleccione una versión.
Puede optar por agregar el paquete seleccionando una regla de versión:
-Up to Next Major
: Esto actualizará el paquete a la próxima versión principal. Es la opción recomendada ya que agrega actualizaciones que no tienen cambios de última hora.
-Up to Next Minor
: Esto actualizará el paquete a la próxima versión secundaria.
-Exact
: Esto bloqueará el paquete a una versión específica. No se instalarán actualizaciones.
Seleccione la versión que desea utilizar y haga clic enNext
. - Agregue el SDK a su destino
En la siguiente pantalla, seleccione los destinos a los que desea agregar la dependencia del paquete. Los objetivos suelen ser su aplicación y cualquier prueba que pueda tener. Hacer clicFinish
para completar el proceso. - Importar el SDK
Ahora que se agregó el SDK a su proyecto, debe importarlo para usarlo. Vaya al archivo donde desea usar el SDK y agregue la siguiente declaración de importación en la parte superior:
import CmpSdk
2. Inicializando el SDK
Dentro del inicio de la aplicación (su viewDidLoad
función), debes crear una instancia de clase CMPManager
. 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 poder usarla en la aplicación.
Ejemplo de inicialización, utilizando el comportamiento automático del initialize()
método:
class ViewController: UIViewController {
// Usual implementation of a View Controller
var cmpManager: CmpManager? = nil
override func viewDidLoad() {
super.viewDidLoad()
// Configure your CMP
let cmpConfig: CmpConfig = CmpConfig.shared.setup(
withId: "<YOUR-CONSENTMANAGER-APP-ID>", // example: a000aaaaa1a
domain: "<YOUR-CONSENTMANAGER-APP-DOMAIN>", // example: delivery.consentmanager.net
appName: "<YOUR-CONSENTMANAGER-APP-NAME>", // example: testApp
language: "<YOUR-CONSENTMANAGER-APP-LANGUAGE"); // example: DE
// You can also determine log levels or ask for Apple's App Tracking Transparency, for example
cmpConfig.logLevel = CmpLogLevel.verbose;
cmpConfig.isAutomaticATTRequest = true;
// Then you pass the cmpConfig to set up and initialize the instance of our SDK
cmpManager = CmpManager(cmpConfig: cmpConfig)
.withErrorListener(onCMPError)
.withCloseListener(onClose)
.withOpenListener(onOpen)
.withOnCMPNotOpenedListener(onCMPNotOpened)
.withOnCmpButtonClickedCallback(onButtonClickedEvent)
.initialize() // This method will trigger the webview loading to collect consent, if necessary
}
}
El SDK ofrece, en aras de la flexibilidad, una forma de mostrar manualmente la capa de consentimiento, aunque a costa de dos vistas de página, una para el método de verificación y otra para el método openLayer. 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 openLayer method() *
// * so be aware. *
// ***********************************************************************
cmpManager.check(isCached: true) { isConsentRequired in // One page view is counted in case cached consent is expired
if isConsentRequired {
// Consent is required, handle accordingly
DispatchQueue.main.async {
// Update UI or show consent dialog
cmpManager?.openLayer() // One page view is counted here
}
} else {
// Consent is not required, proceed with application logic
}
}
Tenga en cuenta que es vital utilizar el initialize()
método en el SDK en el método viewDidLoad, si decide realizar la inicialización automática. De lo contrario, es posible que la vista no esté lista para usarse y que el SDK falle. Además, asegúrese de estar utilizando los datos de configuración correctos. Los datos de configuración se pueden encontrar en su consentmanager cuenta en Menú > CMP > Obtener código para aplicaciones > Código-ID
Interfaz de usuario rápida
Para integrar el SDK en un entorno SwiftUI, debe proporcionar un Controlador UIView que está envuelto dentro de un UIViewControllerRepresentable. Puede encontrar más información sobre en el oficial documentación de apple. Antes de integrar el SDK, asegúrese de que ya integró el Módulo en su proyecto.
1. Comenzamos con la creación de un UiViewController habitual similar a los ejemplos de Swift/Objective C
import UIKit
import CmpSdk
class CmpViewController: UIViewController {
var cmpManager: CmpManager? = nil
override func viewDidLoad() {
.
.
.
// Implement it like the previous example
}
/**
* Show consent button was clicked
*/
@objc func onShowConsentClicked(sender: UIButton!) {
cmpManager!.openView()
}
}
2. Para utilizar el controlador en el interfaz de usuario rápida tienes que crear un UIViewControllerRepresentable que está instanciando el Controlador CmpView:
import SwiftUI
struct CmpViewControllerRepresentable: UIViewControllerRepresentable {
func makeUIViewController(context: Context) -> UIViewController {
let cmpViewController = CmpViewController()
return cmpViewController
}
func updateUIViewController(_ uiViewController: UIViewController, context: Context) {
}
}
3. Ahora podemos usar el Vista del controlador dentro del contexto de SwiftUI:
import SwiftUI
@main
struct cmpApp: App {
var body: some Scene {
WindowGroup {
CmpViewControllerRepresentable()
}
}
}
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
requieren dos parámetros:
- id: cadena del proveedor o ID de propósito. Tenga en cuenta que las ID de proveedor pueden tener diferentes formatos ("123", "s123" y "c123"), verifique nuevamente con Menú> Proveedores y Menú> Propósitos en tu consentmanager cuenta.
- isIABVendor / isIABPurpose: si el proveedor o el propósito es un proveedor / propósito que sigue el estándar IAB TCF, deberá establecer un verdadero, de lo contrario, un 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 openView()
cmpManager!.openView()
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:
consentData = cmpManager.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);
/** to pass the att status you can use the cmpatt parameter (1=accepted, 2=declined) */
myWebView.loadURL("https://mywebsite.com/....#cmpimport=" + consentData + "&cmpatt=1");
Integración con Apple Tracking Transparency (ATT)
En caso de que esté utilizando seguimiento o análisis en su aplicación, le recomendamos leer la guía en Implementación del ATT aquí.
Crear un diseño personalizado
Para un diseño personalizado, hay 2 funciones de devolución de llamada que proporcionan viewController y uiView. En el ejemplo que se muestra a continuación puede ver cómo personalizar el diseño:
let cmpLayout = CmpLayout.default()
cmpLayout?.cornerRadius = 10.0
cmpLayout?.customLayout = CGRect(x: 0, y: 0, width: 200, height: 300)
cmpManager = CMPManager(cmpConfig: cmpConfig)
.withCmpViewControllerConfigurationBlock({ viewController in
viewController?.modalPresentationStyle = .formSheet
//example of customizing controller
})
.withCmpViewConfigurationBlock({ uiView in
cmpLayout?.apply(to: uiView)
// or use your own uiView logic
})
1. con CmpViewControllerConfigurationBlock
Esta función le permite personalizar el estilo de presentación del controlador de vista para el componente del SDK. Al pasar un bloque de configuración, puede modificar varias propiedades del controlador de vista, como su estilo de presentación modal.
Ejemplo:
.withCmpViewControllerConfigurationBlock({ viewController in
// Ensure the viewController is not nil before applying the configuration
viewController?.modalPresentationStyle = .currentContext
})
2. con CmpViewConfigurationBlock
Esta función le permite personalizar la vista de la interfaz de usuario para el componente del SDK. Al pasar un bloque de configuración, puede modificar varias propiedades de la vista, como su diseño y apariencia.
Ejemplo:
.withCmpViewConfigurationBlock({ uiView in
// Configure the uiView to display as a half-screen top layout
CmpUIConfig.configureHalfScreenTop(for: uiView)
})
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 |
ocurre
|
CmpOpenListener |
Oyente del evento cuando se abre CMP |
CmpCloseListener |
Oyente de evento cuando CMP está cerrado |
CmpNotOpenedListener |
Oyente para eventos cuando no es necesario abrir CMP |
CmpErrorListener |
Se llamará al oyente si se produce un error al llamar al servidor o al mostrar la vista. |
CmpButtonClickedListener |
Oyente de evento cuando se hace clic en el botón y se cierra la capa de consentimiento |
CmpATTrackingStatusChangedListener |
Se cambió el estado del oyente de ATTracking |
onCmpUpdateGoogleConsentimiento |
Oyente de cambios en el modo de consentimiento |
Consentimiento de importación/exportación
Para importar o exportar el consentimiento puede utilizar las funciones exportCMPString()
y importCMPString()
. Mira el ejemplo a continuación:
// Importing consent data if you like
cmpManager.importCmpString("${your base64 encoded consentString}");
// ... Your code here ...
// Exporting Consent data
let consentString : String = cmpManager.exportCmpString()
La cadena de consentimiento 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 Safari sino dentro del propio WebView, puede implementar un mecanismo de devolución de llamada para realizar acciones personalizadas basadas en el dominio, como abrir otro ViewController:
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
})
Inicio de sesión
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 Safari sino dentro del propio WebView, puede implementar un mecanismo de devolución de llamada para realizar acciones personalizadas basadas en el dominio, como abrir otro ViewController:
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 Safari sino dentro del propio WebView, puede implementar un mecanismo de devolución de llamada para realizar acciones personalizadas basadas en el dominio, como abrir otro ViewController:
Al utilizar nuestro SDK de iOS, es posible que necesite depurar o analizar información de registro para diversos fines. Los registros generados por nuestro SDK están etiquetados en "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 en Xcode.
Busque la etiqueta
En la consola de depuración de Xcode, puede buscar registros específicamente etiquetados con "Consentimiento" o "CMP" para aislar los registros generados por nuestro SDK.
Opcional: ajustar el nivel detallado
In CmpConfig
, puede ajustar el nivel detallado para obtener registros más detallados.
cmpConfig.isDebugMode = true
cmpConfig.logLevel = CmpLogLevel.debug
- Permite registros más detallados
- Útil para depuración y análisis.
Al ajustar el nivel detallado, puede obtener información de registro más completa, lo que ayudará en la depuración y el análisis del comportamiento de nuestro SDK en su aplicación.