Integrazione iOS
Il SDK PubConsent è l'integrazione del nostro CMP PubConsent nelle applicazioni iOS.
Questa integrazione non richiede molti aggiornamenti poiché ogni cambiamento effettuato all'interno del configuratore si rifletterà automaticamente. Supportiamo versioni iOS dalla 9 fino all'ultima.
Ogni volta che ci saranno cambiamenti significativi, verrai contattato via email al tuo indirizzo tecnico configurato nel nostro pannello di controllo per permetterti di aggiornare la versione del SDK all'ultima che abbiamo pubblicato.
Per ulteriori API o informazioni su come funziona, non esitare a contattare il nostro supporto clienti. Ogni bug o problema durante l'integrazione sarà un feedback prezioso per noi. Per favore, non esitare a contattarci.
Requisiti
Offriamo il nostro SDK come pacchetto binario precompilato come XCFramework che puoi aggiungere alla tua applicazione. Supportiamo versioni iOS >= 12.
L'SDK iOS PubConsent è scritto in Swift, quindi se la tua app è scritta in Objective-C, assicurati che il flag Always Embed Swift Standard Libraries sia impostato su YES.
Aggiungere l'SDK al tuo progetto
Il pacchetto può essere aggiunto utilizzando CocoaPods o manualmente.
Usando CocoaPods
A partire dalle prossime versioni, il supporto per CocoaPods verrà dismesso. Consigliamo vivamente di migrare a Swift Package Manager (SPM), che è lo strumento ufficiale di gestione dei pacchetti supportato da Apple. SPM offre una migliore integrazione con Xcode, maggiore stabilità e un supporto continuo da parte della community. Per ulteriori dettagli sulla migrazione, consultare la documentazione ufficiale di Apple o contattare il nostro team di supporto.Il pacchetto può essere aggiunto utilizzando CocoaPods:
Xcode >= 12 (XCFramework)
- Se non lo hai già fatto, installa l'ultima versione di CocoaPods.
- Aggiungi questa riga al tuo Podfile:
pod 'PubConsent', '3.0.3'Usando Swift Package Manager
L'SDK iOS è disponibile tramite Swift Package Manager come libreria binaria. Per integrarlo nel tuo progetto iOS segui le istruzioni seguenti:
- Apri il tuo progetto Xcode
- Seleziona il tuo progetto nell'area di navigazione
- Seleziona il tuo progetto nella sezione PROJECT
- Seleziona le Dipendenze del Pacchetto
- Clicca sul pulsante +
- Copia l'url del pacchetto https://github.com/pubtech-ai/pubconsent-sdk-apple-os-spm nella barra di ricerca
- Seleziona il pacchetto pubconsent-ios-sdk dalla lista
- Clicca su Add Package
- Nella schermata Choose Package Products per il pacchetto pubconsent-ios-sdk clicca su Add Package
Manualmente
Il pacchetto può anche essere aggiunto manualmente come spiegato di seguito:
- Scarica e decomprimi l'ultima versione del nostro framework per Xcode >= 12: https://cdn.pubtech.ai/pubconsent-sdk-for-publishers/pubconsent-3.0.3-xcframework.zip
- In Xcode, seleziona il tuo progetto.
- Quindi, seleziona il tuo target dell'app.
- Clicca sulla scheda General.
- Scorri verso il basso fino alla sezione Embedded binaries.
- Dal Finder, trascina il file PubConsent.framework nella sezione Embedded binaries.
- Assicurati che la casella Copy items if needed sia selezionata e clicca su fine.
Condivisione consenso con una WebView
Se hai bisogno di riutilizzare il consenso collezionato attraverso la nostra SDK ad una WebView che punta al tuo sito web puoi consultare la documentazione Condivisione consensi alle WebView .
Inizializzare l'SDK
Il processo di inizializzazione preparerà l'SDK per le interazioni con l'utente e la tua applicazione. È importante lanciare l'inizializzazione dell'SDK il prima possibile poiché ciò rende possibile mostrare il CMP all'utente il prima possibile per chiedere il consenso, se necessario.
Nell'AppDelegate, assicurati di importare il modulo PubConsent, quindi chiama il metodo initialize e passa la tua chiave API:
import SwiftUI
import PubConsent
class AppDelegate: NSObject, UIApplicationDelegate {
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
let consentReadyHandler = ConsentReadyHandler()
let closeUIHandler = CloseUIHandler()
let openUIHandler = OpenUIHandler()
let googleConsentModeHandler = GoogleConsentModeHandler()
let errorHandler = ErrorHandler()
let cmpCallbacks = CmpCallbacks(
onConsentReadyCallback: consentReadyHandler,
onCloseUICallback: closeUIHandler,
onCmpUIOpenCallback: openUIHandler,
onErrorCallback: errorHandler,
onGoogleConsentModeCallback: googleConsentModeHandler
)
let parameters = CmpConfig(
id: "your-id", appName: "your-app-name", debug: false, callbacks: cmpCallbacks
)
PubConsentCMP.shared.configure(cmpConfiguration: parameters)
return true
}
}
@main
struct YourAppName: App {
@UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate
var body: some Scene {
WindowGroup {
ContentView()
}
}
}
class ConsentReadyHandler: OnConsentReadyCallback {
func onConsentReady(consentApiInstance: any PubConsent.ConsentApiInterface) {
if (consentApiInstance.getCmpType() == CmpType.TCF_V2_GDPR) {
if let apiInstance = consentApiInstance as? TCFGDPRConsentApi {
print("Google Consent Status \(apiInstance.isVendorConsentEnabled(vendorId: 755))")
print("Google Consent Mode ad_personalization granted? \(apiInstance.getGoogleConsentMode()[GoogleConsentModeType.ad_personalization] == .granted)")
} else {
print("Contact Pubtech since there is some unexpected problem (This can't happen but it's better to track every exception.")
}
}
if (consentApiInstance.getCmpType() == CmpType.GOOGLE_CONSENT_MODE) {
if let apiInstance = consentApiInstance as? GCMConsentApi {
print("Google Consent Mode ad_personalization granted? \(apiInstance.getGoogleConsentMode()[GoogleConsentModeType.ad_personalization] == .granted)")
}
}
}
}
class CloseUIHandler: OnCloseUICallback {
func onCmpUIClosed() {
print("CMP UI has been closed.")
}
}
class OpenUIHandler: OnOpenUICallback {
func onCmpUIOpen() {
print("CMP UI has been opened.")
}
}
// Implement the OnGoogleConsentModeCallback protocol
// Deprecated will be deleted in v3.0.0 use the api exposed with onConsentReady instead.
class GoogleConsentModeHandler: OnGoogleConsentModeCallback {
func update(googleConsentModeMap: [GoogleConsentModeType: GoogleConsentModeStatus]) {
print("Google consent mode updated:")
print("Status ad_personalization: \(googleConsentModeMap[GoogleConsentModeType.ad_personalization] == GoogleConsentModeStatus.granted)")
print("Status ad_storage: \(googleConsentModeMap[GoogleConsentModeType.ad_storage] == GoogleConsentModeStatus.granted)")
print("Status ad_user_data: \(googleConsentModeMap[GoogleConsentModeType.ad_user_data] == GoogleConsentModeStatus.granted)")
print("Status analytics_storage: \(googleConsentModeMap[GoogleConsentModeType.analytics_storage] == GoogleConsentModeStatus.granted)")
// Additional code to handle Google consent mode updates
}
}
class ErrorHandler: OnErrorCallback {
func onError(message: String) {
print("Error occurred: \(message)")
}
}Wrapping UIViewController
Nota: il metodo setupUI dovrebbe essere chiamato solo dal tuo UIViewController principale/di ingresso, che nella maggior parte dei casi dovrebbe essere una volta per lancio dell'app.
Per consentire all'SDK di visualizzare elementi dell'interfaccia utente e interagire con l'utente, devi fornire un riferimento al tuo UIViewController principale. Assicurati di importare il modulo PubConsent e di chiamare il metodo setupUI in Swift, setupUIWithContainerController in Objective-C, dell'SDK nel metodo viewDidLoad del tuo UIViewController principale:
import SwiftUI
struct ViewControllerRepresentable: UIViewControllerRepresentable {
let viewController = UIViewController()
func makeUIViewController(context: Context) -> some UIViewController {
return viewController
}
func updateUIViewController(_ uiViewController: UIViewControllerType, context: Context) {
// No implementation needed. Nothing to update.
}
}Chiamare direttamente l'interfaccia utente
Per far funzionare tutto e visualizzare gli elementi dell'interfaccia utente devi eseguire la seguente riga di codice: PubConsentCMP.shared.setupUI(containerController: viewControllerRepresentable.viewController)
Il seguente è un esempio di utilizzo:
import SwiftUI
import PubConsent
import WebKit
import UIKit
struct ContentView: View {
private let viewControllerRepresentable = ViewControllerRepresentable()
var body: some View {
ZStack {
VStack {
HStack(alignment: .bottom, content: {
VStack(alignment: .leading, content: {
Text("PubConsent CMP").font(.title)
Text("iOS").font(.title).colorInvert()
})
})
VStack(spacing: 30) {
Text("Azioni Demo:").font(.headline)
Button("Apri CMP") {
PubConsentCMP.shared.showNotice()
}
Button("Stampa Info") {
print("Il fornitore Google è abilitato? \(PubConsentCMP.shared.isVendorConsentEnabled(vendorId: 755))")
}
}
.padding(.top, 100)
.background {
viewControllerRepresentable
.frame(width: .zero, height: .zero)
}
.onAppear {
Task {
PubConsentCMP.shared.setupUI(containerController: viewControllerRepresentable.viewController)
}
}
}
}
}
}
#Preview {
ContentView()
}Integrare con App Tracking Transparency
Per ulteriori informazioni su come integrare PubConsent CMP con ATT puoi seguire la relativa App Tracking Transparency (iOS 14.5+).
Integrazione Google Consent Mode (v2)
Google Consent Mode ti permette di regolare il comportamento dei tag Google e del Firebase SDK in base allo stato del consenso dell'utente. Per conformarsi alla policy aggiornata di Google (EU user consent policy), il PubTech CMP supporta i quattro parametri obbligatori: ad_storage, analytics_storage, ad_user_data, e ad_personalization.
1. Imposta gli stati di consenso predefiniti (Default States) Prima che il CMP venga inizializzato, dovresti definire gli stati di consenso predefiniti nei file di configurazione della tua app.
iOS (Info.plist): Aggiungi le seguenti chiavi al tuo Info.plist:XML
<key>GOOGLE_ANALYTICS_DEFAULT_ALLOW_ANALYTICS_STORAGE</key> <false/>
<key>GOOGLE_ANALYTICS_DEFAULT_ALLOW_AD_STORAGE</key> <false/>
<key>GOOGLE_ANALYTICS_DEFAULT_ALLOW_AD_USER_DATA</key> <false/>
<key>GOOGLE_ANALYTICS_DEFAULT_ALLOW_AD_PERSONALIZATION_SIGNALS</key> <false/>2. Sincronizzazione del consenso con Firebase SDKDevi aggiornare il Firebase SDK ogni volta che ilPubTech CMP cattura o aggiorna il consenso dell'utente. Usa la callback onConsentReady per mappare i tipi di consenso di PubTech su Firebase.
import FirebaseAnalytics
class ConsentReadyHandler: OnConsentReadyCallback {
func onConsentReady(consentApiInstance: any PubConsent.ConsentApiInterface) {
let gcm = consentApiInstance.getGoogleConsentMode()
Analytics.setConsent([
.analyticsStorage: gcm[.analytics_storage] == .granted ? .granted : .denied,
.adStorage: gcm[.ad_storage] == .granted ? .granted : .denied,
.adUserData: gcm[.ad_user_data] == .granted ? .granted : .denied,
.adPersonalization: gcm[.ad_personalization] == .granted ? .granted : .denied
])
}
}3. Verifica Per verificare che i segnali vengano inviati correttamente:
Aggiungi -FIRAnalyticsVerboseLoggingEnabled agli argomenti di lancio (launch arguments) della tua app in Xcode.
SDK APIs
Di seguito è riportata la struct che devi inizializzare e fornire al metodo configure PubConsent.shared.configure
Struct: CmpConfig
Descrizione: Rappresenta le impostazioni di configurazione per la Piattaforma di Gestione del Consenso (CMP).
Proprietà:
- id: Una stringa che rappresenta l'ID del CMP (ottenuto dal dashboard di PubTech).
- appName: Una stringa che rappresenta il nome dell'applicazione.
- debug: Un booleano che indica se il CMP è in modalità debug.
- callbacks: Un'istanza opzionale di CmpCallbacks contenente le funzioni di callback.
Metodi:
- init(id:appName:debug:callbacks:): Inizializza una nuova istanza di CmpConfig.
Struct: CmpCallbacks
Descrizione: Contiene funzioni di callback per i principali eventi di PubConsentCMP.
Proprietà:
- onConsentReadyCallback: Una funzione di callback chiamata quando il consenso è pronto.
- onCloseUICallback: Una funzione di callback chiamata quando l'interfaccia utente del CMP viene chiusa.
- onCmpUIOpenCallback: Una funzione di callback chiamata quando l'interfaccia utente del CMP viene aperta.
- onErrorCallback: Una funzione di callback chiamata quando si verifica un errore.
- onGoogleConsentModeCallback: Una funzione di callback chiamata quando la modalità di consenso di Google viene aggiornata.
PubConsent ConsentApiInterface
Utilizzando l'API esposta tramite onConsentReadyCallback potete verificare tramite il metodo getCmpType() quali delle seguenti implementazioni avete a disposizione (questa scelta dipende dalla configurazione salvata attraverso il configuratore PubConsent). Di seguito vi mostriamo le API per ogni CMP Type che offriamo seguenti metodi sono accessibili tramite l'istanza consentApiInstance: any PubConsent.ConsentApiInterface disponibile come parametro alla callback: onConsentReadyCallback
API disponibili per il CmpType.TCF_V2_GDPR
Metodo: isVendorConsentEnabled(vendorId:)
Descrizione: Questo metodo verifica se il consenso è abilitato per un determinato fornitore.
Parametri:
- vendorId: Un intero che rappresenta l'ID del fornitore.
Ritorni:
- Bool: Ritorna true se il consenso è abilitato per il fornitore specificato, altrimenti false.
Metodo: isPurposeConsentEnabled(purposeId:)
Descrizione: Questo metodo verifica se il consenso è abilitato per uno scopo specifico.
Parametri:
- purposeId: Un intero che rappresenta l'ID dello scopo.
Ritorni:
- Bool: Ritorna true se il consenso è abilitato per lo scopo specificato, altrimenti false.
Metodo: isFeatureCookiesEnabled()
Descrizione: Questo metodo verifica se il consenso è abilitato per i cookie delle funzionalità.
Ritorni:
- Bool: Ritorna true se il consenso è abilitato per i cookie delle funzionalità, altrimenti false.
Metodo: isUserExperienceCookiesEnabled()
Descrizione: Questo metodo verifica se il consenso è abilitato per i cookie dell'esperienza utente.
Ritorni:
- Bool: Ritorna true se il consenso è abilitato per i cookie dell'esperienza utente, altrimenti false.
Metodo: isMeasurementCookiesEnabled()
Descrizione: Questo metodo verifica se il consenso è abilitato per i cookie di misurazione.
Ritorni:
- Bool: Ritorna true se il consenso è abilitato per i cookie di misurazione, altrimenti false.
Metodo: getGoogleConsentMode()
Descrizione: Questo metodo recupera lo stato della modalità di consenso per i servizi di Google.
Ritorni:
- [GoogleConsentModeType: GoogleConsentModeStatus]?: Ritorna un dizionario contenente lo stato della modalità di consenso per i diversi servizi di Google. Ritorna nil se le informazioni sulla modalità di consenso non sono disponibili.
API disponibili per il CmpType.Method: getGoogleConsentMode()
Description: This method retrieves the consent mode status for Google services.
Returns:
- [GoogleConsentModeType: GoogleConsentModeStatus]?: Returns a dictionary containing the consent mode status for different Google services. Returns nil if the consent mode information is not available.
Metodo: getGoogleConsentMode()
Descrizione: Questo metodo recupera lo stato della modalità di consenso per i servizi di Google.
Ritorni:
- [GoogleConsentModeType: GoogleConsentModeStatus]?: Ritorna un dizionario contenente lo stato della modalità di consenso per i diversi servizi di Google. Ritorna nil se le informazioni sulla modalità di consenso non sono disponibili.
PubConsent CMP API condivise
I seguenti metodi sono accessibili tramite l'istanza PubConsentCMP.shared.
Metodo: setUserRejectedAll(containerController: viewControllerRepresentable.viewController)
Descrizione: Questo metodo verrà utilizzato per l'integrazione della trasparenza del monitoraggio delle app (ATT). Invece di chiamare il metodo setupUI quando lo stato ATT viene negato, il codice dell'app può eseguire questo metodo se è necessario impostare tutto nel CMP come rifiutato, altrimenti potete scegliere anche di non far esprimere nessun consenso.
Metodo: disableCmpPopup()
Descrizione: Quando il CMP è già mostrato all'utente e l'ATT è negato è possibile disabilitare il popup CMP nascondendolo chiamando questo metodo.
Metodo: enableCmpPopup(containerController: UIViewController)
Descrizione: Questo metodo è necessario per riabilitare il popup precedentemente disabilitato.
Metodo: resetUserPreferences()
Descrizione: Questo metodo è utile per cancellare le preferenze espresse dall'utente.