[iOS] 1. consentmanager Integracja SDK

W tym dokumencie znajdziesz ogólne informacje na temat integracji naszego SDK z Twoim projektem. Więcej szczegółów znajdziesz w naszym Dokumentacja API dokumentacja. Aby zapoznać się z naszą aplikacją demonstracyjną prezentującą przypadki użycia i implementację, która mogłaby służyć jako punkt wyjścia, sprawdź nasze repozytorium. 

1. Instalacja

Kurs consentmanager SDK dla aplikacji na iOS implementuje i zapewnia funkcjonalność informowania użytkownika o ochronie danych oraz pytania i zbierania zgody od użytkownika. Umożliwia programistom aplikacji łatwą integrację consentmanager usługi do swojej aplikacji.

Kroki — opis wysokiego poziomu

Wykonując te kroki, masz pewność, że Twoja aplikacja jest zgodna z wymogami dotyczącymi zgody oraz że zgody użytkowników są odpowiednio zarządzane i przechowywane.

Consent Manager Diagram sekwencji zestawu SDK dostawcy

Aby zilustrować powyższe kroki, sprawdźmy na poniższym diagramie trzy możliwe przepływy sekwencji SDK. 

1. Podczas tworzenia instancji przy użyciu zainicjować funkcji, istnieją dwa możliwe wyniki. Pierwsza ma miejsce, gdy interfejs API zgody informuje zestaw SDK, że CMP nie zostanie otwarty, co powoduje wyzwolenie OnCmpNotOpenedWywołanie zwrotne. Drugim rezultatem jest otwarcie warstwy zgody, co pozwala użytkownikowi na interakcję z nią, a to wyzwala OnOpenCallback. Po wyrażeniu przez użytkownika zgody i przetworzeniu zgody, OnCmpCloseOddzwonienie nazywa się.

Należy pamiętać, że Przy oddzwonieniu po błędzie jest reprezentowany przez czerwone przerywane linie strzałek, aby podać przykłady błędów, które mogą wystąpić podczas procesu.

2. Tworzenie instancji i wywoływanie otwórz i sprawdź zgodę funkcje doprowadzą do podobnego procesu. Różnica polega na tym, że oddzielając tworzenie instancji od sprawdzania API zgody, zyskujesz możliwość dodawania logiki biznesowej i interakcji z API bibliotek.

3. Tworzenie instancji i wywoływanie Otwórz warstwę funkcja otworzy warstwę bez sprawdzania pliku consentmanager, jeśli to konieczne. Jeśli jest już wyrażona zgoda, opcje i ustawienia zostaną pokazane użytkownikowi. Przebieg procesu będzie wyglądał następująco:

Więcej informacji na temat naszego przeglądu wersji pakietu SDK i dziennika zmian można znaleźć w artykule pod tym linkiem.

Instalacja przez Cocoapod

Możesz zainstalować consentmanager SDK przez dodanie CmpSdk do twojego pliku Podfile, jak wyjaśniono w poniższym przykładzie:

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

Gdy to zrobisz, musisz biec pod install w katalogu projektu, aby zainstalować consentmanager SDK. Następnie otwórz *.xcworkspace i buduj. 

Po wykonaniu wszystkich kroków Twoja zależność powinna zostać zainstalowana i możesz kontynuować i używać jej w swoim projekcie.

Instalacja za pomocą Swift Package Manager

1. Otwórz Menedżera pakietów Swift.
2. Iść do File > Swift Packages > Add Package Dependency.
3. Dodaj adres URL repozytorium SDK
   Zobaczysz teraz nowe okno, w którym możesz wpisać adres URL repozytorium pakietu SDK. Większość pakietów SDK jest hostowana w serwisie GitHub, więc adres URL często będzie wyglądał tak
   https://github.com/iubenda/cm-sdk-xcframework.git
   Po wpisaniu adresu URL kliknij Next.
4. Wybierz wersję SDK
   SPM pobierze teraz repozytorium i poprosi o wybranie wersji.
   Możesz dodać pakiet, wybierając regułę wersji:
   - Up to Next Major: Spowoduje to aktualizację pakietu do następnej wersji głównej. Jest to zalecana opcja, ponieważ dodaje aktualizacje, które nie mają istotnych zmian.
   - Up to Next Minor: Spowoduje to aktualizację pakietu do następnej wersji pomocniczej.
   - Exact: Spowoduje to zablokowanie pakietu w określonej wersji. Żadne aktualizacje nie zostaną zainstalowane.
   Wybierz wersję, której chcesz użyć i kliknij Next.
