[iOS] 1. consentmanager Intégration SDK

SDK obsolète / Mise à niveau vers la version 3 : Cette documentation décrit la version 2.x de notre SDK. Le SDK 2.x est obsolète et sera supprimé d'ici la fin de l'année 2025. Veuillez effectuer une mise à niveau vers la version 3.x du SDK. Voir la section Aide sur SDK v3 ici.

Sur ce document, vous trouverez des informations générales sur la façon d'intégrer notre SDK à votre projet. Pour plus de détails, veuillez vous référer à notre Référence de l'API documentation. Pour notre application de démonstration présentant les cas d'utilisation et une implémentation qui pourrait servir de point de départ, veuillez consulter notre dépôt. 

1. Installation

Le consentmanager Le SDK pour les applications iOS implémente et fournit des fonctionnalités pour informer l'utilisateur sur la protection des données et demander et recueillir le consentement de l'utilisateur. Il permet aux développeurs d'applications d'intégrer facilement le consentmanager service dans leur application.

Étapes – Description de haut niveau

En suivant ces étapes, vous vous assurez que votre application est conforme aux exigences de consentement et que le consentement de l'utilisateur est correctement géré et stocké.

Consent Manager Diagramme de séquence du SDK du fournisseur

Pour illustrer les étapes ci-dessus, vérifions dans le diagramme ci-dessous trois flux de séquence SDK possibles. 

1. Lors de la création d'une instance à l'aide de initialiser fonction, il y a deux résultats possibles. La première est lorsque l'API Consentmanger informe le SDK que la CMP ne s'ouvrira pas, ce qui déclenche le OnCmpNotOpenedCallbackOnCmpNotOpenedCallback. Le deuxième résultat est lorsque la couche de consentement s'ouvre, permettant à l'utilisateur d'interagir avec elle, et cela déclenche le SurOpenCallback. Une fois que l'utilisateur a donné son consentement et que celui-ci a été traité, le OnCmpCloseCallbackOnCmpCloseCallback est appelé.

Veuillez noter que SurErreurRappel est représenté par les flèches rouges en pointillés pour fournir des exemples d'erreurs pouvant survenir au cours du processus.

2. Créer une instance et appeler le ouvrirAndCheckConsent les fonctions conduiront à un processus similaire. La différence est qu'en dissociant la création de l'instance et la vérification de l'API consentementmanger, vous obtenez la possibilité d'ajouter une logique métier et d'interagir avec l'API des bibliothèques.

3. Créer une instance et appeler le couche ouverte fonction ouvrira le calque sans vérifier le consentmanager, si c'est nécessaire. Si le consentement a déjà été donné, les options et les paramètres seront affichés à l'utilisateur. Le flux de processus ressemblera à ceci :

Pour plus d'informations sur la présentation de la version du SDK et le journal des modifications, veuillez vous référer à ce lien.

Installation via Cocoapod

Vous pouvez installer le consentmanager SDK en ajoutant CmpSdk à votre Podfile comme expliqué dans l'exemple ci-dessous:

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

Une fois que cela est fait, vous devez exécuter pod install dans le répertoire de votre projet pour installer le consentmanager SDK. Après cela, veuillez ouvrir le *.xcworkspace et construire. 

Après avoir suivi toutes les étapes, votre dépendance doit être installée et vous pouvez continuer et l'utiliser dans votre projet.

Installation via le gestionnaire de packages Swift

1. Ouvrez le gestionnaire de packages Swift.
2. Cliquez sur File > Swift Packages > Add Package Dependency.
3. Ajouter l'URL du référentiel SDK
   Vous verrez maintenant une nouvelle fenêtre dans laquelle vous pourrez entrer l'URL du référentiel du SDK. La plupart des SDK sont hébergés sur GitHub, donc l'URL ressemblera souvent à
   https://github.com/iubenda/cm-sdk-xcframework.git
   Après avoir entré l'URL, cliquez sur Next.
4. Sélectionnez la version du SDK
   SPM va maintenant récupérer le référentiel et vous demander de sélectionner une version.
   Vous pouvez choisir d'ajouter le package en sélectionnant une règle de version :
   - Up to Next Major: Cela mettra à jour le paquet jusqu'à la prochaine version majeure. C'est l'option recommandée car elle ajoute des mises à jour qui n'ont pas de modifications avec rupture.
   - Up to Next Minor: Cela mettra à jour le paquet jusqu'à la prochaine version mineure.
   - Exact: Cela verrouillera le paquet sur une version spécifique. Aucune mise à jour ne sera installée.
   Sélectionnez la version que vous souhaitez utiliser et cliquez sur Next.
