# Social Lead System – Browser-Erweiterung (Entwicklungsartefakt)

Dieses Verzeichnis enthält eine minimale Chrome-Browser-Erweiterung (Manifest V3).
Sie dient ausschließlich dem Test, ob der Endpunkt

    /api/extension/status

der Social-Lead-System-Webanwendung erreichbar ist, sowie der rein lesenden
Erkennung der aktuell geöffneten Facebook-/Messenger-Seite.

## Was die Erweiterung NICHT tut

- Keine Facebook-Automatisierung
- Kein Auslesen von Facebook-Daten über das hinaus, was im Popup angezeigt wird
- Keine Freundschaftsanfragen
- Keine Nachrichten, Likes, Kommentare
- Keine automatischen Klicks oder Navigation auf Facebook
- Keine Kontaktübertragung an Automation.Studio
- Keine Speicherung personenbezogener Facebook-Daten im Social Lead System
- Keine Hintergrundautomatisierung / permanente Überwachung
- Keine Umgehung von Facebook-Schutzmechanismen
- Keine Speicherung von API-Schlüsseln, Tokens oder Secrets

## Dateien

- `manifest.json` – Manifest V3
- `popup.html` – Popup-Struktur
- `popup.css` – Popup-Design
- `popup.js` – Popup-Logik (Verbindungstest + Seitenerkennung)
- `page-detector.js` – rein lesende Erkennungslogik (wird on-demand injiziert)
- `icon16.png`, `icon32.png`, `icon48.png`, `icon128.png` – Symbole

## Berechtigungen

- `storage` – zum lokalen Speichern der eingetragenen Systemadresse in `chrome.storage.local`.
- `permissions` – erforderlich, um die optionale Host-Berechtigung zur Laufzeit über `chrome.permissions.request` gezielt anzufordern.
- `scripting` – zum On-Demand-Injizieren von `page-detector.js` in den aktiven Tab (nur auf Nutzergest).
- `activeTab` – erlaubt den Lesezugriff auf den aktiven Tab ohne dauerhafte Host-Berechtigung; der Zugriff gilt nur für den jeweiligen Nutzergest (Popup öffnen / „Seite neu erkennen“).
- `host_permissions` ist bewusst leer.
- `optional_host_permissions`: `http://*/*` und `https://*/*` (nur für die frei einstellbare Systemadresse, gezielt angefordert).

### Entscheidung: activeTab + scripting statt Content Script

Die Facebook-Erkennung wird bewusst NICHT als permanentes Content Script
umgesetzt. Stattdessen wird `page-detector.js` per `chrome.scripting.executeScript`
nur dann injiziert, wenn der Nutzer das Popup öffnet oder „Seite neu erkennen“
wählt. Vorteile:

- Keine permanente Hintergrundüberwachung.
- Zugriff nur auf den aktiven Tab und nur für den jeweiligen Nutzergest.
- Keine dauerhafte Host-Berechtigung für Facebook nötig (`activeTab` genügt).

### Host-Berechtigungen für Facebook

Für die rein lesende Erkennung ist dank `activeTab` **keine** zusätzliche
Host-Berechtigung für Facebook erforderlich. Die Erweiterung arbeitet nur auf
den unterstützten Domains, prüft dies aber zur Laufzeit im Code
(`isSupportedFbUrl`), nicht über eine pauschale Manifest-Berechtigung.

Unterstützte Domains (im Code geprüft):

- `https://www.facebook.com/*`
- `https://facebook.com/*`
- `https://m.facebook.com/*`
- `https://mbasic.facebook.com/*`
- `https://web.facebook.com/*`
- `https://www.messenger.com/*`
- `https://messenger.com/*`

Auf allen anderen Seiten zeigt die Erkennung „Andere Seite / Nicht unterstützt“.

### Entscheidung zur Host-Berechtigung (Systemadresse)

Die Erweiterung ruft eine vom Benutzer frei einstellbare Systemadresse ab.
Da die Adresse erst zur Laufzeit eingetragen wird, kann keine feste
Host-Berechtigung im Manifest hinterlegt werden. Deshalb werden `http://*/*`
und `https://*/*` als optionale Host-Berechtigungen deklariert und beim
Verbindungstest gezielt nur für die eingetragene Origin angefordert.

## Systemadresse

Die Adresse wird einmal eingetragen, lokal gespeichert und zu

    SYSTEMADRESSE + /api/extension/status

ergänzt. Es werden keine API-Schlüssel, Tokens oder Secrets gespeichert.

## Aktuelle Seite erkennen

Beim Öffnen des Popups wird automatisch einmal die aktuell geöffnete Seite
erkannt. Mit „Seite neu erkennen“ wird die Erkennung erneut ausgeführt.
Erkannt werden:

- Plattform (Facebook / Messenger / Andere Seite)
- Seitentyp (Profil / Gruppe / Beitrag / Messenger / Facebook – sonstige Seite / Nicht unterstützt)
- Bezeichnung (nur wenn zuverlässig erkennbar, sonst „Nicht erkannt“)
- URL

Die Erkennung orientiert sich an URL-Struktur, Seitentitel und semantischen
Überschriften, nicht an wechselnden Facebook-CSS-Klassen. Da Facebook eine
dynamische Single-Page-Anwendung ist, wird bei jedem Erkennungsaufruf der
aktuelle Zustand neu ausgelesen.

Die erkannten Informationen bleiben ausschließlich lokal im Browser. Sie
werden NICHT an /api gesendet, NICHT in Automation.Studio gespeichert und
NICHT dauerhaft in chrome.storage abgelegt.

## Lokaler Test in Chrome

1. Chrome öffnen.
2. `chrome://extensions` aufrufen.
3. „Entwicklermodus“ oben rechts aktivieren.
4. „Entpackte Erweiterung laden“ wählen und dieses `extension/`-Verzeichnis auswählen.
5. Das Erweiterungssymbol in der Symbolleiste anklicken.
6. Systemadresse eintragen (z. B. die Adresse der Webanwendung) und „Adresse speichern“ wählen.
7. „Verbindung prüfen“ wählen. Beim ersten Abruf die Host-Berechtigung für die eingetragene Adresse bestätigen.

### Verbindungstest

Bei Erfolg erscheint „Systemverbindung funktioniert.“.
Bei Fehler erscheint zusätzlich eine kleine technische Hinweismeldung
(z. B. zu CORS, URL, abgelehnter Berechtigung oder Netzwerk).

### Seitenerkennung testen

Öffne nacheinander verschiedene Seiten und klicke jeweils das Erweiterungssymbol:

1. Normale Nicht-Facebook-Seite → Plattform „Andere Seite“, Seitentyp „Nicht unterstützt“.
2. Facebook-Startseite (facebook.com) → „Facebook – sonstige Seite“.
3. Facebook-Profil → „Profil“.
4. Facebook-Gruppe → „Gruppe“.
5. Facebook-Beitrag → „Beitrag“.
6. Messenger → „Messenger“.

Falls eine Bezeichnung nicht zuverlässig erkannt wird, steht „Nicht erkannt“.
Das ist kein technischer Fehler.