cat docs/theming-embedding.md
Alle Anleitungen Zuletzt aktualisiert

Design und Einbindung

Jeder Agent hat einen Tab „Darstellung“ für das Aussehen und einen Tab „Einbinden“ für die Einbindung. Ihre Änderungen sehen Sie sofort in der Vorschau.

Design

Der Tab „Darstellung“ ist so gegliedert, wie Sie meist vorgehen.

  • Unter „Layout“ legen Sie Größe und Form des Fensters fest. Die Breite reicht bis 800 px, die Höhe bis 1.000 px. Beides gilt auf dem Desktop für das schwebende Layout und die Seitenleiste. Auf Mobilgeräten nutzt das Widget immer den ganzen sichtbaren Bereich, und das ganzseitige Layout füllt seinen Container aus.
  • Unter „Farben“ färben Sie Kopfzeile, Chat-Blasen, Eingabefeld und die übrigen Bedienelemente. Schalten Sie auf „Erweitert“ um, erhalten Sie die volle Palette mit Rahmenlinien.
  • Unter „Symbol des Chat-Knopfs“ wählen Sie das Symbol auf dem Chat-Knopf.
  • Unter „Texte“ legen Sie Titel und Untertitel der Kopfzeile fest, die Begrüßung zu Beginn des Chats und den Platzhaltertext im Eingabefeld.
  • Unter „Schatten“ stellen Sie die Schatten von Chat-Knopf, Fenster und Eingabefeld fein ein.
  • Unter „Gehostete Seite“ wählen Sie den Hintergrund der eigenständigen Seite, die Sie teilen können (siehe unten).

Sie müssen nicht alles ausfüllen. Beginnen Sie mit der Standarddarstellung und ändern Sie nur, was Sie anders haben möchten.

Auf Ihrer Website einbinden

Öffnen Sie den Tab „Einbinden“ und kopieren Sie den Einbettungscode. Fügen Sie ihn auf jeder Seite, auf der der Chat erscheinen soll, direkt vor dem schließenden </body>-Tag ein. Der Chat-Knopf lädt asynchron und hält den Aufbau Ihrer Seite nicht auf.

Zur Wahl stehen ein schwebender Chat-Knopf, eine angedockte Seitenleiste, eine ganzseitige Ansicht und ein Inline-Element, das dort erscheint, wo Sie einen Container platzieren. Den passenden Code für jedes Layout zeigt der Tab „Einbinden“.

Sendet Ihre Website eine strenge Content-Security-Policy, müssen Sie unter Umständen die Origins des Oshu-Skripts und seiner Verbindungen freigeben. Welche Direktiven Sie ergänzen müssen, steht im Tab „Einbinden“.

Seitenkontext

Der Chat kann erfahren, auf welcher Seite er sich befindet. Bei neuen Agenten ist das ausgeschaltet. Schalten Sie es ein, erhält der Chat die Adresse der Seite (ohne Tracking-Parameter, weitere Abfrageparameter und Fragmente), ihren Titel, ihre erste Überschrift und ihren Navigationspfad (Breadcrumbs), aber nie den Seitentext. Diese Angaben dienen nur als Hinweis darauf, worum es in einer Frage geht. Wird der Seitenkontext genutzt, sehen Besuchende den Seitentitel in einer kleinen Zeile über dem Eingabefeld.

  • Ein- und ausschalten können Sie den Seitenkontext pro Agent im Tab „Konfiguration“ („Aktuelle Seite einbeziehen“). Ist er aus, chatten Besuchende ganz normal weiter, nur erhält der Assistent keine Hinweise zur Seite.
  • Der private Modus ist keine Ausnahme. Auch ein privates Gespräch erhält den Hinweis zur Seite, denn davon wird nichts gespeichert. Der Hinweis wird nur mit dieser einen Anfrage übermittelt. Der private Modus regelt, was gespeichert wird, nicht, was das Modell bei der gerade gesendeten Nachricht sehen kann.
  • Ein Hinweis auf das Thema, keine Quelle. Der Assistent erfährt, wo sich Besuchende gerade befinden. Er liest Ihre Seite nicht, ruft nichts von ihr ab und prüft nichts davon nach. Mit Quellenangabe belegen kann er nur Inhalte, die Sie in Ihre Bibliotheken aufgenommen haben.
  • Agenten, die nur PDFs als Quellen haben, erhalten den Seitentitel ebenfalls als Hinweis, aber ohne Auszug. Aus der Seite im Browser selbst wird nichts abgerufen.

