Leading Consent Management Platform

Compliant with GDPR, CCPA, COPPA, LGPD, PECR, PDPA, PIPEDA, and more.

Theme

How to integrate UniConsent CMP SDK for Flutter with mobile apps

UniConsent CMP is a package for handling GDPR IAB TCF 2.4 consent management in Flutter apps. You can find a demo app integrated with UniConsent CMP in the "uniconsent_demo" directory.

Prerequisites

UniConsent CMP plan with Mobile app support
UniConsent CMP SDK package (request from support)

Getting started

To include the UniConsent package in your Flutter project, add it as a dependency in your pubspec.yaml file:

dependencies:
  uniconsent:
    path: ../uniconsent

Then, sync the dependency by running the following command:

flutter pub get

Before integrating the SDK, customize the consent banner appearance in the UniConsent Dashboard to match your brand and optimize consent rates.

Step 1: Brand Styling in Dashboard

Go to Projects → Select your Project → Settings → Step 5: UI & Style Settings to configure:

Main Button Colour — Set the primary action button color to match your brand
Main Button Text Colour — Adjust text color on the primary button for readability
Background Colour — Set the banner background color to blend with your app
Text Colour — Ensure body text has appropriate contrast

Step 2: Advanced Styling with Custom CSS (Optional)

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.

Both ratios are optional — every display mode works without them. Pass a ratio (a fraction of the available space, greater than 0 and at most 1) only to override the default size; invalid values throw ArgumentError:

Parameter	Applies to	Default when omitted
`heightRatio`	`modalSheet`, `dialog`	Sheet: 90% of the height. Dialog: 70%
`widthRatio`	`dialog` only	90% of the width, up to 500 logical pixels

Ratios that don't apply to the chosen display mode are ignored (page ignores both).

Event Handler

Listen for SDK lifecycle events with subscribe(). This is the recommended way to know when the UI is displayed and when it is closed.

Available events (CMPEventType):

CMPEventType.uiDisplay — Consent UI is displayed
CMPEventType.uiClose — Consent UI is closed

UniConsent.instance.subscribe((event) {
  switch (event.type) {
    case CMPEventType.uiDisplay:
      print('CMP UI displayed');
      break;
    case CMPEventType.uiClose:
      print('CMP UI closed');
      break;
    default:
      break;
  }
});

Listen for consent changes with an optional callback:

// Display CMP UI with consent change callback
UniConsent.instance.launchCMP(context, onConsentChanged: (info) {
  // Called when the user saves consent choices
  print('Consent updated: ${info?.tcString}');
});

For full control, use buildCMPWidget() to embed the CMP in your own layout:

// Embed in your own widget tree
UniConsent.instance.buildCMPWidget(
  onConsentChanged: (info) { /* ... */ },
  onClose: () { /* dismiss your custom UI */ },
);

Automatically check if consent is needed on app launch:

// Check if consent should be requested (e.g. first visit, or vendor list updated)
final shouldRequest = await UniConsent.instance.shouldRequestConsent();
if (shouldRequest) {
  UniConsent.instance.launchCMP(context);
}

Get the tcString if required:

// Get tcString
final info = await UniConsent.instance.getConsentInfo();
print(info?.tcString);

Read the consent status:

// Read consent status
final info = await UniConsent.instance.getConsentInfo();
if (info is ConsentInfo &&
    info.purposeConsents.contains(DataUsagePurpose.useLimitedDataToSelectAds)) {
  // do something
}

Reset consent status if required:

// Clear all consent data
await UniConsent.instance.clearAll();

Custom First Layer (Agree All / Reject All)

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
final saved = await UniConsent.instance.agreeAll();

// Reject all purposes, special features and vendors
final saved = await UniConsent.instance.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 close event to 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.

final cmp = UniConsent.instance;
if (await cmp.shouldRequestConsent()) {
  // the user needs to make a choice: show your first layer for this policy
  final policy = await cmp.getPolicy(); // gdpr, tcfca or categories
}

Note: These APIs fetch the vendor list and project config over the network and return false if consent could not be saved (e.g. offline).

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()) to make granular choices.

If your app opens a WebView 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.

import 'package:webview_flutter/webview_flutter.dart';
import 'package:uniconsent/uniconsent.dart';

final controller = WebViewController();
controller
  ..setJavaScriptMode(JavaScriptMode.unrestricted)
  ..setNavigationDelegate(NavigationDelegate(
    onPageStarted: (url) async {
      // Inject consent at page start, before CMP tag runs
      await UniConsent.instance.syncConsent(controller);
    },
  ))
  ..loadRequest(Uri.parse('https://example.com'));

Exported types

The following types are available when importing package:uniconsent/uniconsent.dart:

UniConsent — main SDK singleton
UniConsentInfo — base consent data (sdkId, tcString, gdprApplies, vendorListVersion, etc.)
ConsentInfo — extends UniConsentInfo with purpose-level consent lists
DataUsagePurpose — enum of IAB TCF 2.4 purpose IDs
KVDBKeys — IAB TCF storage key constants (e.g. KVDBKeys.tcString, KVDBKeys.purposeConsents)
CMPDisplayMode — enum for display style (page, modalSheet, dialog)
CMPEventType — enum for lifecycle events (the SDK fires uiDisplay and uiClose)
CMPEvent — event object with a type property
CMPEventCallback — typedef for the subscribe() callback
LogLevel — debug / prod
ConsentCallback — typedef for the onConsentChanged callback
UniConsentCMPContent — the core CMP widget for custom layouts