5. Ajoutez le SDK à votre cible
   Sur l'écran suivant, sélectionnez les cibles auxquelles vous souhaitez ajouter la dépendance du package. Les cibles sont généralement votre application et tous les tests que vous pourriez avoir. Cliquez sur Finish pour terminer le processus.
6. Importer le SDK
   Maintenant que le SDK a été ajouté à votre projet, vous devez l'importer pour l'utiliser. Accédez au fichier dans lequel vous souhaitez utiliser le SDK et ajoutez l'instruction d'importation suivante en haut :

import CmpSdk

2. Initialisation du SDK

Dans le démarrage de l'application (votre viewDidLoad fonction), vous devez créer une instance de classe CMPManager. le initialize() La fonction récupérera automatiquement les données nécessaires de notre serveur et déterminera si l'écran de consentement doit être affiché ou non. Si tel est le cas, le SDK affichera automatiquement l'écran de consentement à ce stade, collectera les données et fournira les données à l'application. L'instance peut ensuite être utilisée pour obtenir les détails de consentement du SDK afin de l'utiliser dans l'application.

Exemple d'initialisation, utilisant le comportement automatique du initialize() méthode:

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

Le SDK propose, dans un souci de flexibilité, un moyen d'afficher manuellement la couche de consentement, bien qu'au prix de deux vues de page, une pour la méthode check, une autre pour la méthode openLayer. Exemple : 

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

Veuillez noter qu'il est essentiel d'utiliser le initialize() dans le SDK dans la méthode viewDidLoad, si vous optez pour l'initialisation automatique. Sinon, la vue risque de ne pas être prête à être utilisée et le SDK risque d'échouer. Assurez-vous également que vous utilisez les données de configuration correctes. Les données de configuration se trouvent dans votre consentmanager compte à Menu > CMP > Obtenir le code pour les applications > Code-ID

SwiftUI

Pour intégrer le SDK dans un environnement SwiftUI, vous devez fournir un UIViewController qui est enveloppé à l'intérieur d'un UIViewControllerRepresentable. Vous pouvez trouver plus d'informations sur le site officiel documentation pomme. Avant d'intégrer le SDK, assurez-vous d'avoir déjà intégré le module dans votre projet. 

1. Nous commençons par créer un UiViewController habituel similaire aux exemples pour 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. Pour utiliser le contrôleur dans le interface utilisateur rapide vous devez créer un UIViewControllerRepresentable qui instancie le CmpViewController :

import SwiftUI

struct CmpViewControllerRepresentable: UIViewControllerRepresentable {
    func makeUIViewController(context: Context) -> UIViewController {
        let cmpViewController = CmpViewController()
        
        return cmpViewController
    }
    
    func updateUIViewController(_ uiViewController: UIViewController, context: Context) {
    }
}

3. Nous pouvons maintenant utiliser le ContrôleurView dans le contexte SwiftUI :

import SwiftUI

@main
struct cmpApp: App {
    var body: some Scene {
        WindowGroup {
            CmpViewControllerRepresentable()
        }
    }
}

3. Utilisation du SDK

Vérification du consentement

Afin de vérifier si un fournisseur ou un objectif a son consentement, vous pouvez utiliser les deux méthodes:

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

Les deux méthodes hasPurposeConsent et hasVendorConsent nécessitent deux paramètres :

• id - Chaîne du fournisseur ou de l'ID de fonction. Veuillez noter que les identifiants de fournisseur peuvent avoir différents formats ("123", "s123" et "c123"), veuillez vérifier avec Menu> Fournisseurs et Menu> Objectifs dans votre consentmanager compte.
• isIABVendor / isIABPurpose - Si le fournisseur ou l'objet est un fournisseur / objectif qui suit la norme IAB TCF, vous devrez définir un vrai, sinon un faux.

N'oubliez pas: tous les fournisseurs qui n'appartiennent pas à l'IAB ont des ID commençant par un "s" ou "c" (par exemple, "s123"); les fournisseurs qui appartiennent à l'IAB ont des ID ne commençant pas par un «s» ou «c».

Réouverture de l'écran de consentement

Afin de permettre à l'utilisateur de modifier les choix, vous pouvez simplement appeler openView()

cmpManager!.openView()

Transmission d'informations sur le consentement à d'autres sources

Dans certains cas, une application native peut contenir des vues Web afin d'afficher certains éléments comme de la publicité ou du contenu. Afin de transmettre les informations de consentement du SDK à la vue Web, veuillez utiliser la fonction :

consentData = cmpManager.exportCmpString();

