[iOS] 1. Consentmanager Integracja SDK

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.

Jak to działa?

1. Zintegruj SDK z aplikacją i skonfiguruj ustawienia SDK
2. Gdy SDK zostanie zintegrowany z aplikacją, SDK udostępni funkcje dla programisty aplikacji w celu pobrania danych dotyczących zgody
3. Gdy tylko aplikacja się uruchomi, SDK automatycznie pobierze informacje z ConsentManager serwery w celu przygotowania SDK do jego użycia.
4. Zaleca się, aby przy starcie aplikacji tworzyła instancję klasy CMPConsentTool. Po utworzeniu SDK automatycznie wyświetli ekran zgody, jeśli to konieczne.
5. Gdy aplikacja chce przetwarzać dane osobowe, powinna „zapytać” SDK, czy została wyrażona zgoda na konkretny cel i dostawcę.

Instalacja przez Cocoapod

Dodaj bibliotekę za pomocą 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

Iść do File > Swift Packages > Add Package Dependency.

2. 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 wprowadzeniu adresu URL kliknij Next.

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

4. Dodaj SDK do swojego celu

Na następnym ekranie wybierz cele, do których chcesz dodać zależność pakietu. Cele to zwykle Twoja aplikacja i wszelkie testy, które możesz mieć.
Kliknij Finish w celu zakończenia procesu.

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

Zainicjuj SDK

Dzięki aplikacji startowej (zazwyczaj funkcja viewDidLoad) możesz musi utwórz instancję klasy CMPConsentTool. Spowoduje to automatyczne pobranie niezbędnych danych z naszego serwera i określenie, czy ekran akceptacji ma być wyświetlany, czy nie. Jeśli tak, SDK automatycznie wyświetli w tym momencie ekran zgody, zbierze dane i przekaże je do aplikacji. Instancję można następnie wykorzystać w celu uzyskania szczegółów zgody z SDK w celu wykorzystania jej w aplikacji.

/** Initialize with CmpConfig */
let cmpConfig : CmpConfig = CmpConfig.init()
CmpConfig.setValues(myCmpConfig.domain, addCodeId: myCmpConfig.appId, addAppName: myCmpConfig.appName, addLanguage: myCmpConfig.language)
cmpConsentTool = CMPConsentTool(cmpConfig: cmpConfig, viewController: self)
  
/** Initialize without CmpConfig */
  
cmpConsentTool = cmpConsentTool(CMPConsentTool(domain: myCmpConfig.domain, codeId: myCmpConfig.appId, appName: myCmpConfig.appName, language: myCmpConfig.language, viewController: self))
        
/** Optionally chain callbacks */
cmpConsentTool = cmpConsentTool.withOpenListener(onOpen)
            				   .withOnCmpButtonClickedCallback(onButtonClickedEvent)
            				   .withCloseListener(onClose)
           					   .withErrorListener(onCmpError)

Należy pamiętać, że ważne jest zainicjowanie zestawu SDK w metodzie viewDidLoad. W przeciwnym razie widok może nie być gotowy do użycia, a zestaw SDK może zakończyć się niepowodzeniem.

Upewnij się, że używasz poprawnych danych konfiguracyjnych. Dane konfiguracyjne można znaleźć w swoim ConsentManager konto na Menu > Uzyskaj kod > Identyfikator kodu

SwiftUI

Aby zintegrować SDK w środowisku SwiftUI, musisz podać 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 consentmanager


class CmpViewController: UIViewController {
    struct CmpConfig {
           static let domain = "www.consentmanager.net"
           static let appId = "123456"
           static let appName = "test App"
           static let language = "DE"
       }
    var cmpConsentTool: CMPConsentTool? = nil
    func onClose() -> Void {
        NSLog("closed event");
    }

    func onOpen() -> Void {
        NSLog("opened event");
    }

    func onCMPNotOpened() -> Void {
        NSLog("not opened event");
    }
    