5. Dodaj SDK do swojego celu
   Na następnym ekranie wybierz cele, do których chcesz dodać zależność pakietu. Cele to zazwyczaj Twoja aplikacja i wszelkie testy, które możesz przeprowadzić. Kliknij Finish w celu zakończenia procesu.
6. Zaimportuj pakiet SDK
   Teraz, gdy pakiet SDK został dodany do Twojego projektu, musisz go zaimportować, aby go użyć. Przejdź do pliku, w którym chcesz użyć pakietu SDK, i dodaj u góry następującą instrukcję importu:

import CmpSdk

2. Inicjowanie pakietu SDK

W ramach startu aplikacji (twój viewDidLoad funkcja), musisz utworzyć instancję klasy CMPConsentTool. Plik initialize() funkcja automatycznie pobierze niezbędne dane z naszego serwera i określi, czy należy wyświetlić ekran zgody, czy nie. Jeśli tak, SDK automatycznie wyświetli w tym momencie ekran zgody, zbierze dane i przekaże je aplikacji. Instancję można następnie wykorzystać w celu uzyskania szczegółów zgody z zestawu SDK w celu wykorzystania jej w aplikacji.

Przykład inicjalizacji z wykorzystaniem automatycznego zachowania pliku initialize() metoda:

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

SDK oferuje, dla zapewnienia elastyczności, sposób ręcznego wyświetlania warstwy zgody, chociaż kosztem dwóch wyświetleń strony, jednego dla metody check, drugiego dla metody openLayer. Przykład: 

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

Należy pamiętać, że istotne jest korzystanie z initialize() w SDK w metodzie viewDidLoad, jeśli zdecydujesz się na automatyczną inicjalizację. W przeciwnym razie widok może nie być gotowy do użycia, a zestaw SDK może nie działać. Upewnij się także, że używasz prawidłowych danych konfiguracyjnych. Dane konfiguracyjne można znaleźć w pliku consentmanager konto na Menu > CMP > Pobierz kod dla aplikacji > Code-ID

SwiftUI

Aby zintegrować zestaw SDK ze środowiskiem SwiftUI, należy udostępnić plik Kontroler UIView który jest owinięty wewnątrz a UIViewControllerReprezentatywny. Więcej informacji znajdziesz na oficjalnej stronie dokumentacja jabłkowa. Przed integracją SDK upewnij się, że zintegrowałeś już moduł w swoim projekcie. 

1. Zaczynamy od stworzenia zwykłego UiViewControllera podobnego do przykładów dla 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. W celu korzystania z kontrolera w SwiftUI musisz utworzyć UIViewControllerRepresentable, który tworzy instancję Kontroler CmpView:

import SwiftUI

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

3. Teraz możemy użyć Widok kontrolera wewnątrz kontekstu SwiftUI:

import SwiftUI

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

3. Korzystanie z SDK

Sprawdzanie zgody

Aby sprawdzić, czy sprzedawca lub cel mają zgodę, możesz skorzystać z dwóch metod:

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

Obie metody hasPurposeConsent i hasVendorConsent wymagają dwóch parametrów:

• id — ciąg identyfikatora dostawcy lub celu. Należy pamiętać, że identyfikatory dostawców mogą mieć różne formaty („123”, „s123” i „c123”), sprawdź dokładnie za pomocą Menu > Sprzedawcy i Menu > Cele w telefonie consentmanager konta.
• isIABVendor / isIABPurpose — jeśli dostawca lub cel jest dostawcą/celem zgodnym ze standardem IAB TCF, należy ustawić wartość prawda, w przeciwnym razie fałsz.

Pamiętaj: wszyscy dostawcy, którzy nie należą do IAB, mają identyfikatory zaczynające się od „s” lub „c” (np. „s123”); dostawcy należący do IAB mają identyfikatory, które nie zaczynają się od „s” lub „c”.

Ponowne otwieranie ekranu zgody

Aby umożliwić użytkownikowi zmianę wyborów, wystarczy zadzwonić openView()