Cela exportera les informations de consentement et toutes les autres données nécessaires au CMP. Vous pouvez ensuite transmettre ces informations au CMP qui se trouve dans votre vue Web en l'ajoutant à l'URL appelée dans la vue 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");

Intégration avec Apple Tracking Transparency (ATT)

Si vous utilisez le suivi ou l'analyse dans votre application, nous vous recommandons de lire le guide sur Mise en œuvre du TCA ici.

Création d'une mise en page personnalisée

Pour une mise en page personnalisée, il existe 2 fonctions de rappel qui fournissent le viewController et le uiView. Dans l'exemple ci-dessous, vous pouvez voir comment personnaliser la mise en page :

        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. avecCmpViewControllerConfigurationBlock

Cette fonction vous permet de personnaliser le style de présentation du contrôleur de vue pour le composant du SDK. En passant un bloc de configuration, vous pouvez modifier diverses propriétés du contrôleur de vue, comme son style de présentation modale.

Mise en situation : 

.withCmpViewControllerConfigurationBlock({ viewController in
	// Ensure the viewController is not nil before applying the configuration
	viewController?.modalPresentationStyle = .currentContext
	})

2. avecCmpViewConfigurationBlock

Cette fonction vous permet de personnaliser la vue de l'interface utilisateur du composant du SDK. En passant un bloc de configuration, vous pouvez modifier diverses propriétés de la vue, telles que sa disposition et son apparence.

Mise en situation :

.withCmpViewConfigurationBlock({ uiView in
	// Configure the uiView to display as a half-screen top layout
	CmpUIConfig.configureHalfScreenTop(for: uiView)
    })

Écouteurs d'événements personnalisés

Pour ajouter une logique de processus supplémentaire, vous pouvez utiliser des écouteurs d'événement. Les écouteurs d'événement suivants sont disponibles :

Autorisation d'importation/exportation

Pour importer ou exporter le consentement vous pouvez utiliser les fonctions exportCMPString() et importCMPString(). Vérifiez l'exemple ci-dessous : 

// Importing consent data if you like
cmpManager.importCmpString("${your base64 encoded consentString}");

// ... Your code here ...

// Exporting Consent data 
let consentString : String = cmpManager.exportCmpString()

La consentString doit être codée en base64.

Liens d'application internes et liste blanche de domaines

Pour implémenter la fonctionnalité où certains domaines sont sur liste blanche et, lorsqu'ils sont accessibles dans la WebView de la plateforme de consentement (CMP), ne sont pas ouverts dans un navigateur externe comme Safari mais dans la WebView elle-même, vous pouvez implémenter un mécanisme de rappel pour effectuer des actions personnalisées basées sur le domaine, comme l'ouverture d'un autre 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
            })        

Journal

Pour implémenter la fonctionnalité où certains domaines sont sur liste blanche et, lorsqu'ils sont accessibles dans la WebView de la plateforme de consentement (CMP), ne sont pas ouverts dans un navigateur externe comme Safari mais dans la WebView elle-même, vous pouvez implémenter un mécanisme de rappel pour effectuer des actions personnalisées basées sur le domaine, comme l'ouverture d'un autre ViewController :

Liens d'application internes et liste blanche de domaines

Pour implémenter la fonctionnalité où certains domaines sont sur liste blanche et, lorsqu'ils sont accessibles dans la WebView de la plateforme de consentement (CMP), ne sont pas ouverts dans un navigateur externe comme Safari mais dans la WebView elle-même, vous pouvez implémenter un mécanisme de rappel pour effectuer des actions personnalisées basées sur le domaine, comme l'ouverture d'un autre ViewController :

Lorsque vous utilisez notre SDK iOS, vous devrez peut-être déboguer ou analyser les informations des journaux à diverses fins. Les journaux générés par notre SDK sont étiquetés sous « Cmp : », vous permettant de filtrer et d'afficher facilement uniquement les journaux pertinents. Ce guide fournit des instructions étape par étape sur la façon d'accéder à ces journaux dans Xcode.

Rechercher la balise

Dans la console de débogage de Xcode, vous pouvez rechercher des journaux spécifiquement marqués avec « Consentement » ou « CMP » pour isoler les journaux générés par notre SDK.

Facultatif : Ajuster le niveau détaillé

In CmpConfig, vous pouvez ajuster le niveau détaillé pour des journaux plus détaillés.

cmpConfig.isDebugMode = true   
cmpConfig.logLevel = CmpLogLevel.debug

• Permet des journaux plus détaillés
• Utile pour le débogage et l'analyse.

En ajustant le niveau détaillé, vous pouvez obtenir des informations de journal plus complètes, facilitant le débogage et l'analyse du comportement de notre SDK dans votre application.