example/README.md

Biscotti CMP — Flutter integration example #

Minimal, verified integration of the biscotti_cmp package. The API names below match the package source 1:1 (lib/src/biscotti_cmp.dart).

Requirements: Flutter ≥ 3.16 · Dart ≥ 3.2 · iOS deployment target ≥ 12.0 (App Tracking Transparency features require iOS 14+) · Android minSdk 21.

This is the Flutter SDK (self-contained Dart plugin). Do not also add the native iOS Swift package (BiscottiCMP / SPM) or pod 'BiscottiCMP' — the Flutter package brings its own iOS/Android platform side.

1. Add the package #

flutter pub add biscotti_cmp

# pubspec.yaml
dependencies:
  biscotti_cmp: ^1.1.3

2. iOS setup #

cd ios && pod install

In ios/Podfile make sure the platform line is present:

platform :ios, '12.0'

The SDK integrates App Tracking Transparency. If you request tracking authorization (typical when you collect marketing consent), you must add the usage description to ios/Runner/Info.plist — otherwise the app crashes when ATT is requested:

<key>NSUserTrackingUsageDescription</key>
<string>We ask permission to personalize content and ads.</string>

3. Initialize #

import 'package:flutter/material.dart';
import 'package:biscotti_cmp/biscotti_cmp.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await BiscottiCMP.instance.configure(
    websiteId: 'YOUR_WEBSITE_ID',   // from the Biscotti CMP dashboard
    // apiKey: 'OPTIONAL',          // only needed for server-side consent sync
  );

  runApp(const MyApp());
}

4. Show the consent dialog #

showConsentDialog needs a BuildContext:

WidgetsBinding.instance.addPostFrameCallback((_) {
  BiscottiCMP.instance.showConsentDialog(context);
});

4a. Temporarily disable IAB TCF for the mobile app #

Create a separate Mobile App property in the Biscotti dashboard, disable IAB TCF on that child property, and use its own website ID in configure(). The SDK then keeps category consent active but generates no TC String and removes all IABTCF_* storage keys. Do not reuse the website ID of a TCF-enabled web banner.

5. Gate third-party SDKs behind consent #

BiscottiCMP.instance.registerSDK(
  name: 'firebase_analytics',
  category: ConsentCategory.analytics, // essential | functional | analytics | marketing
  initializer: () {
    // Runs only after the user grants the "analytics" category.
  },
);

6. Read consent #

final marketingOk = BiscottiCMP.instance.hasConsent(ConsentCategory.marketing); // sync
final token = BiscottiCMP.instance.getConsentToken();                            // sync, for server verification

// React to changes:
BiscottiCMP.instance.onConsentChanged.listen((state) {
  // state.categories, state.tcString, ...
});

Optional — request ATT explicitly (iOS only; returns null on Android):

final status = await ATTService().requestTracking();

API reference (as implemented) #

ConsentCategory: essential, functional, analytics, marketing.