Informacia
Treść

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

1. Instalacja

Połączenia 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

  1. Integracja i konfiguracja:

    • Zintegruj pakiet SDK ze swoją aplikacją.
    • Skonfiguruj ustawienia SDK zgodnie ze swoimi potrzebami.
  2. Tworzenie instancji:

    • Podczas uruchamiania aplikacji utwórz instancję CMPConsentTool klasa. Ta instancja będzie obsługiwać proces wyrażania zgody.
  3. Inicjalizacja SDK:
    • Gdy instancja będzie gotowa, SDK automatycznie pobierze niezbędne informacje z pliku consentmanager serwerów w celu przygotowania ich do działania.
  4. Wyświetlanie ekranu zgody:

    • W razie potrzeby pakiet SDK automatycznie wyświetli ekran zgody CMPConsentTool instancja jest tworzona.
  5. Przetwarzanie danych osobowych:

    • Po zebraniu zgód informacje są przechowywane i można je przeglądać za pomocą różnych właściwości i metod udostępnianych przez nasz pakiet SDK. Będziesz mieć informacje o odrzuconych lub zaakceptowanych zgodach, dostawcach, celach itp.

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.

Zainicjuj-Cmp-Sequence-Diagram.png

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:

openlayer-Cmp-Schemat-Sekwencji-.png

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: CMPConsentTool? = 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 = CMPConsentTool(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
  }
}    

Ze względu na elastyczność pakiet SDK oferuje sposób ręcznego wyświetlania warstwy zgody, jak pokazano poniżej: 

.
.
.
// code snippet to manually check the need for consent and manually display the consent layer
cmpManager.check(isCached: true) { isConsentRequired in
    if isConsentRequired {
        // Consent is required, handle accordingly
        DispatchQueue.main.async {
            // Update UI or show consent dialog
            cmpManager?.openLayer()
        }
    } 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: CMPConsentTool? = 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()
        }
    }
}

Przedstawiono przykładowy projekt tutaj

3. Korzystanie z SDK

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

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

Imię

Występuje

 

CmpOpenListener

Odbiornik zdarzeń po otwarciu CMP

CmpCloseListener

Odbiornik zdarzenia, gdy CMP jest zamknięty

CmpNotOpenedListener

Odbiornik zdarzenia, gdy nie trzeba otwierać CMP

CmpErrorLister

Listener zostanie wywołany, jeśli podczas wywoływania Serwera lub wyświetlania widoku wystąpi błąd.

CmpButtonClickedListener

Odbiornik zdarzenia po kliknięciu przycisku i zamknięciu warstwy zgody

CmpATTrackingStatusChangedListener

Zmieniono status odbiornika ATTracking

onCmpUpdateGoogleZgoda

Odbiornik zmian w trybie zgody

Zgoda na import/eksport

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

StringString powinien być zakodowany w standardzie Base64.

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.

 

Powrót do góry