Einbindung per Iframe (Lernplattform, Moodle, Canvas)

Der einfache <iframe>-Code aus dem Tab „Einbinden“ funktioniert ohne Änderungen und ohne JavaScript auf Ihrer Seite. Den Seitenkontext ergänzen Sie in zwei Schritten.

  1. Tragen Sie die genauen Origins der Seiten, auf denen Sie den Chat einbinden, beim Agenten unter „Erlaubte Websites“ ein (zum Beispiel https://moodle.example.de). Platzhalter (Wildcards), reine Hostnamen und eine leere Liste akzeptiert Oshu für die Weitergabe der Seite nicht. Der Chat funktioniert weiterhin überall, wo Sie ihn zulassen, erfährt dann aber nicht, auf welcher Seite er läuft.
  2. Schalten Sie im Tab „Einbinden“ unter „Seitenkontext“ die Option ein und fügen Sie den zweiten Code ein. Er ergänzt ein Skript, das dem Iframe die Adresse der Seite (ohne Tracking-Parameter, weitere Abfrageparameter und Fragmente), ihren Titel, ihre erste Überschrift und ihren Navigationspfad übergibt.

In einer Single-Page-App ändert sich der Seitentitel, während Besuchende navigieren, und der Chat folgt automatisch. Verwaltet Ihr Router ein eigenes Seitenmodell, können Sie es stattdessen direkt übergeben.

const bridge = ChatWidget.connectIframeContext(document.querySelector('#oshu-chat-frame'));
bridge.setPageContext({ title: 'Lecture 4 — Duality', heading: 'Dual problem' });
// later, or on a page with nothing meaningful to say:
bridge.setPageContext(null);

Die Verbindung öffnet der Chat-Iframe, nicht Ihre Seite, und erst dann, wenn die Funktion für den Agenten freigegeben ist. Titel werden auf eine Höchstlänge gekürzt und bereinigt, und der Iframe ignoriert alles, was von einem Origin kommt, der nicht unter „Erlaubte Websites“ steht.

Feste Start-URLs

Der Tab „Einbinden“ kann einen Seitentitel auch fest als Fragment #oshu-page=… in die Iframe-URL schreiben. Bevor Sie das nutzen, sollten Sie zwei Einschränkungen kennen.

  • Der Titel wird beim Erzeugen des Codes festgelegt und folgt deshalb nicht der Navigation auf einer Single-Page-Website. Wechseln Ihre Seiten ohne Neuladen, nutzen Sie das oben beschriebene Skript.
  • URL-Fragmente erscheinen in der Adresszeile, im Browserverlauf und oft auch in den Zugriffsprotokollen von Servern. Schreiben Sie nie etwas Vertrauliches hinein, und lassen Sie das Fragment leer, wenn schon der Seitentitel privat ist (ein Studierendenname, ein Einzelfall, ein Entwurf).

Gehostete Seite zum Teilen

Sie haben keine Website, auf der Sie den Chat einbinden können, oder möchten einen direkten Link? Schalten Sie beim Agenten „Öffentliche Seite aktivieren“ ein. Oshu stellt dann für diesen Agenten eine eigenständige Seite unter einer eigenen URL bereit. Im Dashboard erhalten Sie einen Link zum Kopieren und einen QR-Code zum Teilen. Die Seite wird für Sie erzeugt, ein eigenes Hosting brauchen Sie nicht.

Workspace-Seite

Für alle, die wiederkommen, etwa Studierende im Lauf eines Semesters, schalten Sie im Tab „Gehostete Seiten“ des Agenten „Workspace-Seite aktivieren“ ein. Das ist eine vollständige Chat-Seite mit einer Liste früherer Gespräche am linken Rand. Besuchende machen dort ohne Konto weiter, wo sie aufgehört haben. Die Liste wird auf dem Gerät der Besuchenden gespeichert, und private Chats bleiben dort vollständig erhalten.

Sie können die Seite mit einem Passwort schützen („Zugangspasswort“), das alle teilen, denen Sie den Link geben. Unter „Link mit Passwort“ erhalten Sie dann einen Link, der die Seite direkt entsperrt. Diesen Link können Sie auf einer Kursseite veröffentlichen, die nur Ihre Studierenden sehen, zum Beispiel in Moodle. Ändern Sie das Passwort, funktionieren frühere Links nicht mehr.

Siehe auch: Agenten und Erste Schritte.