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.2

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

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.