Ruboja Assistants (WordPress-Plugin)

Bindet Ruboja-Assistenten auf einer WordPress-Seite ein, inline im Inhalt oder als schwebendes Chatfenster. Der Assistent läuft genau so, wie er in Ruboja eingerichtet ist: System-Prompt, Wissen, Werkzeuge, festes Modell und Startformular.

So funktioniert es

Besucher klickt „Assistent starten“
  → Browser: POST /wp-json/ruboja-assistants/v1/sessions  { assistant }
  → WordPress prüft Freigabe, Login-Pflicht und Rate-Limit
  → WordPress: POST https://api.ruboja.de/api/v1/chat-sessions  (Bearer API-Schlüssel)
  → Ruboja liefert eine Einmal-URL (10 Minuten gültig, einmal einlösbar)
  → Browser zeigt die URL im iFrame, der Chat läuft direkt mit Ruboja

Der API-Schlüssel verlässt nie den Server. Er liegt verschlüsselt in der Datenbank (libsodium, Schlüssel aus den Salts in wp-config.php) oder als Konstante in wp-config.php.

Einrichtung

1. In Ruboja unter Einstellungen → API-Schlüssel einen Schlüssel erzeugen. Nutzer-Zuordnung „Optional“ wählen, sonst können anonyme Besucher nichts starten. Der Schlüssel hat die Rechte seines Erstellers, er sieht also nur dessen Assistenten. Den Schlüssel mit einem technischen Ruboja-Nutzer erzeugen (z. B. „Website“): Ruboja begrüßt anonyme Besucher mit dem Vornamen des Schlüssel-Erstellers („Hallo Enrico, schön dich zu sehen!“), und ihre Chats laufen auf dessen Konto.
2. Plugin installieren (Zip aus dem neuesten GitHub-Release) und aktivieren.
3. Einstellungen → Ruboja-Assistenten: Schlüssel eintragen, speichern. Die Liste der Assistenten wird geladen.
4. Gewünschte Assistenten freigeben und speichern.
5. Block „Ruboja-Assistent“ einfügen oder Shortcode verwenden.

Schlüssel per wp-config.php statt Datenbank:

define( 'RUBOJA_ASSISTANTS_API_KEY', 'sk_live_…' );

Die API-Adresse ist fest https://api.ruboja.de/api/v1 und erscheint nicht in den Einstellungen. Nur für ein Ruboja-Testsystem lässt sie sich überschreiben (nur https):

define( 'RUBOJA_ASSISTANTS_API_BASE', 'https://…/api/v1' );

Shortcode

[ruboja_assistant id="6ad744a4c3e693b346da671a"]
[ruboja_assistant id="…" mode="floating" label="Fragen? Jetzt chatten" position="left"]
[ruboja_assistant id="…" height="800" title="Vorauszahlungen prüfen" color="#1f3a5f"]

Höhe und Kopfzeile

• Ruboja meldet seine Inhaltshöhe nicht an die einbettende Seite. Die Höhe eines Inline-Assistenten wird deshalb fest eingestellt (Block: „Höhe“, Shortcode: height). Für ein langes Startformular wie beim Vorauszahlungs-Assistenten passen etwa 1.050 px bei normaler Inhaltsbreite; auf dem Handy wird das Formular länger (gemessen: ca. 1.225 px bei 420 px Breite) und scrollt dann im iFrame.
• Ruboja-Kopfzeile ausblenden (Standard an): Logo, Assistentenname und Organisation stehen in einer 60 px hohen Zeile, die sich in Ruboja nicht abschalten lässt. Das Plugin schiebt den iFrame um diese Höhe nach oben und schneidet sie ab. Ändert Ruboja sein Layout, die Option ausschalten oder per CSS anpassen: .ruboja-assistant { --ruboja-header-offset: 60px; }
• Begrüßung abschneiden (experimentell, Standard aus): Ruboja begrüßt mit einem zufälligen Satz samt Vorname („Schön, dass du da bist, Enrico!“), ohne Einstellung zum Abschalten. Die Option schneidet zusätzlich 98 px ab, aber nur ab 640 px Breite: Schmaler bricht die Begrüßung je nach Satz um, sie bleibt dann sichtbar statt halb abgeschnitten. Inline-Höhe dabei etwa 100 px niedriger wählen (Vorauszahlungs-Assistent: ca. 950 px) und lieber etwas zu knapp, sonst zentriert Ruboja den Inhalt und die Begrüßung rutscht ins Bild. Nach dem Start des Gesprächs bleiben die obersten ca. 100 px des Chats verdeckt. Feinjustierung per CSS: .ruboja-assistant { --ruboja-greeting-offset: 98px; }

