Vai al contenuto

Widget B2C — gość i firma

Ta sekcja opisuje integracje, w których widget zostaje w sesji gościa:

  • strona publiczna, nieznany odwiedzający: tylko skrypt i formularz kontaktu
  • strona albo portal zna już konto: init() z profilem i danymi firmy, formularz pominięty, gdy danych wystarcza, kontakt powiązany z firmą

Osobista historia w innej przeglądarce albo na innym urządzeniu to inna integracja. Zobacz Widget B2B. Pełny kontrakt pól, zmiana konta w SPA, CSP i provisioning: Integracja techniczna.

Powiązanie firmy nie daje historii innej osoby. Użytkownik zalogowany na stronie pozostaje gościem widgetu, dopóki nie wyślesz external_user_id razem z ważnym restore_id.

Co dostajesz

  • Pływający przycisk albo czat osadzony w kontenerze strony
  • Formularz początkowy dla nieznanego, z etykietami Telefon i Imię. W init() pola to phone i name
  • Sesję gościa zapisaną przez loader w tej samej przeglądarce, osobno dla klucza widgetu. Gdy localStorage jest zablokowany, ciągłość może zostać na bieżącej stronie
  • Gdy wysyłasz external_id, Quoting24 szuka firmy z tym samym web_code. Z company_name może utworzyć brakującą firmę i powiązać kontakt
  • Zgłoszenia i odpowiedzi w Quoting24, jak na pozostałych kanałach

Sesja gościa czyta swoją najnowszą rozmowę także po zamknięciu karty. Nie podąża za osobą do innej przeglądarki.

1. Wymagania w Quoting24

  1. Kanał Widget aktywny w Ustawienia → Kanały
  2. Logo, kolor, pozycja, powitanie, wiadomość powitalna i komunikat poza godzinami skonfigurowane
  3. Dozwolone domeny aktualne, łącznie z testami i localhost
  4. Kod osadzenia skopiowany z konfiguracji kanału: URL skryptu i klucz publiczny

Użyj hosta i klucza tego samego środowiska. W przykładach zastąp HOST_WIDGET i KLUCZ_PUBLICZNY_WIDGET.

Domeny to nazwy hostów, bez https://, portu, ścieżki i *.. example.com obejmuje subdomeny. Pusta lista: brak ograniczenia. Lokalnie serwuj stronę przez HTTP, nie jako file://.

company_name w init() to nazwa firmy klienta. To nie tytuł widgetu i nie konfiguruje się go z tego payloadu.

2. Instalacja pływającego przycisku

Wklej skrypt raz, przed </body>:

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

Przycisk pojawia się po załadowaniu ustawień graficznych. Nowy odwiedzający widzi formularz kontaktu. Kto wraca w tej samej przeglądarce, wznawia sesję gościa, jeśli pamięć jest dostępna.

Skrypt udostępnia jedno window.Quoting24Widget.

3. Osadzenie czatu na stronie

Utwórz kontener przed skryptem i nadaj mu jawną wysokość:

<section aria-labelledby="tytul-wsparcia">
  <h2 id="tytul-wsparcia">Wsparcie</h2>
  <div id="chat-wsparcia" style="width: 100%; height: 600px;"></div>
</section>

<script
  src="https://HOST_WIDGET/assets/widget/script.js?key=KLUCZ_PUBLICZNY_WIDGET&amp;mode=embedded&amp;target=chat-wsparcia"
  async
></script>
  • target to ID elementu, bez #
  • Iframe wypełnia kontener
  • Nie ma pływającego przycisku
  • open(), close() i toggle() nie działają
  • W tym trybie strona decyduje o wysokości i szerokości. W trybie pływającym na telefonie czat może zająć viewport

Sam tryb osadzony nie włącza przywracania historii.

4. Wysłanie profilu klienta

Gdy strona zna konto, wysyła profil po załadowaniu loadera. Pola są łańcuchami. Pomiń nieznane: nie wysyłaj null, liczbowych ID ani pustego e-maila.

window.Quoting24Widget.init({
  external_id: "52",
  company_name: "Ricambi Stella S.r.l.",
  name: "mario.rossi",
  phone: "+393331234567",
  email: "amministrazione@ricambi-stella.example",
});
Dana na stronie albo w ERP Pole Znaczenie
Stabilne odniesienie firmy, ta sama wartość zaimportowana do web_code external_id Dokładne porównanie z companies.web_code, w organizacji widgetu
Nazwa firmy company_name Używana, gdy firmę trzeba utworzyć
Imię osoby albo użytkownika name Imię pokazywane przy kontakcie
E-mail konta email Zapisywany przy firmie tylko w chwili jej utworzenia
Telefon, jeśli go znasz phone Numer kontaktu. Wolisz format międzynarodowy, na przykład +393331234567

