Skip to content

Commit 1cb45b6

Browse files
skerbisskerbis
committed
docs(consent_manager): dokumentation in docs-ordner strukturieren und setup/tutorial erweitern
1 parent 6d78cc6 commit 1cb45b6

13 files changed

Lines changed: 870 additions & 849 deletions

‎README.md‎

Lines changed: 43 additions & 840 deletions
Large diffs are not rendered by default.

DEV_QUICKSTART.md renamed to docs/DEV_QUICKSTART.md

File renamed without changes.

api.md renamed to docs/api.md

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,117 @@ Typischerweise nicht direkt nötig, wenn Links mit `data-consent-action="setting
4343

4444
## PHP API
4545

46+
Die PHP-API besteht aus mehreren Klassen mit unterschiedlichen Aufgaben.
47+
48+
### Frontend
49+
50+
Die Klasse `Frontend` ist die zentrale Integrationsklasse für Templates.
51+
52+
```php
53+
use FriendsOfRedaxo\ConsentManager\Frontend;
54+
```
55+
56+
#### getFragment()
57+
58+
Standard-Einstieg für die Ausgabe im Frontend:
59+
60+
```php
61+
echo Frontend::getFragment(0, 0, 'ConsentManager/box_cssjs.php');
62+
```
63+
64+
Parameter:
65+
66+
- `$forceCache` (`int`): Cache-Verhalten (`0` normal, `1` neu schreiben)
67+
- `$forceReload` (`int`): Seite nach Consent-Änderung neu laden (`0`/`1`)
68+
- `$fragmentFilename` (`string`): Fragment-Datei
69+
70+
#### getFragmentWithVars()
71+
72+
Wie `getFragment()`, aber mit zusätzlichen Variablen für Custom-Fragmente.
73+
74+
```php
75+
echo Frontend::getFragmentWithVars(0, 0, 'ConsentManager/box_cssjs.php', [
76+
'customClass' => 'my-consent-box'
77+
]);
78+
```
79+
80+
#### setDomain()
81+
82+
Lädt Domain-spezifische Daten (Links, Services, Gruppen, Texte) in die Instanz.
83+
84+
```php
85+
$frontend = new Frontend();
86+
$frontend->setDomain('beispiel.de');
87+
```
88+
89+
#### Wichtige Eigenschaften
90+
91+
Nach `setDomain()` stehen u. a. diese Properties zur Verfügung:
92+
93+
- `$frontend->links['privacy_policy']`
94+
- `$frontend->links['legal_notice']`
95+
- `$frontend->cookiegroups`
96+
- `$frontend->cookies`
97+
- `$frontend->texts`
98+
99+
### Utility
100+
101+
Hilfsfunktionen für Consent-Checks und Domain-Informationen.
102+
103+
```php
104+
use FriendsOfRedaxo\ConsentManager\Utility;
105+
```
106+
107+
#### has_consent()
108+
109+
Prüft, ob ein Service bereits akzeptiert wurde.
110+
111+
```php
112+
if (Utility::has_consent('youtube')) {
113+
// Consent vorhanden
114+
}
115+
```
116+
117+
#### consentConfigured()
118+
119+
Prüft, ob für die aktuelle Host-Konstellation eine nutzbare Consent-Konfiguration existiert.
120+
121+
```php
122+
if (!Utility::consentConfigured()) {
123+
// ggf. Fallback oder Hinweis
124+
}
125+
```
126+
127+
#### hostname() und get_domaininfo()
128+
129+
- `hostname()`: liefert den aktuellen Host inkl. Subdomain (domain-spezifischer Consent)
130+
- `get_domaininfo($url)`: zerlegt eine URL in Domain-Bestandteile
131+
132+
### ConsentManager
133+
134+
Statischer Zugriff auf den aufgebauten Addon-Cache.
135+
136+
```php
137+
use FriendsOfRedaxo\ConsentManager\ConsentManager;
138+
```
139+
140+
Wichtige Methoden:
141+
142+
- `getCache()`
143+
- `getDomains()` / `getDomain($domain)`
144+
- `getCookieGroups(?int $clangId = null)`
145+
- `getCookies(?int $clangId = null)`
146+
- `getTexts(?int $clangId = null)`
147+
- `getCookieData(string $uid, ?int $clangId = null)`
148+
- `getPlaceholderData(string $uid, ?int $clangId = null)`
149+
150+
Beispiel:
151+
152+
```php
153+
$domain = ConsentManager::getDomain('beispiel.de');
154+
$cookies = ConsentManager::getCookies();
155+
```
156+
46157
### InlineConsent
47158

48159
Die `InlineConsent` Klasse bietet Methoden zur automatischen Blockierung von externen Inhalten.

credits.md renamed to docs/credits.md

File renamed without changes.

‎docs/dienste_und_gruppen.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# Dienste und Gruppen konfigurieren
2+
3+
Diese Seite beschreibt die vollständige Pflege von Services (Diensten/Cookies) und Gruppen im Consent Manager – inklusive sicherem Import/Export für Backups und Rollouts auf weitere Instanzen.
4+
5+
## Überblick: Was gehört wohin?
6+
7+
- **Dienste** beschreiben den einzelnen Drittanbieter (z. B. YouTube, Maps, Analytics)
8+
- **Gruppen** bündeln mehrere Dienste für die Consent-UI (z. B. „Statistik“, „Marketing“)
9+
- **Domain-Zuordnung** steuert, wo ein Dienst/eine Gruppe aktiv ist
10+
11+
Empfohlene Reihenfolge:
12+
13+
1. Dienste anlegen
14+
2. Cookie-Definitionen sauber pflegen
15+
3. Dienste in Gruppen zuordnen
16+
4. Domain prüfen
17+
5. Konfiguration exportieren (Backup)
18+
19+
## Dienste anlegen
20+
21+
Backend: `Consent Manager → Dienste`
22+
23+
| Feld | Beschreibung |
24+
|------|--------------|
25+
| Schlüssel | Eindeutiger Key ohne Sonderzeichen (z. B. `youtube`) |
26+
| Dienstname | Anzeigename in der Consent-Box |
27+
| Anbieter | Firma/Anbieter des Dienstes |
28+
| Cookies | YAML-Liste der gesetzten Cookies |
29+
| Script | JavaScript-Code, der erst nach Consent ausgeführt wird |
30+
31+
### Best Practices für Service-Keys
32+
33+
- Keys klein und stabil halten (`youtube`, `google-analytics`, `meta-pixel`)
34+
- Keys nachträglich möglichst nicht ändern, damit bestehende Integrationen stabil bleiben
35+
- Pro technischem Dienst genau einen Service-Eintrag verwenden
36+
37+
## Cookie-Definition (YAML)
38+
39+
Beispiel:
40+
41+
```yaml
42+
-
43+
name: _ga
44+
time: 2 Jahre
45+
desc: "Google Analytics ID"
46+
-
47+
name: _gid
48+
time: 24 Stunden
49+
desc: "Session-Tracking"
50+
```
51+
52+
Hinweise:
53+
54+
- `name`: Cookie-Name
55+
- `time`: Speicherdauer / Laufzeit
56+
- `desc`: Kurze, verständliche Beschreibung für die Doku/Transparenz
57+
58+
## Gruppen erstellen
59+
60+
Backend: `Consent Manager → Gruppen`
61+
62+
- **Technisch notwendig**: immer aktiv, nicht deaktivierbar
63+
- **Dienste zuweisen**: mehrere Services pro Gruppe möglich
64+
- **Domain**: Gruppenzuordnung zu einer Domain
65+
66+
### Empfohlene Gruppenstruktur
67+
68+
- **Essenziell/Technisch notwendig**: nur zwingend erforderliche Dienste
69+
- **Statistik**: Analytics/Reporting
70+
- **Marketing**: Ads, Retargeting, Conversion-Tracking
71+
- **Externe Medien**: YouTube, Vimeo, Karten, Embeds
72+
73+
## Gruppen Domains zuordnen
74+
75+
Backend: `Consent Manager → Gruppen`
76+
77+
So gehst du vor:
78+
79+
1. Gewünschte Gruppe öffnen (z. B. `Statistik`)
80+
2. Im Feld **Domain** die Ziel-Domain(s) zuweisen
81+
3. Gruppe speichern
82+
4. Für weitere Gruppen wiederholen
83+
84+
Wichtig:
85+
86+
- Eine Gruppe wirkt nur auf den zugeordneten Domains
87+
- Bei Multi-Domain-Setups sollten alle relevanten Gruppen pro Domain geprüft werden
88+
- Nach Änderungen kurz Frontend testen (Consent-Box + Service-Verhalten)
89+
90+
### Hinweis zum Setup Wizard
91+
92+
Im Setup Wizard wird die technisch notwendige Gruppe (`required`) automatisch der gewählten Domain zugeordnet. Zusätzliche Gruppen sollten danach manuell geprüft und bei Bedarf ergänzt werden.
93+
94+
## Import/Export (wichtig für Backup und Deployment)
95+
96+
Backend:
97+
98+
- Export: `Consent Manager → Einstellungen → Konfiguration exportieren`
99+
- Import: `Consent Manager → Einstellungen → JSON-Konfiguration importieren`
100+
101+
### Export
102+
103+
Der Export enthält die komplette Konfiguration (u. a. Domains, Dienste, Gruppen, Texte) als JSON.
104+
105+
Typische Anwendungsfälle:
106+
107+
- Backup vor größeren Änderungen
108+
- Übernahme von DEV → Stage → Produktion
109+
- Migration auf andere REDAXO-Instanzen
110+
111+
### Import
112+
113+
Beim Import stehen zwei Modi zur Verfügung:
114+
115+
- **Komplett laden**: überschreibt vorhandene Einstellungen
116+
- **Nur Neue**: ergänzt neue Einträge, bestehende bleiben erhalten
117+
118+
### Empfehlung für sichere Änderungen
119+
120+
1. Vor jeder größeren Änderung Export als Backup ziehen
121+
2. Änderungen zuerst in Testumgebung durchführen
122+
3. Export in Zielumgebung importieren
123+
4. Dienste/Gruppen und Domain-Zuordnung direkt prüfen
124+
125+
## Verwandte Doku
126+
127+
- Schnellstart: [DEV_QUICKSTART.md](DEV_QUICKSTART.md)
128+
- API und Events: [api.md](api.md)
129+
- Inline-Consent: [inline.md](inline.md)
130+
- Gesamtüberblick: [README.md](../README.md)

‎docs/erweiterte_konfiguration.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
# Erweiterte Konfiguration
2+
3+
## Google Consent Mode v2
4+
5+
Backend: `Consent Manager → Domains → Domain bearbeiten`
6+
7+
Modi:
8+
9+
- Deaktiviert
10+
- Auto (empfohlen)
11+
- Manual
12+
13+
Hinweis: Der Helper ist typischerweise nur im Manual-Modus nötig.
14+
15+
## Inline-Only Modus
16+
17+
Unterdrückt das globale Banner; Consent wird bei Bedarf inline abgefragt.
18+
19+
Typische Anwendungsfälle:
20+
21+
- Seiten ohne allgemeines Tracking
22+
- Einzelne Unterseiten mit Videos/Maps
23+
- Progressive Consent-Strategien
24+
25+
## Auto-Blocking für manuell eingefügtes HTML
26+
27+
Backend: `Consent Manager → Einstellungen → Auto-Blocking für manuelles HTML aktivieren`
28+
29+
Einsatzgebiet:
30+
31+
- Manuell eingebettete Scripts/iFrames
32+
- CKE5/Redactor-Inhalte
33+
- Redaktions-Workflows mit wiederkehrenden Embeds
34+
35+
Vertiefung: [inline.md](inline.md)
36+
37+
## CKE5 oEmbed Integration
38+
39+
YouTube/Vimeo-Links können automatisch in datenschutzkonforme Platzhalter umgewandelt werden.
40+
41+
### So aktivierst du CKE5 Auto-Embed
42+
43+
1. Backend öffnen: `Consent Manager → Domains → Domain bearbeiten`
44+
2. CKE5 oEmbed Integration aktivieren
45+
3. Optional Breite/Höhe und Drei-Button-Variante konfigurieren
46+
4. Speichern
47+
48+
### Voraussetzungen
49+
50+
- Inline-Consent-Assets müssen im Frontend verfügbar sein
51+
- Die betroffenen Services (z. B. YouTube/Vimeo) sind als Dienste konfiguriert
52+
- Domain ist korrekt zugewiesen
53+
54+
Vertiefung zur Inline-Integration: [inline.md](inline.md)
55+
56+
### Verhalten im Editor
57+
58+
- Redakteure fügen YouTube-/Vimeo-Links im CKE5 ein
59+
- Im Frontend wird daraus ein datenschutzkonformer Platzhalter
60+
- Das eigentliche Medium wird erst nach Consent geladen
61+
62+
### Schneller Funktionstest
63+
64+
1. Inkognito-Fenster öffnen
65+
2. Seite mit CKE5-oEmbed-Link aufrufen
66+
3. Prüfen, ob Platzhalter statt direktem Embed erscheint
67+
4. Consent erteilen und erneutes Laden prüfen
68+
69+
### Häufige Ursachen, wenn es nicht greift
70+
71+
- Inline-Assets fehlen
72+
- Dienst nicht in Gruppen/Domain aktiv
73+
- Domain- oder Template-Einschränkung blockiert Ausgabe
74+
75+
### Aktivierung
76+
77+
Backend: `Consent Manager → Domains → Domain bearbeiten`
78+
79+
Typische Einstellungen:
80+
81+
- CKE5 oEmbed Integration: Aktiviert
82+
- Video-Breite: z. B. `640`
83+
- Video-Höhe: z. B. `360`
84+
- Drei-Button-Variante: optional
85+
86+
### Voraussetzungen
87+
88+
- CKE5 ist im Einsatz
89+
- Inhalte werden als oEmbed-Link eingefügt (nicht nur als statisches HTML)
90+
- Inline-Assets sind eingebunden, damit Platzhalter sauber dargestellt und bedient werden können
91+
92+
Beispiel im Template:
93+
94+
```php
95+
<link rel="stylesheet" href="<?= rex_url::addonAssets('consent_manager', 'consent_inline.css') ?>">
96+
...
97+
<script defer src="<?= rex_url::addonAssets('consent_manager', 'consent_inline.js') ?>"></script>
98+
```
99+
100+
### Redaktionsablauf
101+
102+
1. YouTube- oder Vimeo-Link in CKE5 einfügen
103+
2. Ausgabe im Frontend prüfen
104+
3. Ohne Consent erscheint ein Platzhalter
105+
4. Nach Zustimmung wird der Inhalt geladen
106+
107+
### Typische Fehlerquellen
108+
109+
- Kein Platzhalter sichtbar: Inline-Assets fehlen
110+
- Embed lädt sofort: Dienst/Gruppenzuordnung prüfen
111+
- Falsche Darstellung: Breite/Höhe und Theme-Einstellungen kontrollieren
112+
113+
Vertiefung:
114+
115+
- Inline-Consent: [inline.md](inline.md)
116+
- Dienste & Gruppen: [dienste_und_gruppen.md](dienste_und_gruppen.md)
117+
118+
## Multi-Domain
119+
120+
Mehrere Domains können getrennt konfiguriert werden (Services, Texte, Themes).
121+
122+
## Mehrsprachigkeit
123+
124+
Texte und Service-Skripte können sprachspezifisch gepflegt werden, inkl. Fallback.
125+
126+
## Datensicherung, Import und Export
127+
128+
Backend:
129+
130+
- Export: `Consent Manager → Einstellungen → Konfiguration exportieren`
131+
- Import: `Consent Manager → Einstellungen → JSON-Konfiguration importieren`
132+
133+
Import-Modi:
134+
135+
- **Komplett laden**
136+
- **Nur Neue**
137+
138+
Ausführliche Praxishinweise: [dienste_und_gruppen.md](dienste_und_gruppen.md)

inline.md renamed to docs/inline.md

File renamed without changes.

0 commit comments

Comments
 (0)