Datenschutz

• Laden erst nach Klick (Standard an): Bis zum Klick geht keine Verbindung zu Ruboja.
• Verlauf für wiederkehrende Besucher (Standard aus): setzt ein funktionales Cookie ruboja_assistants_visitor mit Zufalls-ID. Ruboja bekommt nur einen daraus abgeleiteten HMAC als reference_id. Ohne Verlauf bekommt jede Sitzung eine neue Zufallsreferenz.
• Nutzer-Zuordnung (Standard aus): schickt für angemeldete WordPress-Nutzer die E-Mail-Adresse als X-User-Mail. Gedacht für Intranets, deren Nutzer auch in Ruboja sind.
• Ohne Nutzer-Zuordnung laufen alle Chats anonym auf dem Konto des Schlüssel-Erstellers (Ruboja-Modus operator).

Design

• Backend im Ruboja-CD: Einstellungsseite und Block im Editor folgen dem Ruboja-CD (gemessen auf ruboja.de, Oktober 2026): Rot #df252b, Schrift Outfit, flache Buttons mit 9 px Rundung, weiße Karten mit 1 px Rand #e9ecef und 18 px Rundung, Text #1a1a1a / #2e2e2e, Ruboja-Zeichen im Seitenkopf.
• Front-End neutral: Auf der Website übernimmt der Assistent die Schrift des Themes und die eingestellte Akzentfarbe (Standard Dunkelblau #1f3a5f), damit er zum Design der jeweiligen Website passt.
• Schrift Outfit liegt im Plugin (assets/fonts/, Latin-Teilmenge aus @fontsource-variable/outfit 5.3.0, 32 KB, SIL Open Font License 1.1, siehe assets/fonts/OFL.txt). Sie wird nur im Backend geladen, unter dem eigenen Namen „Ruboja Outfit“ und vom eigenen Server.

Wo der API-Schlüssel liegt

• Nie in den Plugin-Dateien. Der Schlüssel steht verschlüsselt in der Datenbank (wp_options, Option ruboja_assistants_api_key, Format v1:…) oder als Konstante in der wp-config.php. Wer den Plugin-Ordner herunterlädt (FTP, Dateimanager des Hosters, Download-Plugins) oder die Release-Zip weitergibt, gibt keinen Schlüssel weiter.
• Löschen über Plugins → Löschen entfernt Schlüssel, Einstellungen und Assistentenliste (uninstall.php, auch auf allen Seiten einer Multisite). Deaktivieren behält alles, damit nach dem Reaktivieren nichts neu einzurichten ist.
• Ordner per FTP entfernen löscht nichts in der Datenbank, denn WordPress führt uninstall.php dann nicht aus. Den Schlüssel vorher in den Einstellungen mit „Gespeicherten Schlüssel entfernen“ löschen oder in Ruboja widerrufen.
• Komplette Website-Sicherungen (Datenbank und wp-config.php, auch Staging-Kopien) enthalten den verschlüsselten Schlüssel und die Salts, mit denen er sich entschlüsseln lässt. Gerät so eine Sicherung in falsche Hände: Schlüssel in Ruboja unter Einstellungen → API-Schlüssel widerrufen und neu erzeugen.

Dateiprüfung und Meldung an den Entwickler

• Jedes Release trägt checksums.json mit den SHA-256-Prüfsummen aller Plugin-Dateien (bin/build-zip.sh → bin/make-checksums.py, Release-Workflow hängt sie an).
• Jede Installation lädt täglich die Liste ihrer Version von GitHub und vergleicht (includes/class-integrity.php). Ergebnis: unverändert, verändert (geänderte, fehlende, hinzugefügte Dateien), nicht prüfbar (keine Liste erreichbar), Entwicklungskopie (.git).
• Meldung an den Entwickler: Bei neuen Abweichungen und wenn wieder alles stimmt, schickt die Website eine E-Mail an Integrity::DEVELOPER_EMAIL (enricomiebach@gmail.com): Website, Plugin-, WordPress- und PHP-Version, Status, Dateinamen und denselben Bericht als JSON. Keine personenbezogenen Daten. Immer an, offengelegt in readme.txt und auf der Einstellungsseite. Der Absender ist der Standard von WordPress (wordpress@<domain>); ohne funktionierenden Mailversand der Website geht die Meldung verloren.
• Ruboja-Datenquelle (vorbereitet): Integrity::REPORT_WEBHOOK auf die Webhook-Adresse einer Datenquelle in Siteware GmbH setzen, dann geht derselbe JSON-Bericht zusätzlich dorthin (z. B. für ein Dashboard aller Installationen).
• Sichtbar für Betreiber unter Werkzeuge → Website-Zustand und in der Karte „Dateiprüfung“.
• Grenze: Wer die Plugin-Dateien ändern kann, kann auch die Prüfung entfernen. Sie erkennt Änderungen, fehlerhafte Uploads und abgelegte Dateien, keinen gezielten Angreifer mit vollem Serverzugriff.

Entwicklung

Voraussetzungen: Docker, Node.js 20+.

npm install
npm run env:start        # WordPress auf http://localhost:8888 (admin / password)
npm run composer install # PHP-Werkzeuge im Container installieren
npm run lint:php         # WordPress Coding Standards
npm run test:php         # PHPUnit gegen die WordPress-Testsuite
npm run i18n:pot         # languages/ruboja-assistants.pot neu erzeugen
npm run i18n:compile     # .po → .mo und .json
npm run build:zip        # dist/ruboja-assistants.zip und dist/checksums.json
npm run downloads        # Downloads je Release und gesamt

Aufbau:

Versionierung und Releases

Versionen folgen SemVer. Ein Release in vier Schritten:

bin/bump-version.sh 0.2.0     # Version in allen Dateien setzen
# CHANGELOG.md: Abschnitt "## [0.2.0] - JJJJ-MM-TT" anlegen (wird zum Release-Text)
git commit -am "Release 0.2.0"
git tag v0.2.0 && git push origin main v0.2.0

Der Workflow release.yml prüft, dass Tag und Versionen übereinstimmen, nimmt den CHANGELOG-Abschnitt als Release-Text, baut ruboja-assistants.zip und veröffentlicht das GitHub-Release.

Updates in WordPress

• Installierte Seiten zeigen die neue Version unter Plugins („Jetzt aktualisieren“) und unter Dashboard → Aktualisierungen. Automatische Updates lassen sich in der Plugin-Liste einschalten. Grundlage ist der Header Update URI (https://github.com/EnricoMiebach/ruboja-assistants), das Repository ist öffentlich.
• WordPress fragt etwa alle 12 Stunden nach, das Plugin merkt sich das Release 6 Stunden. Sofort geht es mit Dashboard → Aktualisierungen → Erneut prüfen.
• „Details ansehen“ zeigt die Release-Notizen.
• Eine Kopie mit .git-Ordner (Entwicklung, wp-env) bekommt nie ein Update angeboten, damit WordPress kein Arbeitsverzeichnis überschreibt. Updates also immer an einer Installation aus der Release-Zip testen.
• Bei einem privaten Repository bräuchte jede Seite ein Token mit Lesezugriff: define( 'RUBOJA_ASSISTANTS_GITHUB_TOKEN', 'github_pat_…' ); (nicht getestet).

Downloads zählen

GitHub zählt jeden Download einer Release-Datei. npm run downloads (oder bin/downloads.py) zeigt die Zahlen je Release und gesamt:

• Zip: Downloads von ruboja-assistants.zip, also manuelle Downloads, Neuinstallationen und jedes Update, das WordPress von GitHub holt. Eine Website zählt pro Update einmal.
• Prüfungen: Abrufe von checksums.json durch die tägliche Dateiprüfung (ab 0.1.9), höchstens etwa zwei pro Website und Tag. Daraus lässt sich die Zahl aktiver Installationen grob ablesen.

Das Badge oben zeigt die Zip-Downloads der neuesten Version. Ein Badge für die Zip über alle Versionen bietet shields.io nicht an; das „total“-Badge würde die Prüfsummen-Abrufe mitzählen.

Lizenz

GPL-2.0-or-later, siehe LICENSE.