Compliant with GDPR, CCPA, COPPA, LGPD, PECR, PDPA, PIPEDA, and more.
UniConsent CMP is a package for handling GDPR IAB TCF 2.4 consent management in iOS. You can find a demo app integrated with UniConsent CMP in the "UniConsentDemo" directory.
Add UniConsent.xcframework into your project. In your target's General > Frameworks, Libraries, and Embedded Content, set UniConsent.xcframework to Embed & Sign.
Before integrating the SDK, customize the consent banner appearance in the UniConsent Dashboard to match your brand and optimize consent rates.
Go to Projects → Select your Project → Settings → Step 5: UI & Style Settings to configure:
For more precise control, add custom CSS in the CSS Content field under Step 5. This is recommended to make the banner feel native to your app and achieve the best consent rate:
/* 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;
}
Tip: A well-branded consent UI that feels native to your app typically achieves higher consent rates. Users are more likely to engage positively with a banner that matches the look and feel they expect.
To use the UniConsent CMP in your app, follow these steps:
Initialize the CMP with an App ID from your 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
}
Display the CMP UI:
// 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)
Available display modes (CMPDisplayMode):
.fullScreen — Full-screen modal presentation (default).modalSheet — Bottom sheet with drag handle (iOS 15+).dialog — Centered dialog with dimmed backgroundAvailable from SDK version 26.8.0.
Both ratios are optional — every display mode works without them. Pass a ratio (a fraction of the screen, clamped to 0.1...1.0) only to override the default size:
| Parameter | Applies to | Default when omitted |
|---|---|---|
heightRatio | .modalSheet, .dialog | Sheet: 90% of the available height. Dialog: 70% of the screen |
widthRatio | .dialog only | 90% of the screen width, up to 500pt |
Ratios that don't apply to the chosen display mode are ignored (.fullScreen ignores both). On iOS 16+ the sheet uses the exact heightRatio; iOS 15 falls back to the system medium detent (ratio ≤ 0.5) or large detent (ratio > 0.5).
Listen for SDK lifecycle events with CMPEventHandler. This is the recommended way to know when the SDK has finished initializing, when the UI is displayed, and when it is closed.
Available events (CMPEventType):
.sdkInit — SDK initialization started.ready — SDK initialization completed (GEO, config, and vendors loaded).uiDisplay — Consent UI is displayed.uiClose — Consent UI is closedSubscribe to events before calling initialize() to receive all events:
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
}
}
}
You can also subscribe from a 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
}
}
}
To unsubscribe:
UniConsentCMP.shared.unsubscribe(self)
You can also listen for consent dismiss with 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())
}
}
Automatically check if consent is expired when the vendorList updates:
// Automatic check if consent is expired when vendorList updates
if UniConsentCMP.shared.shouldRequestConsent() {
UniConsentCMP.shared.launchCMP(rootVC: self)
}
Get the tcString if required:
// Get tcString if required
UniConsentCMP.shared.getTCString()
Read the consent status:
// 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()
Reset consent status if required:
// Reset consent status if required
UniConsentCMP.shared.clearConsentData()
Available from SDK version 26.7.0. If you build your own first-layer consent UI instead of showing the CMP webview, you can save consent directly:
// 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()
Both APIs save the same consent values as the CMP UI flow (IAB TCF keys, additional consent and consent mode signals) and fire the same .uiClose event for subscribers.
For users in the US and Canada, both APIs also save the CCPA, US State Privacy and IAB TCF Canada choice that applies to them, by the same rules as the CMP UI, and write the IAB GPP and US Privacy keys. Turn on the API-only modes in the project settings of the UniConsent dashboard so the CMP banner is not shown for those regions.
They also save the cookie categories choice where a cookie categories banner applies (every category, or only Strictly Necessary), and the project's custom purposes and custom vendors.
To know which first layer to show, call getPolicy() (from SDK version 26.10.0). It returns the policy that applies to the user, by the same rules as the CMP: gdpr (IAB TCF), tcfca (IAB TCF Canada), uss (US State Privacy), ccpa, categories (see Cookie Categories below) or none.
let cmp = UniConsentCMP.shared
if cmp.shouldRequestConsent() {
// the user needs to make a choice: show your first layer for this policy
let policy = cmp.getPolicy() // gdpr, tcfca or categories
}
Note: These APIs fetch the vendor list and project config over the network synchronously and return
falseif consent could not be saved (e.g. offline). Call them afterinitialize()and off the main thread.Important: Your custom first layer must still meet IAB TCF requirements (disclose purposes and vendors, and offer accept and reject with equal prominence). Users should still be able to open the full CMP UI (
launchCMP()) for granular choices.
If your app opens a WKWebView that loads a web page with the UniConsent CMP tag, you can pass the native consent status so the CMP tag recognises existing consent and does not show the banner again.
Call syncConsent(to:) before loading the web page:
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];
Open the CMP at a specific screen, for example from a "Privacy settings" link in your app. The screen you ask for always opens. For US users, the settings screens open the CCPA or US State Privacy settings that apply to them. Users in Canada see the IAB TCF Canada version of the IAB TCF screens.
| Screen | Shows |
|---|---|
.GDPRFirstScreen | First layer (banner) |
.GDPRSecondScreen | Settings (purposes) |
.GDPRVendorsScreen | Vendors |
.CCPAFirstScreen | CCPA first layer |
.CCPASecondScreen | CCPA settings |
.USStateFirstScreen | US State Privacy first layer |
.USStateSecondScreen | US State Privacy settings |
.CategoriesFirstScreen | Cookie categories first layer (banner) |
.CategoriesSecondScreen | Cookie categories settings |
let cmp = UniConsentCMP.shared
// open the settings screen
cmp.setUIStage(.GDPRSecondScreen)
cmp.launchCMP(rootVC: self)
// open the CMP only when consent is needed (EU and IAB TCF Canada), returns whether it opened
let opened = cmp.launchCMPIfNeeded(rootVC: self)
// debug logs from the SDK and the CMP page, use .error (default) in release builds
cmp.setLogLevel(.debug)
// for testing only: show the CMP as for a user in another region, "EU", "CA" (Canada), "CAQC" (Quebec), "US" plus a state code such as "USCA" or "USTX", "BR", "CN", "ZA", "VN" or any other country code, or "N" (outside these regions). It also applies to getPolicy() and shouldRequestConsent(); remove it in release builds
cmp.setTestRegion("CA")
// close the CMP if it is open
cmp.dismissCMP()
// the user has made a choice: IAB TCF, CCPA, US State Privacy or IAB TCF Canada
let given = cmp.isConsentGiven()
// days since the IAB TCF consent was created, 0 when there is none
let days = cmp.getConsentAge()
// the user's region and, for the US and Canada, the state or province code (empty when unknown)
let geo = cmp.getGEO()
let state = cmp.getGEOState()
The CMP stores the IAB GPP keys and the US Privacy key in the app's UserDefaults, as the IAB specifications define them. Ad SDKs in your app read them from there; no code changes are needed. The GPP keys are written when GPP, US State Privacy or IAB TCF Canada is enabled in the project settings of the UniConsent dashboard. The US Privacy key is written whenever CCPA is enabled.
| Key | Value |
|---|---|
IABGPP_HDR_Version | GPP version (1) |
IABGPP_HDR_Sections | Section IDs in the GPP string, separated by _ |
IABGPP_HDR_GppString | The full GPP string |
IABGPP_GppSID | Section IDs that apply to the user, separated by _, or -1 when none apply |
IABGPP_2_String | IAB TCF EU string, when GDPR applies |
IABGPP_5_String | IAB TCF Canada string, when Canada TCF applies |
IABGPP_6_String | US Privacy string, when CCPA applies |
IABGPP_7_String | US National (usnat) string, when US State Privacy or CCPA applies |
IABGPP_8_String to IABGPP_27_String | The section for the user's state (8 California to 27 Rhode Island), when US State Privacy applies, or California under CCPA, following the GPP Sections setting |
IABUSPrivacy_String | US Privacy string whenever CCPA is enabled: the user's choice in the CCPA region, otherwise 1--- |
The keys are updated each time the CMP loads and after every consent choice. When GPP is turned off, the IABGPP_ keys are removed. To read them yourself:
let gppString = UserDefaults.standard.string(forKey: "IABGPP_HDR_GppString") ?? ""
let gppSid = UserDefaults.standard.string(forKey: "IABGPP_GppSID") ?? ""
Apps support the same US and Canada options as websites: CCPA, US State Privacy (with the states list, GPP Sections and MSPA settings) and IAB TCF Canada. shouldRequestConsent() returns true for Canadian users IAB TCF Canada applies to until they make a choice. US privacy is opt-out, so US users are not asked on their own: they see the US banner or settings when your app opens the CMP, for example from a privacy settings link. Until then, when CCPA or US State Privacy is enabled, the SDK writes the default US Privacy and GPP keys for US users without showing anything: not opted out, or opted out when the device ad tracking opt-out is on. US State Privacy starts off for new Mobile App projects; turn it on in the dashboard.
When the user has turned off ad tracking on the device, the CMP treats it as a US opt-out of sale, sharing and targeted advertising, as Global Privacy Control does on websites. On iOS this is tracking not allowed in App Tracking Transparency; on Android it is a deleted advertising ID or limit ad tracking, read through Google Play services when your app includes it. A choice the user then saves in the banner takes precedence.
The SDK also returns the stored strings:
let gppString = UniConsentCMP.shared.getGPPString()
let gppSid = UniConsentCMP.shared.getGPPSID()
let usPrivacy = UniConsentCMP.shared.getUSPrivacyString()
Available from SDK version 26.10.0. Where a region uses cookie categories instead of IAB TCF or the US policies, the CMP shows a banner with four categories: Strictly Necessary, Performance, Functionality, and Targeting or Advertising. This applies to:
Opt-in categories start with only Strictly Necessary on, and shouldRequestConsent() returns true until the user makes a choice, and again after you change the config version. Opt-out categories start with every category on (Targeting off when the device ad tracking opt-out is on in the US), and the app does not ask on its own: users change them from your privacy settings link. Opt-out applies to an opt-out rule for other countries and, in apps, to a Consent Categories project in the US.
Open the categories screens with .CategoriesFirstScreen (banner) and .CategoriesSecondScreen (settings). setTestRegion() also takes BR, CN, ZA, VN and other country codes, to test these regions.
Available from SDK version 26.10.0. The custom purposes and the custom vendors you add in the project settings of the UniConsent dashboard show in the CMP screens: the custom purposes in the IAB TCF first layer and settings and in the cookie categories settings, the custom vendors in the IAB TCF vendors list. In the CCPA and US State Privacy settings only sensitive custom purposes are listed. In the cookie categories settings the custom vendors follow the Targeting or Advertising category. Where IAB TCF does not apply (cookie categories and the US), the custom vendors are listed read-only under Vendors List in the menu, and in the cookie categories settings under Targeting or Advertising.
To start or stop your own SDKs by them, ask the SDK whether the app may use a custom purpose or custom vendor now. The answer follows the user's policy, by the same rules the CMP uses for tags:
let cmp = UniConsentCMP.shared
if cmp.isCustomPurposeConsented(1) {
// start the SDK your custom purpose 1 covers
}
let vendorAllowed = cmp.isCustomVendorConsented(2)
let all = cmp.getCustomConsents() // ["purposes": ["1": true], "vendors": ["2": false]]
Call them again after the CMP closes or the consent changes. Ids the project does not have, and every id before the SDK is ready, return false.
The CMP can list the third-party SDKs in your app (ad networks, analytics, attribution and others) with their company, what they are used for and their privacy policy. Users see them under Vendors List, read-only in every region: there are no toggles, and your app keeps turning each SDK on or off from the user's choices for purposes or cookie categories.
To set the list, turn on Enable Third-party SDKs in Step 4: Advanced Features of your app project, pick your SDKs in the Third-party SDKs tab or add your own, then save and publish. No code is needed in your app.
Set up default consent status KV:
<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/>
Control analytics based on the consent flags:
// 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
}
Find more info at Set up consent mode for apps
getGPPString(), getGPPSID() and getUSPrivacyString().USStateSecondScreen; add launchCMPIfNeeded(), setLogLevel() and getGEOState().CCPAFirstScreen and .USStateFirstScreen; add setTestRegion() to test the CMP as a user in another region, such as Canada.CategoriesFirstScreen and .CategoriesSecondScreengetPolicy(); agreeAll() and rejectAll() also save the cookie categories, custom purposes and custom vendorssetTestRegion() also takes BR, CN, ZA, VN and other country codes, and applies to getPolicy() and shouldRequestConsent()isCustomPurposeConsented(), isCustomVendorConsented() and getCustomConsents(): the custom purposes and custom vendors the app may use now, under the user's policy