Docs Sync: Update from com_kickbannerstats commit 4e4a8ee86353285b48914240257d8960b41cac12

Author: Kicktemp Bot

src/components/com_kickbannerstats/api-integration.md

@@ -0,0 +1,72 @@
+# API & Looker Studio Integration
+
+KickBannerStats stellt eine JSON-API über den Joomla API Wrapper bereit. Diese wird primär genutzt, um Daten an **Google Looker Studio** zu übergeben.
+
+## API Endpoint
+
+Der Zugriff erfolgt über den `StatisticsController`.
+
+**Basis-URL:**
+
+### Authentifizierung
+Die API nutzt die Standard Joomla API Token Authentifizierung (`Bearer Token` oder `X-Joomla-Token`).
+
+### Filter-Parameter
+Die API unterstützt folgende GET-Parameter zur Filterung:
+
+| Parameter | Typ | Beschreibung |
+| :--- | :--- | :--- |
+| `filter[begin]` | String (Y-m-d) | Startdatum (inklusiv) |
+| `filter[end]` | String (Y-m-d) | Enddatum (inklusiv) |
+| `filter[client_id]` | Int | Nur spezifischer Kunde |
+| `filter[banner_id]` | Int | Nur spezifisches Banner |
+
+## Beispiel Response
+https://ihre-domain.de/api/index.php/v1/kickbannerstats/statistics
+
+```json
+[
+    {
+        "date": "2026-01-20",
+        "banner_id": 422,
+        "client_id": 13,
+        "impressions": 1319,
+        "clicks": 3,
+        "banner_name": "Musical Kids Amulett",
+        "client_name": "besser-im-blick",
+        "updated_at": "2026-02-12 13:37:39"
+    },
+    {
+        "date": "2026-01-19",
+        "banner_id": 422,
+        "client_id": 13,
+        "impressions": 41324,
+        "clicks": 38,
+        "banner_name": "Musical Kids Amulett",
+        "client_name": "besser-im-blick",
+        "updated_at": "2026-02-12 13:37:39"
+    }
+]
+```
+
+Looker Studio Connector
+Um diese Daten in Looker Studio zu nutzen, benötigen Sie ein Google Apps Script (Community Connector), welches diese API konsumiert.
+
+Schema Definition
+Im Connector mappen Sie die JSON-Felder wie folgt:
+
+date -> Datum (YYYYMMDD)
+
+banner_name -> Text
+
+client_name -> Text
+
+impressions -> Zahl
+
+clicks -> Zahl
+
+CTR -> Berechnetes Feld (clicks / impressions)
+
+::: tip Caching
+Da die Daten in #__kickbannerstats_daily nur einmal täglich aktualisiert werden, empfiehlt es sich, im Looker Studio Connector ein Caching von 12 bis 24 Stunden zu aktivieren.
+:::

src/components/com_kickbannerstats/architecture.md

@@ -0,0 +1,25 @@
+# Architektur & Datenbank
+
+Der Kern von KickBannerStats ist die Entkopplung von "Schreiben" (Joomla Core) und "Lesen" (KickBannerStats).
+
+## Datenbank-Schema
+
+Die Komponente nutzt eine eigene, flache Tabelle zur Speicherung der Tageswerte pro Banner und Kunde.
+
+```sql
+CREATE TABLE IF NOT EXISTS `#__kickbannerstats_daily`
+(
+  `date` DATE NOT NULL,
+  `banner_id` INT UNSIGNED NOT NULL,
+  `client_id` INT UNSIGNED NOT NULL,
+  `impressions` INT UNSIGNED NOT NULL DEFAULT 0,
+  `clicks` INT UNSIGNED NOT NULL DEFAULT 0,
+  `banner_name` VARCHAR(255) NOT NULL,
+  `client_name` VARCHAR(255) NOT NULL,
+  `updated_at` DATETIME NOT NULL,
+  PRIMARY KEY (`date`, `banner_id`, `client_id`),
+  KEY `idx_banner_date` (`banner_id`, `date`),
+  KEY `idx_client_date` (`client_id`, `date`)
+) ENGINE = InnoDB
+  DEFAULT CHARSET = utf8mb4
+  DEFAULT COLLATE = utf8mb4_unicode_ci;

src/components/com_kickbannerstats/backend.md

@@ -0,0 +1,20 @@
+# Einführung
+
+**KickBannerStats** ist eine spezialisierte Joomla-Komponente, die entwickelt wurde, um die Performance von Banner-Auswertungen zu optimieren und eine nahtlose Integration mit Business-Intelligence-Tools wie **Google Looker Studio** zu ermöglichen. 
+
+## Das Problem
+Die native Joomla-Tabelle `#__banner_tracks` speichert jeden einzelnen View und Klick als separate Zeile. Bei stark frequentierten Seiten wächst diese Tabelle schnell auf Millionen von Einträgen an.
+* **Performance:** Direkte Abfragen für Zeiträume (z.B. "Letzter Monat") werden extrem langsam.
+* **Externe Tools:** APIs laufen in Timeouts, wenn sie versuchen, Rohdaten live zu aggregieren.
+
+## Die Lösung
+KickBannerStats entkoppelt die Datenerfassung von der Auswertung:
+1.  **Aggregation:** Ein Task-Plugin verdichtet die Rohdaten täglich in eine optimierte Tabelle (`#__kickbannerstats_daily`).
+2.  **Performance:** Statt Millionen Zeilen zu scannen, greift die API auf wenige tausend vorbrechnete Datensätze zu.
+3.  **Konnektivität:** Eine spezialisierte API liefert JSON-Daten, die perfekt für Looker Studio formatiert sind.
+
+## Features
+* 🚀 **High-Performance:** Schnelle Dashboards auch bei großen Datenmengen.
+* 🤖 **Automatisierung:** `Scheduler Task` für tägliche Updates.
+* back **Backfill:** Nachträglicher Import historischer Daten.
+* 📊 **Looker Studio Ready:** Native JSON-Ausgabe für Community Connectors.

src/components/com_kickbannerstats/index.md

@@ -0,0 +1,21 @@
+{
+  "text": "KickBannerStats",
+  "items": [
+    {
+      "text": "Einführung",
+      "link": "/components/com_kickbannerstats/"
+    },
+    {
+      "text": "Architektur",
+      "link": "/components/com_kickbannerstats/architecture"
+    },
+    {
+      "text": "Backend Nutzung",
+      "link": "/components/com_kickbannerstats/backend"
+    },
+    {
+      "text": "API Integration",
+      "link": "/components/com_kickbannerstats/api-integration"
+    }
+  ]
+}