Compliant with GDPR, CCPA, COPPA, LGPD, PECR, PDPA, PIPEDA, and more.
UniConsent CMP è un pacchetto per la gestione del consenso GDPR IAB TCF 2.4 su iOS. Nella directory "UniConsentDemo" trovi un'app dimostrativa integrata con UniConsent CMP.
Aggiungi UniConsent.xcframework al tuo progetto. Nella sezione General > Frameworks, Libraries, and Embedded Content del tuo target, imposta UniConsent.xcframework su Embed & Sign.
Prima di integrare l'SDK, personalizza l'aspetto del banner del consenso nella Dashboard UniConsent per adattarlo al tuo brand e ottimizzare i tassi di consenso.
Vai a Projects → Select your Project → Settings → Step 5: UI & Style Settings per configurare:
Per un controllo più preciso, aggiungi CSS personalizzato nel campo CSS Content del passaggio 5. È consigliato per far sembrare il banner parte integrante della tua app e ottenere il miglior tasso di consenso:
/* Example: Style the accept button to match your brand */
.unic-btn-accept {
background-color: #4CAF50;
border-radius: 8px;
font-weight: 600;
}
/* Example: Adjust banner font */
.unic-banner {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
}
/* Example: Make the reject button less prominent */
.unic-btn-reject {
background-color: transparent;
border: 1px solid #ccc;
color: #666;
}
Suggerimento: un'interfaccia del consenso coerente con il brand e integrata nella tua app ottiene in genere tassi di consenso più elevati. Gli utenti tendono a interagire in modo più positivo con un banner che rispecchia l'aspetto e lo stile che si aspettano.
Per usare UniConsent CMP nella tua app, segui questi passaggi:
Inizializza la CMP con un App ID fornito dal tuo account manager:
import UniConsent
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
// Init CMP with appId
// initialize() loads the location, config and vendor list over the network: keep it off the main thread
DispatchQueue.global(qos: .userInitiated).async {
UniConsentCMP.shared.initialize(apiId: "YOUR_APP_ID_CHANGE_THIS")
}
return true
}
Mostra l'interfaccia della CMP:
// Display CMP as full-screen modal (default)
UniConsentCMP.shared.setUIStage(.GDPRFirstScreen)
UniConsentCMP.shared.launchCMP(rootVC: self)
// Display CMP as a modal bottom sheet
UniConsentCMP.shared.launchCMP(rootVC: self, displayMode: .modalSheet)
// Display CMP as a modal bottom sheet at 60% of the available height
UniConsentCMP.shared.launchCMP(rootVC: self, displayMode: .modalSheet, heightRatio: 0.6)
// Display CMP as a center dialog
UniConsentCMP.shared.launchCMP(rootVC: self, displayMode: .dialog)
// Display CMP as a center dialog at 80% width and 60% height
UniConsentCMP.shared.launchCMP(rootVC: self, displayMode: .dialog, widthRatio: 0.8, heightRatio: 0.6)
Modalità di visualizzazione disponibili (CMPDisplayMode):
.fullScreen: presentazione modale a schermo intero (predefinita).modalSheet: bottom sheet con maniglia di trascinamento (iOS 15+).dialog: finestra di dialogo centrata con sfondo oscuratoDisponibile dalla versione 26.8.0 dell'SDK.
Entrambi i rapporti sono facoltativi: ogni modalità di visualizzazione funziona anche senza. Passa un rapporto (una frazione dello schermo, limitata all'intervallo 0.1...1.0) solo per sovrascrivere le dimensioni predefinite:
| Parametro | Si applica a | Valore predefinito se omesso |
|---|---|---|
heightRatio | .modalSheet, .dialog | Sheet: 90% dell'altezza disponibile. Dialog: 70% dello schermo |
widthRatio | Solo .dialog | 90% della larghezza dello schermo, fino a 500pt |
I rapporti che non si applicano alla modalità di visualizzazione scelta vengono ignorati (.fullScreen li ignora entrambi). Su iOS 16+ il foglio usa esattamente il valore di heightRatio; su iOS 15 si ricorre al detent di sistema medium (rapporto ≤ 0.5) o large (rapporto > 0.5).
Ascolta gli eventi del ciclo di vita dell'SDK con CMPEventHandler. È il modo consigliato per sapere quando l'SDK ha completato l'inizializzazione, quando l'interfaccia viene mostrata e quando viene chiusa.
Eventi disponibili (CMPEventType):
.sdkInit: inizializzazione dell'SDK avviata.ready: inizializzazione dell'SDK completata (GEO, configurazione e fornitori caricati).uiDisplay: l'interfaccia del consenso viene mostrata.uiClose: l'interfaccia del consenso viene chiusaSottoscrivi gli eventi prima di chiamare initialize() per riceverli tutti:
import UniConsent
@main
class AppDelegate: UIResponder, UIApplicationDelegate, CMPEventHandler {
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
UniConsentCMP.shared.subscribe(self)
DispatchQueue.global(qos: .userInitiated).async {
UniConsentCMP.shared.initialize(apiId: "YOUR_APP_ID")
}
return true
}
func handle(event: CMPEvent) {
switch event.type {
case .ready:
// SDK is ready — check consent and launch CMP if needed
// events arrive on the thread that called initialize(): show UI on the main thread
DispatchQueue.main.async {
if let rootVC = UIApplication.shared.connectedScenes
.compactMap({ ($0 as? UIWindowScene)?.keyWindow?.rootViewController }).first {
UniConsentCMP.shared.launchCMPIfNeeded(rootVC: rootVC)
}
}
case .uiClose:
// User finished interacting with consent UI
print("TC String:", UniConsentCMP.shared.getTCString())
default:
break
}
}
}
Puoi anche effettuare la sottoscrizione da un view controller:
class ViewController: UIViewController, CMPEventHandler {
override func viewDidLoad() {
super.viewDidLoad()
UniConsentCMP.shared.subscribe(self)
}
func handle(event: CMPEvent) {
switch event.type {
case .uiDisplay:
print("CMP UI is now visible")
case .uiClose:
print("Consent given, vendor 1 allowed:", UniConsentCMP.shared.isAllowVendorById(vendorId: 1))
default:
break
}
}
}
Per annullare la sottoscrizione:
UniConsentCMP.shared.unsubscribe(self)
Puoi anche rilevare la chiusura del consenso con CMPUIDelegate:
class ViewController: UIViewController, CMPUIDelegate {
func showCMP() {
UniConsentCMP.shared.view.delegate = self
UniConsentCMP.shared.setUIStage(.GDPRFirstScreen)
UniConsentCMP.shared.launchCMP(rootVC: self, displayMode: .modalSheet)
}
func onDismiss() {
// Called when the user closes the consent UI
print("TC String:", UniConsentCMP.shared.getTCString())
}
}
Verifica automaticamente se il consenso è scaduto quando la vendorList viene aggiornata:
// Automatic check if consent is expired when vendorList updates
if UniConsentCMP.shared.shouldRequestConsent() {
UniConsentCMP.shared.launchCMP(rootVC: self)
}
Ottieni la tcString, se necessario:
// Get tcString if required
UniConsentCMP.shared.getTCString()
Leggi lo stato del consenso:
// Check consent for a specific IAB purpose
UniConsentCMP.shared.isAllowPurposeById(purposeId: 1)
// Check consent for a specific IAB vendor
UniConsentCMP.shared.isAllowVendorById(vendorId: 1)
// Get all allowed purpose/vendor IDs
UniConsentCMP.shared.getAllowedPurposeIds()
UniConsentCMP.shared.getAllowedVendorIds()
// Check if GDPR applies
UniConsentCMP.shared.gdprApplies
// Check if any consent has been given
UniConsentCMP.shared.isConsentGiven()
Reimposta lo stato del consenso, se necessario:
// Reset consent status if required
UniConsentCMP.shared.clearConsentData()
Disponibile dalla versione 26.7.0 dell'SDK. Se crei una tua interfaccia di primo livello per il consenso invece di mostrare la webview della CMP, puoi salvare il consenso direttamente:
// Grant consent for all purposes, special features and vendors
let saved = UniConsentCMP.shared.agreeAll()
// Reject all purposes, special features and vendors
let saved = UniConsentCMP.shared.rejectAll()
Entrambe le API salvano gli stessi valori di consenso del flusso dell'interfaccia della CMP (chiavi IAB TCF, additional consent e segnali di Consent Mode) e inviano lo stesso evento .uiClose ai sottoscrittori.
Per gli utenti di Stati Uniti e Canada, entrambe le API salvano anche la scelta CCPA, US State Privacy e IAB TCF Canada che si applica a loro, con le stesse regole dell'interfaccia della CMP, e scrivono le chiavi IAB GPP e US Privacy. Attiva le modalità API-Only nelle impostazioni del progetto nella dashboard di UniConsent, così il banner della CMP non viene mostrato in quelle regioni.
Salvano anche la scelta delle categorie di cookie dove si applica un banner di categorie di cookie (tutte le categorie, oppure solo Strettamente necessari), e le finalità e i fornitori personalizzati del progetto.
Per sapere quale primo livello mostrare, chiama getPolicy() (dalla versione 26.10.0 dell'SDK). Restituisce la policy che si applica all'utente, con le stesse regole della CMP: gdpr (IAB TCF), tcfca (IAB TCF Canada), uss (US State Privacy), ccpa, categories (vedi Categorie di cookie più avanti) o none.
let cmp = UniConsentCMP.shared
if cmp.shouldRequestConsent() {
// l'utente deve fare una scelta: mostra il tuo primo livello per questa policy
let policy = cmp.getPolicy() // gdpr, tcfca o categories
}
Nota: queste API recuperano la vendor list e la configurazione del progetto tramite rete in modo sincrono e restituiscono
falsese non è stato possibile salvare il consenso (ad esempio offline). Chiamale dopoinitialize()e al di fuori del main thread.Importante: il tuo primo livello personalizzato deve comunque rispettare i requisiti IAB TCF (indicare le finalità e i fornitori e offrire le opzioni di accettazione e rifiuto con uguale evidenza). Gli utenti devono comunque poter aprire l'interfaccia completa della CMP (
launchCMP()) per effettuare scelte granulari.
Se la tua app apre una WKWebView che carica una pagina web con il tag CMP di UniConsent, puoi passare lo stato del consenso nativo in modo che il tag CMP riconosca il consenso esistente e non mostri di nuovo il banner.
Chiama syncConsent(to:) prima di caricare la pagina web:
import WebKit
import UniConsent
let webView = WKWebView(frame: .zero, configuration: WKWebViewConfiguration())
// Inject native consent before page load
UniConsentCMP.shared.syncConsent(to: webView)
// Then load your web page
webView.load(URLRequest(url: URL(string: "https://example.com")!))
// Initialize with event handler
@interface AppDelegate () <CMPEventHandler>
@end
@implementation AppDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
[[UniConsentCMP shared] subscribe:self];
// initialize loads the location, config and vendor list over the network: keep it off the main thread
dispatch_async(dispatch_get_global_queue(QOS_CLASS_USER_INITIATED, 0), ^{
[[UniConsentCMP shared] initializeWithApiId:@"YOUR_APP_ID"];
});
return YES;
}
- (void)handleWithEvent:(CMPEvent *)event {
switch (event.type) {
case CMPEventTypeReady:
NSLog(@"CMP ready");
break;
case CMPEventTypeUiClose:
NSLog(@"TC String: %@", [[UniConsentCMP shared] getTCString]);
break;
default:
break;
}
}
@end
// Display CMP (full screen by default)
[UniConsentCMP.shared launchCMPWithRootVC:self];
// Display CMP with a specific display mode
// Use CMPDisplayModeFullScreen, CMPDisplayModeModalSheet, or CMPDisplayModeDialog
[UniConsentCMP.shared launchCMPWithRootVC:self displayMode:CMPDisplayModeModalSheet];
Apri la CMP su una schermata specifica, ad esempio da un link "Impostazioni privacy" della tua app. La schermata richiesta si apre sempre. Per gli utenti negli Stati Uniti, le schermate delle impostazioni aprono le impostazioni CCPA o US State Privacy che si applicano a loro. Gli utenti in Canada vedono la versione IAB TCF Canada delle schermate IAB TCF.
| Schermata | Mostra |
|---|---|
.GDPRFirstScreen | Primo livello (banner) |
.GDPRSecondScreen | Impostazioni (finalità) |
.GDPRVendorsScreen | Fornitori |
.CCPAFirstScreen | Primo livello CCPA |
.CCPASecondScreen | Impostazioni CCPA |
.USStateFirstScreen | Primo livello US State Privacy |
.USStateSecondScreen | Impostazioni US State Privacy |
.CategoriesFirstScreen | Primo livello delle categorie di cookie (banner) |
.CategoriesSecondScreen | Impostazioni delle categorie di cookie |
let cmp = UniConsentCMP.shared
// aprire la schermata delle impostazioni
cmp.setUIStage(.GDPRSecondScreen)
cmp.launchCMP(rootVC: self)
// aprire la CMP solo quando serve il consenso (UE e IAB TCF Canada); restituisce se è stata aperta
let opened = cmp.launchCMPIfNeeded(rootVC: self)
// log di debug dell'SDK e della pagina CMP; usa .error (predefinito) nelle build di produzione
cmp.setLogLevel(.debug)
// solo per i test: mostrare la CMP come per un utente di un'altra regione, "EU", "CA" (Canada), "CAQC" (Québec), "US" più un codice di stato come "USCA" o "USTX", "BR", "CN", "ZA", "VN" o qualsiasi altro codice paese, oppure "N" (fuori da queste regioni). Si applica anche a getPolicy() e a shouldRequestConsent(); da rimuovere nelle build di produzione
cmp.setTestRegion("CA")
// chiudere la CMP se è aperta
cmp.dismissCMP()
// l'utente ha fatto una scelta: IAB TCF, CCPA, US State Privacy o IAB TCF Canada
let given = cmp.isConsentGiven()
// giorni dalla creazione del consenso IAB TCF, 0 se non c'è
let days = cmp.getConsentAge()
// regione dell'utente e, per Stati Uniti e Canada, il codice dello stato o della provincia (vuoto se sconosciuto)
let geo = cmp.getGEO()
let state = cmp.getGEOState()
La CMP salva le chiavi IAB GPP e la chiave US Privacy in gli UserDefaults dell'app, come definite dalle specifiche IAB. Gli SDK pubblicitari della tua app le leggono da lì; non servono modifiche al codice. Le chiavi GPP vengono scritte quando GPP, US State Privacy o IAB TCF Canada è attivato nelle impostazioni del progetto nella dashboard di UniConsent. La chiave US Privacy viene scritta ogni volta che il CCPA è attivato.
| Chiave | Valore |
|---|---|
IABGPP_HDR_Version | Versione GPP (1) |
IABGPP_HDR_Sections | ID delle sezioni nella stringa GPP, separati da _ |
IABGPP_HDR_GppString | La stringa GPP completa |
IABGPP_GppSID | ID delle sezioni che si applicano all'utente, separati da _, oppure -1 se non se ne applica nessuna |
IABGPP_2_String | Stringa IAB TCF EU, quando si applica il GDPR |
IABGPP_5_String | Stringa IAB TCF Canada, quando si applica il TCF Canada |
IABGPP_6_String | Stringa US Privacy, quando si applica il CCPA |
IABGPP_7_String | Stringa US National (usnat), quando si applica US State Privacy o il CCPA |
IABGPP_8_String a IABGPP_27_String | La sezione dello stato dell'utente (8 California a 27 Rhode Island), quando si applica US State Privacy, o la California con il CCPA, secondo l'impostazione GPP Sections |
IABUSPrivacy_String | Stringa US Privacy ogni volta che il CCPA è attivato: la scelta dell'utente nella regione CCPA, altrimenti 1--- |
Le chiavi vengono aggiornate a ogni caricamento della CMP e dopo ogni scelta di consenso. Quali utenti ricevono le chiavi IABGPP_ dipende da GPP Signals nelle impostazioni del progetto: gli utenti in Canada sempre (IAB TCF Canada), quelli negli Stati Uniti quando US è attivo e quelli nell'UE quando EU è attivo. Gli utenti non coperti da alcuna regione ricevono le chiavi senza sezioni finché US o EU è attivo, altrimenti nessuna chiave. Per leggerle direttamente:
let gppString = UserDefaults.standard.string(forKey: "IABGPP_HDR_GppString") ?? ""
let gppSid = UserDefaults.standard.string(forKey: "IABGPP_GppSID") ?? ""
Le app supportano le stesse opzioni per Stati Uniti e Canada dei siti web: CCPA, US State Privacy (con l'elenco degli stati e le impostazioni GPP Sections e MSPA) e IAB TCF Canada. shouldRequestConsent() restituisce true per gli utenti del Canada a cui si applica IAB TCF Canada finché non fanno una scelta. La privacy negli Stati Uniti è di tipo opt-out, quindi agli utenti statunitensi non viene chiesto da sé: vedono il banner o le impostazioni USA quando la tua app apre la CMP, ad esempio da un link alle impostazioni privacy. Fino ad allora, quando il CCPA o US State Privacy è attivato, l'SDK scrive le chiavi US Privacy e GPP predefinite per gli utenti statunitensi senza mostrare nulla: nessuna opposizione, oppure opposizione quando il tracciamento pubblicitario è disattivato sul dispositivo. US State Privacy parte disattivato nei nuovi progetti Mobile App; attivalo nella dashboard.
Quando l'utente ha disattivato il tracciamento pubblicitario sul dispositivo, la CMP lo considera un'opposizione statunitense alla vendita, alla condivisione e alla pubblicità mirata, come fa Global Privacy Control sui siti web. Su iOS è il tracciamento non consentito in App Tracking Transparency; su Android un ID pubblicità eliminato o la limitazione del tracciamento pubblicitario, letti tramite i servizi Google Play quando la tua app li include. Una scelta che l'utente salva poi nel banner ha la precedenza.
L'SDK restituisce anche le stringhe salvate:
let gppString = UniConsentCMP.shared.getGPPString()
let gppSid = UniConsentCMP.shared.getGPPSID()
let usPrivacy = UniConsentCMP.shared.getUSPrivacyString()
Disponibile dalla versione 26.10.0 dell'SDK. Dove una regione usa le categorie di cookie invece di IAB TCF o delle policy USA, la CMP mostra un banner con quattro categorie: Strettamente necessari, Prestazioni, Funzionalità, e Targeting o pubblicità. Si applica a:
Le categorie opt-in partono con solo Strettamente necessari attiva, e shouldRequestConsent() restituisce true finché l'utente non fa una scelta, e di nuovo dopo che modifichi la versione della configurazione. Le categorie opt-out partono con tutte le categorie attive (Targeting disattivato quando il tracciamento pubblicitario è disattivato sul dispositivo negli Stati Uniti), e l'app non chiede da sé: gli utenti le modificano dal tuo link alle impostazioni privacy. L'opt-out si applica a una regola opt-out per gli altri paesi e, nelle app, a un progetto Consent Categories negli Stati Uniti.
Apri le schermate delle categorie con .CategoriesFirstScreen (banner) e .CategoriesSecondScreen (impostazioni). setTestRegion() accetta anche BR, CN, ZA, VN e altri codici paese, per provare queste regioni.
Disponibile dalla versione 26.10.0 dell'SDK. Le finalità personalizzate e i fornitori personalizzati che aggiungi nelle impostazioni del progetto nella dashboard di UniConsent compaiono nelle schermate della CMP: le finalità personalizzate nel primo livello e nelle impostazioni IAB TCF e nelle impostazioni delle categorie di cookie, i fornitori personalizzati nell'elenco dei fornitori IAB TCF. Nelle impostazioni CCPA e US State Privacy sono elencate solo le finalità personalizzate sensibili. Nelle impostazioni delle categorie di cookie i fornitori personalizzati seguono la categoria Targeting o pubblicità. Dove IAB TCF non si applica (categorie di cookie e Stati Uniti), i fornitori personalizzati sono elencati in sola lettura nell'elenco dei fornitori del menu, e nelle impostazioni delle categorie di cookie sotto Targeting o pubblicità.
Per avviare o fermare i tuoi SDK in base a essi, chiedi all'SDK se l'app può usare ora una finalità personalizzata o un fornitore personalizzato. La risposta segue la policy dell'utente, con le stesse regole che la CMP usa per i tag:
let cmp = UniConsentCMP.shared
if cmp.isCustomPurposeConsented(1) {
// avvia l'SDK coperto dalla tua finalità personalizzata 1
}
let vendorAllowed = cmp.isCustomVendorConsented(2)
let all = cmp.getCustomConsents() // ["purposes": ["1": true], "vendors": ["2": false]]
Richiamale dopo la chiusura della CMP o una modifica del consenso. Gli ID che il progetto non ha, e tutti gli ID prima che l'SDK sia pronto, restituiscono false.
La CMP può elencare gli SDK di terze parti della tua app (reti pubblicitarie, analisi, attribuzione e altri) con la loro azienda, il loro utilizzo e la loro informativa sulla privacy. Gli utenti li vedono nell'elenco dei fornitori, in sola lettura in tutte le regioni: non ci sono interruttori e la tua app continua ad attivare o disattivare ogni SDK in base alle scelte dell'utente per le finalità o le categorie di cookie.
Per impostare l'elenco, attiva Enable Third-party SDKs in Step 4: Advanced Features del tuo progetto app, scegli i tuoi SDK nella scheda Third-party SDKs o aggiungine di tuoi, poi salva e pubblica. Non serve codice nella tua app.
Configura i valori chiave (KV) predefiniti dello stato del consenso:
<key>FIREBASE_ANALYTICS_COLLECTION_ENABLED</key> <false/>
<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/>
Controlla gli analytics in base ai flag del consenso:
// SDK Version <= 25.6.1
public func onDismiss() {
if(UniConsentCMP.shared.isAllowPurposeById(purposeId: 1)) {
Analytics.setConsent([
.analyticsStorage: .granted,
.adStorage: .granted,
.adUserData: .granted,
.adPersonalization: .granted,
])
Analytics.setAnalyticsCollectionEnabled(true);
} else {
Analytics.setConsent([
.analyticsStorage: .denied,
.adStorage: .denied,
.adUserData: .denied,
.adPersonalization: .denied,
])
Analytics.setAnalyticsCollectionEnabled(false);
}
// other logic such as send analytics events
}
Trova maggiori informazioni in Set up consent mode for apps
setCustomConsent() per salvare la scelta su una finalità personalizzata da una schermata della tua app, come una casella per il tracciamento dell'apertura delle email; isCustomPurposeConsented() accetta anche l'ID della finalità personalizzata impostato nella dashboardemail viene inviato come email_hash (SHA-256); l'indirizzo non viene salvato né inviatogetGPPString(), getGPPSID() e getUSPrivacyString().USStateSecondScreen; nuovi launchCMPIfNeeded(), setLogLevel() e getGEOState().CCPAFirstScreen e .USStateFirstScreen; nuovo setTestRegion() per provare la CMP come un utente di un'altra regione, ad esempio il Canada.CategoriesFirstScreen e .CategoriesSecondScreengetPolicy(); agreeAll() e rejectAll() salvano anche le categorie di cookie, le finalità personalizzate e i fornitori personalizzatisetTestRegion() accetta anche BR, CN, ZA, VN e altri codici paese, e si applica a getPolicy() e a shouldRequestConsent()isCustomPurposeConsented(), isCustomVendorConsented() e getCustomConsents(): le finalità e i fornitori personalizzati che l'app può usare ora secondo la policy dell'utenteLeggi sulla privacy, consenso e conformità, poche email al mese.