Ten payload nie wysyła external_user_id ani restore_id. Trzymaj name i company_name osobno: nie doklejaj nazwy firmy do nazwy użytkownika, żeby uzyskać powiązanie. Publiczne pole to external_id. Nie wysyłaj web_code, wewnętrznego UUID Quoting24 ani companies.code.

Formularz pokazuje Imię i Telefon. W init() te pola nazywają się name i phone. E-mail nazywa się email. Imię, Telefon i Email nie są kluczami: loader je odrzuca, tak jak odrzuca web_code zamiast external_id.

Przykłady

Imię i telefon, te same dane co w formularzu. Czat startuje i nie szuka firmy.

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

Profil z firmą. name to osoba, phone numer kontaktu, a email trafia do firmy tylko wtedy, gdy to wywołanie ją tworzy.

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

Sam e-mail. Poprawny adres w email wystarcza, żeby otworzyć sesję.

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

Gdy pole przekracza limity albo e-mail jest źle zbudowany, żądanie jest odrzucane. Limity i zachowanie każdego pola: Integracja techniczna.

Czekanie na loader

Skrypt async może jeszcze nie być wykonany, gdy późniejszy kod woła init(). Przy danych wstępnych użyj modułu ładowania zamiast statycznego znacznika, importowanego raz w głównym układzie:

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

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("API widgetu jest niedostępne"));
      }
    };
    script.onerror = () => {
      script.remove();
      reject(new Error("Nie udało się załadować widgetu"));
    };
    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",
});

Zaimportuj moduł z bundlera albo załaduj plik wejściowy przez <script type="module" src="/assets/wsparcie.js"></script>. W trybie osadzonym dodaj &mode=embedded&target=chat-wsparcia do URL i najpierw zamontuj kontener.

loadWidget() zgłasza tylko, że API JavaScript jest dostępne. init() zwraca void: kolejkuje profil, gdy iframe nie jest gotowy, i nie czeka na sesję. Wynik sprawdzaj przez isReady() i hasSessionError().

init() zastępuje zapisany profil. Nie scala go z poprzednim. Przekaż wszystkie pola, które mają zostać.

Zmiana strony w SPA nie wymaga nowego skryptu ani reset(). Przy zmianie osoby albo konta i przy wylogowaniu wywołaj reset() przed nowym profilem: sama zmiana pól nie odłącza poprzedniej sesji gościa. Pełny wzorzec: Logowanie, wylogowanie i zmiana konta.

5. Jak firma jest powiązywana albo tworzona

Quoting24 wykonuje ten przebieg przy inicjalizacji, nawet gdy odwiedzający nie wysłał jeszcze wiadomości:

  1. Przy niepustym external_id szuka firmy tej samej organizacji, której web_code jest równy tej wartości
  2. Gdy ją znajdzie, wiąże kontakt. Nazwa i e-mail istniejącej firmy zostają
  3. Gdy jej nie znajdzie i jest też niepuste company_name, tworzy firmę z name = company_name, web_code = external_id i e-mailem, jeśli jest, a potem wiąże kontakt
  4. Gdy nie może znaleźć ani utworzyć firmy, idzie dalej z dostępnym profilem. Gdy to nie wystarcza nowemu gościowi, pokazuje formularz. Błędy bazy albo limit żądań kończą inicjalizację niepowodzeniem
Wysłane dane Sytuacja w Quoting24 Wynik
external_id: "52", company_name: "Ricambi Stella S.r.l." Istnieje web_code = "52" Używa istniejącej firmy i nie zmienia jej nazwy
Te same dane plus ważny e-mail Nie istnieje web_code = "52" Tworzy firmę z kodem web 52, nazwą i e-mailem oraz wiąże kontakt
external_id: "52", name: "mario.rossi" Brak dopasowania Uruchamia gościa bez nowego powiązania firmy
external_id: "52", bez innych danych Jest dopasowanie Uruchamia gościa powiązanego z firmą, z domyślnym imieniem Visitatore
external_id: "52", bez innych danych Brak dopasowania Pokazuje formularz kontaktu
company_name bez external_id, plus name Dowolna Uruchamia odwiedzającego. Nie szuka i nie tworzy firmy

Wyszukiwanie nie używa nazwy firmy, e-maila, telefonu, NIP ani companies.code. "052" i "52" to różne wartości; spacje w external_id nie są usuwane. Jeśli najpierw importujesz kartotekę, wpisz w web_code tę samą wartość, którą strona wyśle w external_id. Zobacz też Firmy → Kod web.

Nowy gość startuje, gdy jest przynajmniej imię, telefon, ważny e-mail albo external_user_id, albo firma znaleziona albo utworzona przez external_id. init({}) i samo company_name nie zaczynają sesji.

