Storefront-Erweiterungen

Diese Anleitung ergänzt eine öffentliche Workspace-Storefront um Contact Forms und Website Chat. Nutzen Sie beide Erweiterungen nur über öffentliche Verträge. Der Shop sammelt Eingaben und rendert den Widget-Zustand; Workspace entscheidet über Annahme, Routing, Spam-Behandlung, Chat-Status und interne Verarbeitung.

Voraussetzungen

Klären Sie vor der Einbindung:

  • Die Storefront läuft auf einer freigegebenen öffentlichen Origin der aktiven Site.
  • Die Administration hat für jede Contact Form ein aktives Ingress mit erlaubten Origins angelegt.
  • Die Administration hat für Website Chat ein aktives Widget mit erlaubten Origins und Routing angelegt.
  • Sie haben den öffentlichen formKey oder widgetKey erhalten.

Verwenden Sie keine internen IDs, Queue-IDs, Konversations-IDs oder Admin-Endpunkte im Client. Sites richten Administratoren in Sites und CMS ein; Chat-Widget-Eingänge stehen in Website Chat.

Contact Forms einbinden

Senden Sie Formularübermittlungen an den öffentlichen Contact-Forms-Endpunkt:

http
POST /api/v1/public/v1/contact-forms/{formKey}/submissions

formKey ist ein öffentlicher, opaker Schlüssel. Speichern Sie ihn wie Konfiguration für die Seite und leiten Sie daraus keine interne Formular-, Ingress- oder Routing-ID ab.

Senden Sie JSON mit Nachricht und mindestens einem erreichbaren Kontaktwert:

json
{
  "name": "Ada Lovelace",
  "companyName": "Analytical Engines Ltd",
  "email": "ada@example.test",
  "phone": "+49 30 123456",
  "message": "Bitte rufen Sie mich zurück.",
  "pageUrl": "https://www.example.test/kontakt",
  "honeypot": "",
  "filledSeconds": 8
}

Der Browser sendet den Origin-Header normal mit. Workspace prüft diese Origin gegen die Allowlist des Contact-Form-Ingress. Bauen Sie keinen lokalen Allowlist-Ersatz in die Storefront.

Contact-Form-UX

Behandeln Sie 202 Accepted als angenommene Übermittlung. Zeigen Sie danach eine neutrale Bestätigung wie „Vielen Dank, wir haben Ihre Nachricht erhalten.“ an.

Halten Sie die öffentliche Seite bewusst einfach:

  • Führen Sie ein Honeypot-Feld mit und lassen Sie es für Menschen unsichtbar.
  • Messen Sie filledSeconds ab dem ersten Rendern des Formulars.
  • Senden Sie pageUrl, damit Betreiber den Ursprung der Anfrage erkennen.
  • Validieren Sie Pflichtfelder für die Nutzerführung, aber treffen Sie keine Spam- oder Routing-Entscheidung im Client.
  • Erzeugen Sie keine lokalen Leads, Kommentare, E-Mails oder Fallback-Tickets.
  • Zeigen Sie keine Submission-IDs, Risikogründe oder internen Validierungsdetails an.

Wenn eine Übermittlung angenommen wurde, aber intern kein Lead sichtbar ist, übergeben Sie an die Administration nur public-safe Diagnosewerte: Formularlabel, Page URL, Origin, Zeitpunkt, HTTP-Status und eine künstliche Beispielpayload ohne echte personenbezogene Daten.

Gemeinsame Submission-Signale wiederverwenden

Nutzen Sie dieselben Schutzsignale auch bei Firmenzugangs- und Angebotsformularen in der Storefront. Senden Sie honeypot leer, messen Sie filledSeconds ab dem ersten Rendern des Formulars und senden Sie pageUrl, wenn die Seite fachlich zum Request gehört.

Behandeln Sie öffentliche Ablehnungen neutral:

  • 429 Too Many Requests bedeutet, dass ein Rate-Limit gegriffen hat.
  • 413 Payload Too Large bedeutet, dass die Payload zu groß ist.
  • Generische Annahmeantworten bei verdächtigen Firmenzugangs-Anfragen bedeuten nicht automatisch, dass intern ein Lead entstanden ist.

Zeigen Sie keine Risikogründe, Bucket-Namen, interne IDs oder Rohfehlermeldungen an. Treffen Sie Spam-, Lead- oder Angebotsentscheidungen nicht im Client.

Website Chat einbinden

Bevor Sie das Widget einbinden, muss die Administration unter System > Chat-Widget-Eingänge einen aktiven Chat-Widget-Eingang anlegen. Dort entstehen der öffentliche widgetKey, die erlaubten Origins, das Routing zur verantwortlichen Gruppe und die Verfügbarkeitssteuerung.

Binden Sie das offizielle Widget-Script ein und platzieren Sie das Custom Element auf der Seite:

html
<script src="/api/v1/public/v1/widgets/embed/chat-widget.js"></script>
<nucleus-chat-widget data-widget-key="PUBLIC_WIDGET_KEY"></nucleus-chat-widget>

data-widget-key enthält einen öffentlichen Widget-Key. Verwenden Sie keine internen Widget-, Tenant-, Queue- oder Konversations-IDs. Kopieren Sie den Widget-Code nicht in die Storefront und bauen Sie kein eigenes Chat-Protokoll nach.

Wenn Ihnen der Widget-Key fehlt, fordern Sie ihn bei der Administration an. Erzeugen Sie ihn nicht über Backend-, Admin- oder interne Conversation-APIs aus der Storefront heraus.

Das Widget nutzt öffentliche Widget- und Conversation-Endpunkte für Status, Bootstrap, Nachrichten, Präsenz, Stream und Leave. Behandeln Sie öffentliche Conversation Tokens wie Zugangsdaten: Schreiben Sie sie nicht in Logs, Analytics, Support-Nachrichten oder eigene URLs außerhalb der dokumentierten öffentlichen Conversation-Pfade.

Chat-Zustände behandeln

Lassen Sie das Widget den Chat führen. Die Storefront stellt nur den Einbettungspunkt, Branding und den Seitenkontext bereit.

Beachten Sie diese Regeln:

  • Wenn Script, Status, Bootstrap oder Resume fehlschlagen, zeigen Sie einen nicht verfügbaren Chat-Zustand oder lassen Sie das Widget diesen Zustand anzeigen.
  • Wenn die Origin nicht erlaubt oder das Widget inaktiv ist, bauen Sie keinen Fallback auf interne Conversations-APIs.
  • Speichern Sie kein lokales Chat-Protokoll als Ersatz für Workspace.
  • Treffen Sie keine lokalen Routing- oder Queue-Entscheidungen.
  • Passen Sie Farben und Radien über dokumentierte --nucleus-chat-widget-* CSS Custom Properties am Host-Element an.
  • Nutzen Sie Widget-Slots oder dokumentierte Icon-Variablen für eigene Icons, statt das Script zu verändern.

Vor dem Go-live prüfen Sie Script-Auslieferung, Widget-Status, Bootstrap, erste Nachricht, Resume/Read, Antwort, Stream-Verhalten sowie inaktive und origin-verweigerte Zustände.

Vollständiger Storefront-Slice

Ergänzen Sie Contact Forms und Website Chat erst, nachdem die Kernstrecke stabil ist: Context, Katalog und Pricing, Cart, Shipping, Checkout, Payment, Login, Gastkauf, Firmenzugang und Angebotsanfrage. Die fachlichen Commerce-Voraussetzungen stehen im Onlineshop-Einstieg.