Vai al contenuto

Widget B2C — Gastbesucher und Unternehmen

Dieser Abschnitt behandelt Integrationen, in denen das Widget in einer Gastsitzung bleibt:

  • öffentliche Website, unbekannter Besucher: nur Skript und Kontaktformular
  • Website oder Portal kennt das Konto schon: init() mit Profil und Unternehmensdaten, Formular wird übersprungen, wenn die Daten reichen, Kontakt wird dem Unternehmen zugeordnet

Der persönliche Verlauf auf einem anderen Browser oder Gerät ist eine andere Integration. Siehe Widget B2B. Vollständiger Feldvertrag, Kontowechsel in einer SPA, CSP und Provisioning: Technische Integration.

Ein Unternehmen zuzuordnen gibt nicht den Verlauf einer anderen Person frei. Ein auf der Website angemeldeter Benutzer bleibt ein Widget-Gast, bis Sie external_user_id zusammen mit einer gültigen restore_id senden.

Was Sie erhalten

  • Eine schwebende Schaltfläche oder einen Chat in einem Seitencontainer
  • Ein Anfangsformular für Unbekannte, mit den Beschriftungen Telefon und Name. In init() heißen die Felder phone und name
  • Eine Gastsitzung, die der Loader im selben Browser speichert, getrennt nach Widget-Schlüssel. Ist localStorage blockiert, kann die Kontinuität auf der aktuellen Seite bleiben
  • Wenn Sie external_id senden, sucht Quoting24 ein Unternehmen mit demselben web_code. Mit company_name zusätzlich kann es das fehlende Unternehmen anlegen und den Kontakt zuordnen
  • Tickets und Antworten in Quoting24, wie auf den anderen Kanälen

Die Gastsitzung liest ihre letzte Unterhaltung auch nach dem Schließen des Tabs. Sie folgt der Person nicht auf einen anderen Browser.

1. Voraussetzungen in Quoting24

  1. Kanal Widget aktiv unter Einstellungen → Kanäle
  2. Logo, Farbe, Position, Begrüßung, Willkommenstext und Text außerhalb der Zeiten konfiguriert
  3. Erlaubte Domains aktuell, einschließlich Test und localhost
  4. Einbettungscode aus der Kanalkonfiguration kopiert: Skript-URL und öffentlicher Schlüssel

Host und Schlüssel derselben Umgebung verwenden. In den Beispielen WIDGET_HOST und WIDGET_SCHLUESSEL ersetzen.

Domains sind Hostnamen, ohne https://, Port, Pfad oder *.. example.com schließt Subdomains ein. Leere Liste: keine Beschränkung. Lokal die Seite über HTTP ausliefern, nicht als file://.

company_name in init() ist der Firmenname des Kunden. Es ist nicht der Widget-Titel und wird nicht über dieses Payload konfiguriert.

2. Schwebende Schaltfläche einbinden

Das Skript einmal einfügen, vor </body>:

<script
  src="https://WIDGET_HOST/assets/widget/script.js?key=WIDGET_SCHLUESSEL"
  async
></script>

Die Schaltfläche erscheint nach dem Laden der grafischen Einstellungen. Ein neuer Besucher sieht das Kontaktformular. Wer im selben Browser zurückkehrt, setzt die Gastsitzung fort, wenn Speicher verfügbar ist.

Das Skript stellt ein einziges window.Quoting24Widget bereit.

3. Chat in die Seite einbetten

Den Container vor dem Skript anlegen und ihm eine explizite Höhe geben:

<section aria-labelledby="titel-support">
  <h2 id="titel-support">Support</h2>
  <div id="chat-support" style="width: 100%; height: 600px;"></div>
</section>

<script
  src="https://WIDGET_HOST/assets/widget/script.js?key=WIDGET_SCHLUESSEL&amp;mode=embedded&amp;target=chat-support"
  async
></script>
  • target ist die Element-ID, ohne #
  • Das iframe füllt den Container
  • Es gibt keine schwebende Schaltfläche
  • open(), close() und toggle() haben keine Wirkung
  • In diesem Modus bestimmt die Website Höhe und Breite. Im schwebenden Modus kann der Chat auf dem Mobilgerät den Viewport füllen

Der eingebettete Modus allein schaltet die Verlaufswiederherstellung nicht frei.