    override func viewDidLoad() {
        cmpConsentTool = cmpConsentTool(CMPConsentTool(domain: CmpConfig.domain, codeId: CmpConfig.appId, appName: CmpConfig.appName, language: CmpConfig.language, viewController: self))
        // creating a example button to manually open the consent screen
        let button = UIButton.init(frame: CGRect.init(x: 10, y: 100, width: 100, height: 50))
        button.setTitle("Consent", for: .normal)
        button.backgroundColor = .red
        button.addTarget(self, action: #selector(onShowConsentClicked), for: .touchUpInside)
        self.view.addSubview(button)
    }
    
    /**
     * Show consent button was clicked
     */
    @objc func onShowConsentClicked(sender: UIButton!) {
        cmpConsentTool!.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

Korzystanie z SDK

Sprawdź zgodę

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

if(consentTool!.hasPurposeConsent("52", purposeIsV1orV2: false))
{
    if(consentTool!.hasVendorConsent("s26", purposeIsV1orV2: false))
    {
        //do something with data
    }
}

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 konto.
• 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()

cmpConsentTool!.openView()

Przekazywanie informacji o Zgodzie do innych źródeł

W niektórych przypadkach natywna aplikacja może zawierać widoki internetowe w celu wyświetlania pewnych rzeczy, takich jak reklamy lub treści. W celu przekazania informacji o zgodzie z SDK do webview prosimy o skorzystanie z funkcji:

consentData = CmpConsentTool.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)

Od czasu iOS 14 firma Apple wprowadziła platformę Apple Tracking Transparency, która wymaga, aby każda aplikacja ujawniała dane śledzenia, z których korzysta. Sama struktura ATT nie jest zgodna z IAB TCF/RODO itp. i jest tylko wersją specyficzną dla firmy Apple, w której można poprosić użytkownika o zgodę na śledzenie danych. Aby umożliwić użytkownikowi lepsze wrażenia, wspieramy rozwiązanie do synchronizacji zgód między CMP SDK a interfejsem ATT. SDK oferuje w tym celu dwa różne rozwiązania. 

1. Deweloper samodzielnie integruje ATT Framework, a następnie przekazuje otrzymane informacje do CMP SDK. Dokumentację jabłek można znaleźć tutaj

Zalecamy tę integrację. Nadal możesz uzyskać pełną kontrolę nad interfejsem ATT i wdrożyć spersonalizowany proces w zależności od użytkownika.  

Integracja mogłaby wyglądać tak. 

       func requestPermission() {
           if #available(iOS 14, *) {
               ATTrackingManager.requestTrackingAuthorization(completionHandler: { status in
                   switch status {
                   case .authorized:
                       // Tracking authorization dialog was shown and accepted
                       // TODO custom code here:
                   case .denied:
                       // Tracking authorization dialog was shown and permission is denied
                       // TODO custom code here:
                   case .notDetermined:
                       // Tracking authorization dialog has not been shown
                       // TODO custom code here:
                   case .restricted:
                       // Tracking authorization dialog has not been shown app is restricted for tracking
                       // TODO custom code here:
                   }
                   // After determination of the att status, pass the information to the cmp sdk                                                           
                   CmpConfig.setAppleTrackingStatus(status.rawValue);
               })
           }
       }

Prośba o pozwolenie może wyglądać tak. Ważny wiersz kodu to 19, w którym informacje są przekazywane do CMP SDK. W zależności od statusu ATT CMP SDK ustawia wstępnie zdefiniowane informacje o zgodzie. 

2. Deweloper aktywuje automatyczne śledzenie jabłek. CMP SDK obsługuje żądanie z domyślnym protokołem. Stan będzie wtedy obsługiwany przez CMP SDK. Później możliwe jest uzyskanie statusu ATT przez programistę, mimo to niestandardowe akcje powinny być obsługiwane na żądanie, jak w opcji 1. Możesz aktywować automatyczne żądanie ATT za pomocą:

Spowoduje to wyświetlenie warstwy ATT z systemu operacyjnego. 

CmpConfig.setAutoAppleTracking(true);

Pamiętaj, aby aktywować tę funkcję przed utworzeniem wystąpienia CMP SDK. 

Jeśli nie używasz ATT, być może będziesz musiał zanotować automatyczną recenzję Apple. Ponieważ Apple ATT jest zintegrowany jako opcja, ale nie jest używany. Apple może nie zatwierdzić Aplikacji automatycznie.

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 eksportCMPData() i importCMPData (ciąg cmpData). Sprawdź poniższy przykład: 

// Instanstiate CMPConsentTool()
cmpConsentTool = CMPConsentTool.init(...)

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

// ... Your code here ...


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

ZgodaString, którą musisz przekazać, powinna być zakodowana w base64.

Diagram sekwencji CMP SDK

W tym przykładzie pokazujemy trzy możliwe przepływy sekwencji SDK, aby zrozumieć Consentmanager i tam procesy. 

1. Podczas tworzenia instancji przy użyciu zainicjować funkcji, możliwe są dwa wyniki. Pierwszym jest sytuacja, w której interfejs API Consentmanager informuje SDK, że CMP nie zostanie otwarty, co wyzwala błąd 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 interfejsu API Consentmanager, zyskujesz możliwość dodania logiki biznesowej i interakcji z interfejsem 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:

Dynamiczne blokowanie treści za pomocą symbolu zastępczego UIView

Ta funkcja jest przestarzała i zostanie usunięta w przyszłości. Użyj interfejsu API enableVendorList

Symbol zastępczy viewObject można zaimplementować, aby uzyskać funkcjonalność dynamicznego blokowania treści tutaj.Możesz utworzyć widok za pomocą następującej metody: 

class ViewController: UIViewController, CmpPlaceholderAcceptedDelegate {
//...
  
@objc func createPlaceholderView{
	let params : CmpPlaceholderParams = CmpPlaceholderParams.init(vendorId: "123");
	let placeholder : CmpPlaceholderView = (cmpConsentTool?.createPlaceholder(CGRect.init(x: 0, y: 300, width: view.frame.size.width, height: 				view.frame.size.height), params))!;
	placeholder.vendorDelegate = self;
	view.addSubview(placeholder);	
}



func vendorAccepted(_ placeholderView: CmpPlaceholderView!) {
	//... actions to do when the consent is accepted
  	// Like showing youtube video view
}
// ...
}

Z obiektem opakowującym CMPPlaceholderParams możesz także przekazać parametry opcjonalne, takie jak teksty niestandardowe lub opcjonalny obraz podglądu. możesz dodać własne teksty, jak pokazano poniżej: 

params.buttonText = "Click me";

Wymagana logika biznesowa, gdy chcesz pokazać widok i nie musi być stosowana przez dewelopera. Aby uzyskać informacje, gdy użytkownik wchodzi w interakcję z symbolem zastępczym, możesz użyć przygotowanego pełnomocnika CmpPlaceholderAcceptedDelegate. Za pomocą pełnomocnika będziesz musiał zaimplementować funkcję vendorAccepted, w której możesz kontrolować dodatkową logikę, gdy użytkownik zaakceptuje zgodę.