Dla już powiązanego kontaktu nowy ważny kod może zmienić firmę. Pominięcie kodu albo wysłanie nierozwiązanego nie kasuje poprzedniego powiązania. Zmiana osoby albo konta wymaga reset().

Limity

web_code nie jest unikalny. Przy kilku dopasowaniach publiczna inicjalizacja bierze pierwsze według rosnącej daty utworzenia. Równoczesne żądania, które jeszcze nie znajdują firmy, mogą utworzyć więcej niż jedną: tworzenie nie jest atomowe i nie zastępuje importu ani synchronizacji z ERP.

Tworzenie niejawne jest ograniczone do 20 prób na okno 60 sekund i adres IP, w procesie backendu obsługującym żądanie. Powyżej limitu inicjalizacja kończy się TOO_MANY_REQUESTS: ponów z oczekiwaniem, bez ciągłych pętli init().

Dane wychodzą z przeglądarki i odwiedzający może je zmienić. Powiązanie nie dowodzi przynależności do firmy i nie daje historii firmy. Wysyłaj company_name tylko wtedy, gdy chcesz dopuścić to publiczne tworzenie. Istniejące firmy aktualizuj narzędziami Quoting24 albo autoryzowaną integracją ERP.

E-mail publicznej inicjalizacji trafia tylko do nowej firmy. Nie jest zapisywany przy kontakcie i nie aktualizuje firmy już istniejącej. Telefon używany już przez inny kontakt nie scala kontaktów ani czatów.

6. Zachowanie na stronie

Sytuacja Oczekiwane zachowanie
Pierwszy odwiedzający, tylko skrypt Przycisk, potem formularz, potem czat
init() z wystarczającym profilem Formularz pominięty
external_id już obecne jako web_code Kontakt powiązany; nazwa i e-mail firmy bez zmian
Nowe external_id z company_name Firma utworzona i kontakt powiązany
Nowy kod i imię, bez company_name Czat bez nowej firmy
Tylko nowy kod Formularz kontaktu
Tylko nazwa firmy i imię Brak wyszukiwania i tworzenia po nazwie
Przeładowanie w tej samej przeglądarce Sesja gościa wznowiona, jeśli pamięć jest dostępna
Inna przeglądarka albo urządzenie Nowa sesja gościa
Poza godzinami Baner poza godzinami; pisanie zostaje użyteczne
Telefon, pływający przycisk Czat może zająć viewport

Załączniki: PDF, DOC, DOCX, JPG/JPEG, PNG. Najwyżej 10 MiB na plik i 100 MiB załączników wskazanych w rozmowie.

7. Przydatne sterowanie

Gdy pływający przycisk jest widoczny, możesz podłączyć przycisk strony do window.Quoting24Widget?.open().

Metoda Użycie
init(profile) Ustawia albo zastępuje bieżący profil
open() / close() / toggle() Tylko widget pływający. Zamknięcie nie jest wylogowaniem
isReady() Sesja odwiedzającego uruchomiona. Na formularzu kontaktu zostaje fałszem
hasSessionError() Błąd sesji zgłoszony przez iframe
reset() Czyści profil, sesję lokalną, zapisane poświadczenie gościa i nieprzeczytane tej instancji
dispose() Demontuje interfejs i nasłuchiwanie. Nie czyści zapisanego poświadczenia gościa ani globalnego obiektu API

Nie czekaj na isReady(), żeby nowy gość otworzył formularz. Nie ma publicznego zdarzenia gotowości. Te wskaźniki nie opisują całego stanu sieci.

Lista kontrolna przed wdrożeniem

  • [ ] Host i klucz tego samego środowiska
  • [ ] Domeny strony i stagingu na liście, tylko jako nazwy hostów
  • [ ] Logo, kolor, powitanie, wiadomość powitalna i komunikat poza godzinami sprawdzone
  • [ ] Nowa przeglądarka, tylko skrypt: formularz, wiadomość, zgłoszenie w Quoting24
  • [ ] external_id już w web_code: powiązanie, kartoteka firmy bez zmian
  • [ ] Nowy kod z company_name: firma utworzona z tym kodem web
  • [ ] Nowy kod bez company_name: żadna firma nie utworzona
  • [ ] Pusty e-mail, liczbowe ID albo za długa nazwa firmy: payload odrzucony, do poprawy
  • [ ] Przeładowanie i nawigacja SPA: jedna instancja, sesja gościa zachowana
  • [ ] Zmiana konta: natychmiast reset(), spóźnione odpowiedzi odrzucone
  • [ ] Telefon: pisanie użyteczne
  • [ ] Niedozwolona domena: widget odrzucony

Częste problemy: Rozwiązywanie problemów.