4. Kundenprofil senden

Kennt die Website das Konto, sendet sie das Profil nach dem Laden des Loaders. Die Felder sind Zeichenketten. Unbekannte weglassen: kein null, keine numerischen IDs, keine leere E-Mail.

window.Quoting24Widget.init({
  external_id: "52",
  company_name: "Ricambi Stella S.r.l.",
  name: "mario.rossi",
  phone: "+393331234567",
  email: "amministrazione@ricambi-stella.example",
});
Angabe auf der Website oder im ERP Feld Bedeutung
Stabile Unternehmensreferenz, derselbe Wert wie in web_code importiert external_id Exakter Vergleich mit companies.web_code, in der Organisation des Widgets
Firmenname company_name Wird verwendet, wenn das Unternehmen angelegt werden muss
Name der Person oder des Benutzers name Name, der am Kontakt angezeigt wird
E-Mail des Kontos email Wird nur beim Anlegen des Unternehmens am Unternehmen gespeichert
Telefon, falls bekannt phone Nummer des Kontakts. Internationales Format bevorzugen, zum Beispiel +393331234567

Dieses Payload sendet weder external_user_id noch restore_id. name und company_name getrennt halten: den Firmennamen nicht an den Benutzernamen hängen, um die Zuordnung zu erhalten. Das öffentliche Feld heißt external_id. Nicht web_code, die interne UUID von Quoting24 oder companies.code senden.

Das Formular zeigt Name und Telefon. In init() heißen die Felder name und phone. Die E-Mail heißt email. Name, Telefon und Email sind keine Schlüssel: der Loader verwirft sie, so wie er web_code anstelle von external_id verwirft.

Beispiele

Name und Telefon, dieselben Daten wie im Formular. Der Chat startet und sucht kein Unternehmen.

widget.init({
  name: "Mario Rossi",
  phone: "+393331234567",
});

Profil mit Unternehmen. name ist die Person, phone die Nummer des Kontakts, email wird am Unternehmen nur geschrieben, wenn dieser Aufruf es anlegt.

widget.init({
  external_id: "52",
  company_name: "Ricambi Stella S.r.l.",
  name: "Mario Rossi",
  phone: "+393331234567",
  email: "mario.rossi@ricambi-stella.example",
});

Nur E-Mail. Eine gültige Adresse in email reicht, um die Sitzung zu öffnen.

widget.init({
  email: "mario.rossi@ricambi-stella.example",
});

Überschreitet ein Feld die Grenzen oder ist die E-Mail ungültig, wird die Anfrage abgelehnt. Grenzen und Verhalten jedes Feldes: Technische Integration.

Auf den Loader warten

Ein async-Skript ist vielleicht noch nicht ausgeführt, wenn späterer Code init() aufruft. Für vorausgefüllte Daten ein Lademodul anstelle des statischen Tags verwenden, einmal im Hauptlayout importiert:

// /assets/quoting24-loader.js
const widgetScriptUrl =
  "https://WIDGET_HOST/assets/widget/script.js?key=WIDGET_SCHLUESSEL";

let widgetPromise;

export function loadWidget() {
  if (window.Quoting24Widget) {
    return Promise.resolve(window.Quoting24Widget);
  }
  if (widgetPromise) return widgetPromise;

  widgetPromise = new Promise((resolve, reject) => {
    const script = document.createElement("script");
    script.id = "quoting24-widget-script";
    script.src = widgetScriptUrl;
    script.async = true;
    script.onload = () => {
      if (window.Quoting24Widget) resolve(window.Quoting24Widget);
      else {
        script.remove();
        reject(new Error("Widget-API ist nicht verfügbar"));
      }
    };
    script.onerror = () => {
      script.remove();
      reject(new Error("Widget-Skript konnte nicht geladen werden"));
    };
    document.body.appendChild(script);
  }).catch((error) => {
    widgetPromise = undefined;
    throw error;
  });

  return widgetPromise;
}

import { loadWidget } from "/assets/quoting24-loader.js";

const widget = await loadWidget();
widget.init({
  external_id: "52",
  company_name: "Ricambi Stella S.r.l.",
  name: "mario.rossi",
  phone: "+393331234567",
  email: "amministrazione@ricambi-stella.example",
});

