breakpilot-pwa/consent-sdk/README.md

@breakpilot/consent-sdk

DSGVO/TTDSG-konformes Consent Management SDK fuer Web, PWA und Mobile Apps.

Features

• DSGVO, TTDSG und ePrivacy-Richtlinie konform
• IAB TCF 2.2 Unterstuetzung
• Google Consent Mode v2 Integration
• Plattformuebergreifend (Web, PWA, iOS, Android, Flutter, React Native)
• Typsicher (TypeScript)
• Barrierefreundlich (WCAG 2.1 AA)
• Open Source (Apache 2.0)

Installation

npm install @breakpilot/consent-sdk

Quick Start

Vanilla JavaScript

import { ConsentManager } from '@breakpilot/consent-sdk';

const consent = new ConsentManager({
  apiEndpoint: 'https://consent.example.com/api/v1',
  siteId: 'site_abc123',
  language: 'de',
});

await consent.init();

// Consent pruefen
if (consent.hasConsent('analytics')) {
  // Analytics laden
}

// Events
consent.on('change', (newConsent) => {
  console.log('Consent changed:', newConsent);
});

React

import { ConsentProvider, useConsent, ConsentBanner, ConsentGate } from '@breakpilot/consent-sdk/react';

const config = {
  apiEndpoint: 'https://consent.example.com/api/v1',
  siteId: 'site_abc123',
};

function App() {
  return (
    <ConsentProvider config={config}>
      <ConsentBanner />
      <MainContent />
    </ConsentProvider>
  );
}

function AnalyticsSection() {
  return (
    <ConsentGate
      category="analytics"
      placeholder={<p>Analytics erfordert Ihre Zustimmung.</p>}
    >
      <GoogleAnalytics />
    </ConsentGate>
  );
}

function SettingsButton() {
  const { showSettings } = useConsent();
  return <button onClick={showSettings}>Cookie-Einstellungen</button>;
}

Script Blocking

Verwenden Sie data-consent um Skripte zu blockieren:

<!-- Externes Script -->
<script
  data-consent="analytics"
  data-src="https://www.googletagmanager.com/gtag/js?id=GA-XXXXX"
  type="text/plain">
</script>

<!-- Inline Script -->
<script data-consent="marketing" type="text/plain">
  fbq('init', 'XXXXX');
</script>

<!-- iFrame -->
<iframe
  data-consent="social"
  data-src="https://www.youtube.com/embed/XXXXX"
  title="YouTube Video">
</iframe>

Consent-Kategorien

Kategorie	Beschreibung	Einwilligung
essential	Technisch notwendig	Nicht erforderlich
functional	Personalisierung	Erforderlich
analytics	Nutzungsanalyse	Erforderlich
marketing	Werbung	Erforderlich
social	Social Media	Erforderlich

Konfiguration

const config: ConsentConfig = {
  // Pflicht
  apiEndpoint: 'https://consent.example.com/api/v1',
  siteId: 'site_abc123',

  // Sprache
  language: 'de',
  fallbackLanguage: 'en',

  // UI
  ui: {
    position: 'bottom',      // 'bottom' | 'top' | 'center'
    layout: 'modal',         // 'bar' | 'modal' | 'floating'
    theme: 'auto',           // 'light' | 'dark' | 'auto'
    zIndex: 999999,
  },

  // Verhalten
  consent: {
    required: true,
    rejectAllVisible: true,  // "Alle ablehnen" Button
    acceptAllVisible: true,  // "Alle akzeptieren" Button
    granularControl: true,   // Kategorien einzeln waehlbar
    rememberDays: 365,       // Speicherdauer
    recheckAfterDays: 180,   // Erneut fragen nach X Tagen
  },

  // Callbacks
  onConsentChange: (consent) => {
    console.log('Consent:', consent);
  },

  // Debug
  debug: process.env.NODE_ENV === 'development',
};

API

ConsentManager

// Initialisieren
await consent.init();

// Consent pruefen
consent.hasConsent('analytics');        // boolean
consent.hasVendorConsent('google');     // boolean

// Consent abrufen
consent.getConsent();                   // ConsentState | null

// Consent setzen
await consent.setConsent({
  essential: true,
  analytics: true,
  marketing: false,
});

// Aktionen
await consent.acceptAll();
await consent.rejectAll();
await consent.revokeAll();

// Banner
consent.showBanner();
consent.hideBanner();
consent.showSettings();
consent.needsConsent();                 // boolean

// Events
consent.on('change', callback);
consent.on('banner_show', callback);
consent.on('banner_hide', callback);
consent.off('change', callback);

// Export (DSGVO Art. 20)
const data = await consent.exportConsent();

React Hooks

// Basis-Hook
const {
  consent,
  isLoading,
  isBannerVisible,
  needsConsent,
  hasConsent,
  acceptAll,
  rejectAll,
  showBanner,
  showSettings,
} = useConsent();

// Mit Kategorie
const { allowed } = useConsent('analytics');

// Manager-Zugriff
const manager = useConsentManager();

Rechtliche Compliance

Dieses SDK erfuellt:

• DSGVO (EU 2016/679) - Art. 4, 6, 7, 12, 13, 17, 20
• TTDSG (Deutschland) - § 25
• ePrivacy-Richtlinie (2002/58/EG) - Art. 5
• Planet49-Urteil (EuGH C-673/17)
• BGH Cookie-Einwilligung II (2023)
• DSK Orientierungshilfe Telemedien

Lizenz

Apache 2.0 - Open Source, kommerziell nutzbar.

Copyright 2026 BreakPilot GmbH

Licensed under the Apache License, Version 2.0