如何将 UniConsent CMP SDK 集成到 Flutter 移动应用

UniConsent CMP 是用于在 Flutter 应用中处理 GDPR IAB TCF 2.3 同意管理的软件包。您可以在 "uniconsent_demo" 目录中找到集成了 UniConsent CMP 的演示应用。

前提条件

• 支持移动应用的 UniConsent CMP 方案
• UniConsent CMP SDK 软件包（请联系支持团队获取）

开始使用

要在 Flutter 项目中包含 UniConsent 软件包，请将其作为依赖项添加到 pubspec.yaml 文件中：

dependencies:
  uniconsent:
    path: ../uniconsent

然后运行以下命令同步依赖项：

flutter pub get

自定义同意界面

在集成 SDK 之前，请在 UniConsent 控制台 中自定义同意横幅的外观，以匹配您的品牌并优化同意率。

第 1 步：在控制台中设置品牌样式

前往 Projects → 选择您的项目 → Settings → Step 5: UI & Style Settings 进行配置：

• Main Button Colour — 设置主操作按钮颜色以匹配您的品牌
• Main Button Text Colour — 调整主按钮上的文字颜色以确保可读性
• Background Colour — 设置横幅背景颜色以融入您的应用
• Text Colour — 确保正文文字具有适当的对比度

第 2 步：使用自定义 CSS 进行高级样式设置（可选）

如需更精确的控制，请在 Step 5 的 CSS Content 字段中添加自定义 CSS。建议使用此功能让横幅呈现原生应用的观感，以获得最佳同意率：

/* 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;
}

提示： 具有原生应用观感的精心设计的同意界面通常能获得更高的同意率。用户更可能对符合预期外观和风格的横幅做出积极响应。

使用方法

要在应用中使用 UniConsent CMP，请按照以下步骤操作：

使用客户经理提供的 App ID 初始化 CMP：

// Init CMP with appId
UniConsent.instance.setAppId("YOUR_APP_ID_CHANGE_THIS");
// Set language (Optional)
UniConsent.instance.setLanguage("EN");

显示 CMP 界面：

// Display CMP as full-screen page (default)
UniConsent.instance.launchCMP(context);

// Display CMP as a modal bottom sheet
UniConsent.instance.launchCMP(context, displayMode: CMPDisplayMode.modalSheet);

// Display CMP as a center dialog
UniConsent.instance.launchCMP(context, displayMode: CMPDisplayMode.dialog);

事件处理

使用 subscribe() 监听 SDK 生命周期事件。这是了解界面何时显示和关闭的推荐方式。

可用事件（CMPEventType）：

• CMPEventType.uiDisplay — 同意界面已显示
• CMPEventType.uiClose — 同意界面已关闭

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;
  }
});

使用可选回调监听同意变更：

// 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}');
});

如需完全控制，使用 buildCMPWidget() 将 CMP 嵌入您自己的布局中：

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

在应用启动时自动检查是否需要同意：

// 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);
}

获取 tcString（如需要）：

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

读取同意状态：

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

重置同意状态（如需要）：

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

将同意状态同步到 WebView

如果您的应用打开了加载带有 UniConsent CMP 标签的网页的 WebView，您可以传递原生同意状态，这样 CMP 标签会识别已有的同意记录，不会再次显示横幅。

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

final controller = WebViewController()
  ..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'));

导出的类型

导入 package:uniconsent/uniconsent.dart 后可使用以下类型：

• UniConsent — SDK 主单例
• UniConsentInfo — 基础同意数据（sdkId、tcString、gdprApplies、vendorListVersion 等）
• ConsentInfo — 继承自 UniConsentInfo，包含目的级别的同意列表
• DataUsagePurpose — IAB TCF 2.3 目的 ID 枚举
• KVDBKeys — IAB TCF 存储键常量（例如 KVDBKeys.tcString、KVDBKeys.purposeConsents）
• CMPDisplayMode — 显示样式枚举（page、modalSheet、dialog）
• CMPEventType — 生命周期事件枚举（sdkInit、ready、uiDisplay、uiClose）
• CMPEvent — 带有 type 属性的事件对象
• CMPEventCallback — subscribe() 回调的类型定义
• LogLevel — debug / prod
• ConsentCallback — onConsentChanged 回调的类型定义
• UniConsentCMPContent — 用于自定义布局的核心 CMP 组件

注意事项

1. 用户应该能够在应用的设置部分访问"隐私设置"按钮或链接，以便打开 CMP 界面。
2. 您可以使用 shouldRequestConsent() 函数来检查是否需要根据状态请求新的同意。在用户打开应用时，根据需要显示 CMP 界面。