Open a Specific Screen and Other Options

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
`CMPStage.gdprFirstScreen`	First layer (banner)
`CMPStage.gdprSecondScreen`	Settings (purposes)
`CMPStage.gdprVendorsScreen`	Vendors
`CMPStage.ccpaFirstScreen`	CCPA first layer
`CMPStage.ccpaSecondScreen`	CCPA settings
`CMPStage.usStateFirstScreen`	US State Privacy first layer
`CMPStage.usStateSecondScreen`	US State Privacy settings
`CMPStage.categoriesFirstScreen`	Cookie categories first layer (banner)
`CMPStage.categoriesSecondScreen`	Cookie categories settings

final cmp = UniConsent.instance;

// open the settings screen
cmp.launchCMP(context, stage: CMPStage.gdprSecondScreen);

// open the CMP only when consent is needed (EU and IAB TCF Canada), returns whether it opened
final opened = await cmp.launchCMPIfNeeded(context);

// debug logs, use LogLevel.prod in release builds
cmp.setLogLevel(LogLevel.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");

// the user's country code ("AA" when unknown) and, for the US and Canada, the state or province code
final geo = await cmp.getGEO();
final state = await cmp.getGEOState();

IAB GPP and US Privacy

The CMP stores the IAB GPP keys and the US Privacy key in the app's native storage (SharedPreferences on Android, UserDefaults on iOS), 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. Which users get the IABGPP_ keys follows GPP Signals in the project settings: users in Canada always (IAB TCF Canada), US users when US is on, and EU users when EU is on. Users no region covers get the keys with no section while US or EU is on, and no keys otherwise.

US and Canada

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.

Device ad tracking opt-out

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.

Read the GPP and US Privacy strings

The SDK also returns the stored strings:

final gppString = await UniConsent.instance.getGPPString();
final gppSid = await UniConsent.instance.getGPPSID();
final usPrivacy = await UniConsent.instance.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:

LGPD in Brazil, PIPL in China, POPIA in South Africa and PDPD in Vietnam, when turned on in the project settings of the UniConsent dashboard
your rules for other countries: a rule for a country, and a rule for all remaining countries
a Consent Categories project, in its regions

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 CMPStage.categoriesFirstScreen (banner) and CMPStage.categoriesSecondScreen (settings). setTestRegion() also takes BR, CN, ZA, VN and other country codes, to test these regions.

Custom Purposes and Custom Vendors

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:

IAB TCF, IAB TCF Canada and opt-in cookie categories: allowed only after the user agrees
the US and opt-out cookie categories: allowed until the user opts out; sensitive custom purposes need the user's agreement, and the custom vendors are off when the device opts out of ad tracking in the US
no policy: allowed

final cmp = UniConsent.instance;
if (await cmp.isCustomPurposeConsented(1)) {
  // start the SDK your custom purpose 1 covers
}
final vendorAllowed = await cmp.isCustomVendorConsented(2);
final all = await 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.

Third-party SDK Disclosure

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.

Notes

Users should have the ability to access a "Privacy Settings" button or link in the settings section of your application in order to open the CMP UI.
You can utilize the shouldRequestConsent() function to check whether you should request new consent based on the status. Display the CMP UI as needed when a user opens the application.

Changelog

26.11.0

Add setCustomConsent() to save a custom purpose choice from your app's own screen, such as an email open tracking checkbox; isCustomPurposeConsented() also takes the custom purpose ID set in the dashboard
An email user ID is sent as email_hash (SHA-256); the address itself is not stored or sent
The IAB GPP keys follow the GPP Signals settings in the dashboard

26.10.0

IAB GPP and US Privacy keys for ad SDKs
US State Privacy and IAB TCF Canada in apps, including the custom first layer
Add getGPPString(), getGPPSID() and getUSPrivacyString()
Open a specific screen with launchCMP(context, stage:); add launchCMPIfNeeded(), getGEO() and getGEOState()
Open the CCPA and US State Privacy first layers with CMPStage.ccpaFirstScreen and CMPStage.usStateFirstScreen; add setTestRegion() to test the CMP as a user in another region, such as Canada
Cookie categories in apps: LGPD (Brazil), PIPL (China), POPIA (South Africa), PDPD (Vietnam), your rules for other countries and Consent Categories projects, with CMPStage.categoriesFirstScreen and CMPStage.categoriesSecondScreen
Add getPolicy(); agreeAll() and rejectAll() also save the cookie categories, custom purposes and custom vendors
setTestRegion() also takes BR, CN, ZA, VN and other country codes, and applies to getPolicy() and shouldRequestConsent()
Add isCustomPurposeConsented(), isCustomVendorConsented() and getCustomConsents(): the custom purposes and custom vendors the app may use now, under the user's policy

26.9.0

IAB TCF 2.4 support

Consent Management for Web

Mobile App CMP

Google Consent Mode

Google Tag Gateway

IAB TCF Certified CMP

Microsoft UET Consent

Amazon Consent Signal

Meta Pixel Consent

TikTok Pixel Consent

Cookie Scanner

For Publishers

For Advertisers

For Shopify

For WordPress