Das Modul über den Bundler importieren oder die Einstiegsdatei mit <script type="module" src="/assets/support.js"></script> laden. Für den eingebetteten Modus &mode=embedded&target=chat-support an die URL hängen und den Container zuerst einbinden.

loadWidget() meldet nur, dass die JavaScript-API verfügbar ist. init() gibt void zurück: es reiht das Profil ein, wenn das iframe noch nicht bereit ist, und wartet nicht auf die Sitzung. Für das Ergebnis isReady() und hasSessionError() verwenden.

init() ersetzt das gespeicherte Profil. Es führt es nicht mit dem vorherigen zusammen. Alle Felder übergeben, die bleiben sollen.

Ein Seitenwechsel in einer SPA braucht weder ein neues Skript noch ein reset(). Bei Personen- oder Kontowechsel und beim Abmelden reset() vor dem neuen Profil aufrufen: nur die Felder zu ändern löst die vorherige Gastsitzung nicht. Vollständiges Muster: Anmeldung, Abmeldung und Kontowechsel.

5. Wie das Unternehmen zugeordnet oder angelegt wird

Quoting24 führt diesen Ablauf bei der Initialisierung aus, auch wenn der Besucher noch keine Nachricht gesendet hat:

  1. Bei einer nicht leeren external_id sucht es ein Unternehmen derselben Organisation, dessen web_code diesem Wert entspricht
  2. Findet es eines, verknüpft es den Kontakt. Name und E-Mail des vorhandenen Unternehmens bleiben unverändert
  3. Findet es keines und ist auch ein nicht leeres company_name vorhanden, legt es das Unternehmen mit name = company_name, web_code = external_id und gegebenenfalls email an und verknüpft dann den Kontakt
  4. Kann es das Unternehmen nicht finden oder anlegen, fährt es mit dem verfügbaren Profil fort. Reicht das für einen neuen Gast nicht, zeigt es das Formular. Datenbankfehler oder das Anfragelimit lassen die Initialisierung fehlschlagen
Gesendete Daten Lage in Quoting24 Ergebnis
external_id: "52", company_name: "Ricambi Stella S.r.l." web_code = "52" existiert Verwendet das vorhandene Unternehmen und ändert seinen Namen nicht
Dieselben Daten plus eine gültige E-Mail web_code = "52" existiert nicht Legt das Unternehmen mit Web-Code 52, Firmenname und E-Mail an und ordnet den Kontakt zu
external_id: "52", name: "mario.rossi" Keine Übereinstimmung Startet den Gast ohne neue Unternehmenszuordnung
external_id: "52", ohne weitere Daten Eine Übereinstimmung existiert Startet den zugeordneten Gast mit dem Standardnamen Visitatore
external_id: "52", ohne weitere Daten Keine Übereinstimmung Zeigt das Kontaktformular
company_name ohne external_id, plus name Beliebig Startet den Besucher. Sucht und legt kein Unternehmen an

Die Suche verwendet weder Firmenname, E-Mail, Telefon, Umsatzsteuer-ID noch companies.code. "052" und "52" sind verschiedene Werte; Leerzeichen in external_id werden nicht entfernt. Wird der Bestand vorher importiert, in web_code denselben Wert schreiben, den die Website in external_id senden wird. Siehe auch Unternehmen → Web-Code.

Ein neuer Gast startet, wenn mindestens ein Name, ein Telefon, eine gültige E-Mail oder eine external_user_id vorhanden ist, oder ein über external_id gefundenes oder angelegtes Unternehmen. init({}) und company_name allein starten keine Sitzung.

Bei einem bereits verknüpften Kontakt kann ein neuer gültiger Code das Unternehmen wechseln. Den Code wegzulassen oder einen nicht aufgelösten zu senden löscht die vorherige Zuordnung nicht. Personen- oder Kontowechsel braucht reset().

Grenzen

web_code ist nicht eindeutig. Bei mehreren Treffern nimmt die öffentliche Initialisierung den ersten nach aufsteigendem Erstellungsdatum. Gleichzeitige Anfragen, die das Unternehmen noch nicht finden, können mehrere anlegen: die Anlage ist nicht atomar und ersetzt keinen Import und keine Synchronisation aus dem ERP.

