feat(consent_manager): ready-event und dev-kurzhilfe ergänzen

Author: skerbis

CHANGELOG.md

@@ -12,6 +12,9 @@
 - **Cleanup (Issue #470):** Inline-JS aus `pages/config.php` und `pages/help.php` in externe Assets ausgelagert.
 - **Fix:** Backend-JS wird zentral im Boot-Prozess eingebunden, statt seitenlokal verteilt.
 - **Fix:** Initialisierung im Backend auf `rex:ready` vereinheitlicht; PJAX-spezifische Zusatzpfade entfernt.
+- **Fix:** Consent-Logging-Request auf same-origin umgestellt (`window.location` statt `fe_controller`), um `TypeError: Load failed` bei Host-/Protokoll-Mismatch zu vermeiden.
+- **Feature (JS API):** Neues Event `consent_manager-ready` eingeführt, damit eigene Skripte zuverlässig auf die Initialisierung reagieren können.
+- **Docs:** Neue Entwickler-Kurzhilfe `DEV_QUICKSTART.md` mit Einbindungsvarianten sowie Consent-Abfragen per PHP/JavaScript ergänzt und in die Hilfe-Navigation integriert.
 
 ## Version 5.6.0-beta1 - 05.03.2026
 

DEV_QUICKSTART.md

@@ -0,0 +1,183 @@
+# Consent Manager – Dev Kurzhilfe (Schnellstart)
+
+Kurz und praktisch: Einbindung, Consent-Abfrage und typische Snippets.
+
+## 1) Einbindung wählen
+
+### Option A: Auto-Inject (empfohlen)
+1. Backend öffnen: `Consent Manager -> Domains -> Domain bearbeiten`
+2. `Automatische Frontend-Einbindung` auf **Aktiviert** setzen
+3. Speichern
+
+Ergebnis: Der Consent Manager wird automatisch vor `</head>` eingebunden.
+
+### Option B: Manuell im Template (komplett)
+
+```php
+<?php
+use FriendsOfRedaxo\ConsentManager\Frontend;
+
+echo Frontend::getFragment(0, 0, 'ConsentManager/box_cssjs.php');
+```
+
+### Option C: Manuell, Komponenten getrennt
+
+```php
+<?php
+use FriendsOfRedaxo\ConsentManager\Frontend;
+?>
+<style><?= Frontend::getCSS() ?></style>
+<script<?= Frontend::getNonceAttribute() ?>>
+<?= Frontend::getJS() ?>
+</script>
+<?= Frontend::getBox() ?>
+```
+
+---
+
+## 2) Consent in PHP abfragen
+
+```php
+<?php
+use FriendsOfRedaxo\ConsentManager\Utility;
+
+if (Utility::has_consent('google-analytics')) {
+    // Script/Markup nur bei erteiltem Consent ausgeben
+}
+```
+
+---
+
+## 3) Consent in JavaScript abfragen
+
+Wichtig: Eigene Skripte sollten warten, bis der Consent Manager initialisiert ist.
+
+```javascript
+document.addEventListener('consent_manager-ready', function (e) {
+  if (!e.detail.initialized) {
+    console.warn('Consent Manager nicht bereit:', e.detail.reason);
+    return;
+  }
+
+  if (typeof consent_manager_hasconsent === 'function' && consent_manager_hasconsent('google-analytics')) {
+    console.log('GA darf geladen werden');
+  }
+});
+```
+
+Direkte Abfrage (wenn bereits sicher initialisiert):
+
+```javascript
+if (typeof consent_manager_hasconsent === 'function' && consent_manager_hasconsent('google-analytics')) {
+  // Consent vorhanden
+}
+```
+
+---
+
+## 4) Auf Consent-Änderung reagieren
+
+```javascript
+document.addEventListener('consent_manager-saved', function (e) {
+  var consents = JSON.parse(e.detail);
+  // z. B. Tracking dynamisch starten/stoppen
+});
+```
+
+---
+
+## 5) Einstellungen-Dialog per Link öffnen
+
+Standard (ohne Reload):
+
+```html
+<a href="#" data-consent-action="settings">Cookie-Einstellungen</a>
+```
+
+Variante mit Reload nach Speichern:
+
+```html
+<a href="#" data-consent-action="settings,reload">Cookie-Einstellungen</a>
+```
+
+Tipp: `reload` ist sinnvoll, wenn externe Skripte keinen sauberen Live-Reinit unterstützen und erst nach einem Seiten-Reload korrekt starten/stoppen.
+
+---
+
+## 6) Häufige Stolpersteine
+
+- `consent_manager_hasconsent is not defined`: Consent Manager ist noch nicht geladen oder gar nicht eingebunden.
+- `TypeError: Load failed` beim Speichern: meist URL-/Host-/HTTPS-Mismatch im Setup; aktuelle Version nutzt same-origin Logging.
+- Falsche Quotes in JS vermeiden: normale `'` oder `"` verwenden, keine typografischen Anführungszeichen.
+
+---
+
+## 7) Spezialfälle (Tipps)
+
+### A) Mehrere Services gleichzeitig prüfen
+
+```javascript
+function hasAllConsents(serviceKeys) {
+  if (typeof consent_manager_hasconsent !== 'function') return false;
+  return serviceKeys.every(function (key) {
+    return consent_manager_hasconsent(key);
+  });
+}
+
+document.addEventListener('consent_manager-ready', function () {
+  if (hasAllConsents(['google-analytics', 'google-tag-manager'])) {
+    // Nur wenn beide erlaubt sind
+  }
+});
+```
+
+### B) Script erst nach Consent dynamisch laden
+
+```javascript
+function loadScript(src) {
+  var script = document.createElement('script');
+  script.src = src;
+  script.async = true;
+  document.head.appendChild(script);
+}
+
+document.addEventListener('consent_manager-ready', function () {
+  if (typeof consent_manager_hasconsent === 'function' && consent_manager_hasconsent('google-analytics')) {
+    loadScript('https://www.googletagmanager.com/gtag/js?id=G-XXXXXXX');
+  }
+});
+```
+
+### C) Reaktion auf spätere Änderungen (Opt-in/Opt-out)
+
+```javascript
+document.addEventListener('consent_manager-saved', function () {
+  if (typeof consent_manager_hasconsent !== 'function') return;
+
+  if (consent_manager_hasconsent('google-analytics')) {
+    // Tracking aktivieren
+  } else {
+    // Tracking deaktivieren / keine neuen Events senden
+  }
+});
+```
+
+### D) Fallback, wenn eigenes Script sehr früh läuft
+
+```javascript
+function onConsentManagerReady(callback) {
+  document.addEventListener('consent_manager-ready', function (e) {
+    if (e.detail.initialized) callback();
+  });
+
+  document.addEventListener('DOMContentLoaded', function () {
+    if (typeof consent_manager_hasconsent === 'function') {
+      callback();
+    }
+  });
+}
+
+onConsentManagerReady(function () {
+  // hier sicher mit consent_manager_hasconsent arbeiten
+});
+```

README.md

@@ -620,6 +620,8 @@ $legalId = $consent->links['legal_notice'] ?? 0;
 
 ## 👨‍💻 Für Developer
 
+👉 **Kurzhilfe / Schnellstart für Entwickler:** [DEV_QUICKSTART.md](DEV_QUICKSTART.md)
+
 ### JavaScript API
 
 ```javascript
@@ -634,6 +636,18 @@ document.addEventListener('consent_manager-saved', function(e) {
     // Scripts nachladen, UI aktualisieren etc.
 });
 
+// Event wenn Consent Manager initialisiert ist
+document.addEventListener('consent_manager-ready', function(e) {
+    if (!e.detail.initialized) {
+        console.warn('Consent Manager nicht initialisiert:', e.detail.reason);
+        return;
+    }
+
+    if (typeof consent_manager_hasconsent === 'function' && consent_manager_hasconsent('google-analytics')) {
+        // Eigene Scripts sicher ausführen
+    }
+});
+
 // Box öffnen
 consent_manager_showBox();
 

assets/consent_manager_frontend.js

@@ -51,6 +51,19 @@ function safeJSONParse(input, fallback) {
     var showDelay = parseInt(autoInjectOptions.showDelay, 10) || 0;
     var autoFocus = autoInjectOptions.autoFocus !== false; // default true
 
+    function emitReady(initialized, reason) {
+        document.dispatchEvent(new CustomEvent('consent_manager-ready', {
+            detail: {
+                initialized: initialized,
+                reason: reason || null,
+                noCookieSet: !!consent_manager_parameters.no_cookie_set,
+                domain: consent_manager_parameters.domain || '',
+                hasConsentApi: typeof consent_manager_hasconsent === 'function',
+                hasShowBoxApi: typeof consent_manager_showBox === 'function'
+            }
+        }));
+    }
+
     // Es gibt keinen Datenschutzcookie, Consent zeigen
     if (typeof cmCookieAPI.get(cmCookieName) === 'undefined') {
         cmCookieAPI.set(cmCookieName + '_test', 'test');
@@ -75,6 +88,7 @@ function safeJSONParse(input, fallback) {
 
     if (consent_manager_box_template === '') {
         console.warn('Addon consent_manager: Keine Cookie-Gruppen / Cookies ausgewählt bzw. keine Domain zugewiesen! (' + location.hostname + ')');
+        emitReady(false, 'missing_template');
         return;
     }
     consent_managerBox = new DOMParser().parseFromString(consent_manager_box_template, 'text/html');
@@ -409,11 +423,15 @@ function safeJSONParse(input, fallback) {
             console.warn('Addon consent_manager: Es konnte kein Cookie für die Domain ' + document.domain + ' gesetzt werden!');
         } else {
             // Async logging to avoid blocking UI (replaced deprecated synchronous XHR)
-            var url = consent_manager_parameters.fe_controller + '?rex-api-call=consent_manager&buster=' + new Date().getTime();
+            // Use same-origin current URL to avoid mixed-content/CORS failures when fe_controller differs.
+            var url = window.location.pathname + window.location.search;
+            var separator = url.indexOf('?') === -1 ? '?' : '&';
+            url = url + separator + 'rex-api-call=consent_manager&buster=' + new Date().getTime();
             var params = 'domain=' + encodeURIComponent(document.domain) + '&consentid=' + encodeURIComponent(consent_manager_parameters.consentid) + '&buster=' + new Date().getTime();
 
             fetch(url, {
                 method: 'POST',
+                credentials: 'same-origin',
                 headers: {
                     'Content-Type': 'application/x-www-form-urlencoded',
                     'Cache-Control': 'no-cache, no-store, max-age=0'
@@ -666,6 +684,8 @@ function safeJSONParse(input, fallback) {
         document.dispatchEvent(new CustomEvent('consent_manager-show'));
     }
 
+    emitReady(true);
+
 })();
 
 function mapConsentsToGoogleFlags(consents) {

assets/consent_manager_frontend.min.js

@@ -8,6 +8,11 @@
         'icon' => 'rex-icon fa-book',
         'file' => 'README.md'
     ],
+    'dev_quickstart' => [
+        'title' => 'Dev Kurzhilfe',
+        'icon' => 'rex-icon fa-bolt',
+        'file' => 'DEV_QUICKSTART.md'
+    ],
     'inline' => [
         'title' => 'Inline Consent',
         'icon' => 'rex-icon fa-play-circle',