cmpManager!.openView()

Przekazywanie informacji o Zgodzie do innych źródeł

W niektórych przypadkach aplikacja natywna może zawierać widoki internetowe w celu wyświetlania określonych rzeczy, takich jak reklamy lub treści. W celu przesłania informacji o zgodzie z SDK do webview należy skorzystać z funkcji:

consentData = cmpManager.exportCmpString();

Spowoduje to wyeksportowanie informacji o zgodzie i wszystkich dalszych danych wymaganych przez CMP. Następnie możesz przekazać te informacje do CMP w widoku sieciowym, dodając je do adresu URL wywoływanego w widoku sieciowym:

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");

Integracja z Apple Tracking Transparency (ATT)

Jeśli korzystasz ze śledzenia lub analityki w swojej aplikacji, zalecamy zapoznanie się z przewodnikiem Implementacja ATT tutaj.

Tworzenie niestandardowego układu

W przypadku układu niestandardowego dostępne są 2 funkcje wywołania zwrotnego, które udostępniają kontroler viewController i uiView. W przykładzie pokazanym poniżej możesz zobaczyć, jak dostosować układ:

        let cmpLayout = CmpLayout.default()
        cmpLayout?.cornerRadius = 10.0
        cmpLayout?.customLayout = CGRect(x: 0, y: 0, width: 200, height: 300)
        cmpManager = CMPConsentTool(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. z blokiem konfiguracyjnym CmpViewControllerConfigurationBlock

Ta funkcja umożliwia dostosowanie stylu prezentacji kontrolera widoku dla komponentu SDK. Przekazując blok konfiguracyjny, możesz modyfikować różne właściwości kontrolera widoku, takie jak jego modalny styl prezentacji.

Przykład: 

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

2. z blokiem CmpViewConfigurationBlock

Ta funkcja umożliwia dostosowanie widoku interfejsu użytkownika dla komponentu SDK. Przekazując blok konfiguracyjny, możesz modyfikować różne właściwości widoku, takie jak jego układ i wygląd

Przykład:

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

Niestandardowe odbiorniki zdarzeń

Aby dodać dodatkową logikę procesu, możesz skorzystać z detektorów zdarzeń. Dostępne są następujące detektory zdarzeń:

Zgoda na import/eksport

Aby zaimportować lub wyeksportować zgodę możesz skorzystać z funkcji exportCMPString() i importCMPString(). Sprawdź poniższy przykład: 

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

// ... Your code here ...

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

StringString powinien być zakodowany w standardzie Base64.

Wewnętrzne linki do aplikacji i biała lista domen

Aby zaimplementować funkcję, w której określone domeny znajdują się na białej liście i gdy są otwierane w ramach platformy zgody (CMP) WebView, nie są otwierane w zewnętrznej przeglądarce, takiej jak Safari, ale w samym WebView, możesz zaimplementować mechanizm wywołania zwrotnego w celu wykonywania niestandardowych działań w oparciu o domeny, na przykład otwarcie innego ViewControllera:

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

Logowanie

Podczas korzystania z naszego pakietu SDK dla systemu iOS może zaistnieć potrzeba debugowania lub analizowania informacji z dziennika do różnych celów. Dzienniki generowane przez nasz zestaw SDK są oznaczone w sekcji „Cmp:”, co pozwala na łatwe filtrowanie i przeglądanie tylko odpowiednich dzienników. Ten przewodnik zawiera instrukcje krok po kroku dotyczące uzyskiwania dostępu do tych dzienników w Xcode.

Wyszukaj tag

W konsoli debugowania Xcode możesz wyszukiwać dzienniki specjalnie oznaczone tagiem „Zgoda” lub „CMP”, aby odizolować dzienniki wygenerowane przez nasz zestaw SDK.

Opcjonalnie: Dostosuj poziom szczegółowości

In CmpConfig, możesz dostosować poziom szczegółowości, aby uzyskać bardziej szczegółowe dzienniki.

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

• Umożliwia bardziej szczegółowe dzienniki
• Przydatne do debugowania i analizy.

Dostosowując poziom szczegółowości, możesz uzyskać bardziej szczegółowe informacje z logów, pomagając w debugowaniu i analizie zachowania naszego pakietu SDK w Twojej aplikacji.