Die implizite Anlage ist auf 20 Versuche pro 60-Sekunden-Fenster und IP-Adresse begrenzt, im Backend-Prozess, der die Anfrage bearbeitet. Darüber schlägt die Initialisierung mit TOO_MANY_REQUESTS fehl: mit Wartezeit wiederholen, ohne fortlaufende init()-Schleifen.

Die Daten kommen aus dem Browser und der Besucher kann sie verändern. Die Zuordnung beweist keine Zugehörigkeit zum Unternehmen und gibt keinen Unternehmensverlauf frei. company_name nur senden, wenn diese öffentliche Anlage erlaubt sein soll. Vorhandene Unternehmen über die Werkzeuge von Quoting24 oder eine autorisierte ERP-Integration aktualisieren.

Die E-Mail der öffentlichen Initialisierung landet nur auf dem neuen Unternehmen. Sie wird nicht am Kontakt geschrieben und aktualisiert kein vorhandenes Unternehmen. Eine Telefonnummer, die ein anderer Kontakt schon verwendet, führt Kontakte oder Chats nicht zusammen.

6. Verhalten auf der Website

Situation Erwartetes Verhalten
Erster Besucher, nur Skript Schaltfläche, dann Formular, dann Chat
init() mit ausreichendem Profil Formular übersprungen
external_id schon als web_code vorhanden Kontakt zugeordnet; Name und E-Mail des Unternehmens unverändert
Neue external_id mit company_name Unternehmen angelegt und Kontakt zugeordnet
Neuer Code und Name, ohne company_name Chat ohne neues Unternehmen
Nur neuer Code Kontaktformular
Nur Firmenname und Name Keine Suche und keine Anlage nach Name
Neuladen im selben Browser Gastsitzung fortgesetzt, wenn Speicher verfügbar ist
Anderer Browser oder anderes Gerät Neue Gastsitzung
Außerhalb der Zeiten Banner außerhalb der Zeiten; das Verfassen bleibt nutzbar
Mobil, schwebende Schaltfläche Der Chat kann den Viewport füllen

Anhänge: PDF, DOC, DOCX, JPG/JPEG, PNG. Höchstens 10 MiB pro Datei und 100 MiB referenzierte Anhänge pro Unterhaltung.

7. Nützliche Steuerungen

Ist die schwebende Schaltfläche sichtbar, kann eine Schaltfläche der Website mit window.Quoting24Widget?.open() verbunden werden.

Methode Verwendung
init(profile) Setzt oder ersetzt das aktuelle Profil
open() / close() / toggle() Nur schwebendes Widget. Schließen ist kein Abmelden
isReady() Besuchersitzung gestartet. Bleibt auf dem Kontaktformular falsch
hasSessionError() Vom iframe gemeldeter Sitzungsfehler
reset() Löscht Profil, lokale Sitzung, gespeicherten Gastnachweis und Ungelesene dieser Instanz
dispose() Hängt Oberfläche und Listener ab. Löscht weder den gespeicherten Gastnachweis noch das globale API-Objekt

Nicht auf isReady() warten, damit ein neuer Gast das Formular öffnen kann. Es gibt kein öffentliches Verfügbarkeitsereignis. Diese Anzeigen beschreiben nicht den gesamten Netzstatus.

Checkliste vor der Freigabe

  • [ ] Host und Schlüssel derselben Umgebung
  • [ ] Domains der Website und des Stagings in der Liste, nur als Hostnamen
  • [ ] Logo, Farbe, Begrüßung, Willkommenstext und Text außerhalb der Zeiten geprüft
  • [ ] Neuer Browser, nur Skript: Formular, Nachricht, Ticket in Quoting24
  • [ ] external_id schon in web_code: Zuordnung, Unternehmensstamm unverändert
  • [ ] Neuer Code mit company_name: Unternehmen mit diesem Web-Code angelegt
  • [ ] Neuer Code ohne company_name: kein Unternehmen angelegt
  • [ ] Leere E-Mail, numerische ID oder zu langer Firmenname: Payload abgelehnt, zu korrigieren
  • [ ] Neuladen und SPA-Navigation: eine Instanz, Gastsitzung bleibt erhalten
  • [ ] Kontowechsel: sofort reset(), verspätete Antworten verwerfen
  • [ ] Mobilgerät: Verfassen nutzbar
  • [ ] Nicht erlaubte Domain: Widget abgelehnt

Häufige Probleme: Problemlösung.