:::note Stav verzí
Funkce popsané jako dostupné v aktuálním zdrojovém kódu byly ověřeny v lokálním hostovaném loaderu v16; neznamená to, že jsou dostupné v loaderu používaném ve vašem prostředí. Než se na ně spolehnete, ověřte jeho verzi. Vydané npm SDK 0.1.4 poskytuje remove(); pro konečný teardown odeberte všechny mount handly vytvořené se stejnou konfigurací. Teardown funguje jen tehdy, pokud loader podporuje signál odebrání odesílaný SDK.
:::
Přizpůsobení hostovaného widgetu
Přizpůsobte hotové rozhraní načítané z https://chattybox.ai/widget.js. Kanonické příklady instalace pro frameworky a platformy najdete v Průvodcích instalací.
Než začnete s přizpůsobováním
Vytvořte projekt, indexujte jeho obsah a ověřte reprezentativní odpovědi v části Otestovat chatbota, teprve potom věnujte čas vzhledu. Kompletní postup najdete v části Začínáme.
Nakonfigurujte hostovaný widget
- Otevřete řídicí panel a vyberte projekt.
- Přejděte do Přizpůsobení → Vzhled, kde upravíte vzhled, branding a nastavení Jazyk.
- Zkontrolujte stav automatického ukládání. Před otestováním widgetu na webu opravte validační chyby nebo neúspěšné uložení zkuste znovu.
Instalační kód a veřejné klíče najdete v části Instalace. Před instalací:
- Otevřete Instalace → Klíče a domény, kde zkontrolujete nastavení originů nebo vytvoříte veřejný klíč pro prohlížeč. Klíč je určen pro klientský kód a není tajný.
- V části Instalace → Instalace na web vyberte vhodný klíč a zkopírujte vygenerovaný úryvek. Klíč vytvořený bez omezení přijímá požadavky z různých originů; klíč připravený pro konkrétní web už může být omezen na jeho origin. Před použitím na stagingu nebo localhostu zkontrolujte nastavení vybraného klíče.
- Volitelně povolte omezení na přesné originy jako další vrstvu ochrany. Omezení originů návštěvníky neověřuje.
- Postupujte podle Průvodců instalací pro svou platformu.
<script
src="https://chattybox.ai/widget.js"
data-api-key="YOUR_API_KEY"
data-api-url="https://adorable-woodpecker-629.convex.site/chat"
async
></script>
Uložené změny se načtou při další inicializaci; otevřenou stránku je nutné obnovit.
Vizuální přizpůsobení
Editor v řídicím panelu umožňuje měnit podporované barvy, umístění, ikonu a text widgetu bez úprav kódu webu. Výsledek ověřte v hostovaném widgetu, protože náhled a loader nejsou totožné.
Ovládací prvky v řídicím panelu
-
Akcentní barva - Vyberte hlavní barvu značky. Ovlivňuje spouštěč, hlavní zvýraznění a zprávy uživatele.
-
Pozice widgetu - Zvolte, kde se widget na obrazovce zobrazí.
-
Název hlavičky - Nastavte název zobrazený v horní části okna chatu.
-
Uvítací zpráva - Přizpůsobte první zprávu, kterou návštěvníci uvidí po otevření chatu.
-
Označení ChattyBox - Tarif Starter a vyšší umožňuje vypnout patičku „Powered by ChattyBox“. V tarifu Free je označení povinné.
Editor nabízí také nastavení Pozadí widgetu a Barva textu a výběr výchozí ikony, emoji, URL obrázku nebo nahraného obrázku. Nahraná ikona může mít nejvýše 512 KiB a musí používat podporovaný typ MIME: PNG, JPEG, WebP, SVG, GIF nebo ICO. Volba velikosti ikony se zobrazí pouze při výběru ikony z URL obrázku nebo nahraného obrázku. Hostovaný loader v16 v aktuálním zdrojovém kódu používá iconSize k nastavení velikosti spouštěče a ikony. Než se na tuto funkci spolehnete, ověřte verzi loaderu používanou ve vašem prostředí.
Zkontrolujte stav automatického ukládání vzhledu, opravte případné chyby nebo uložení zkuste znovu a poté obnovte stránku s widgetem. Náhled řídicího panelu je maketa, nikoli samotný hostovaný widget. U projektů uzamčených konfigurací se pole vzhledu a jazyka spravují pomocí config-as-code; projekty s odpovídajícím tarifem mohou nadále ukládat označení značky samostatně.
Výchozí hodnoty konfigurace
Následující hodnoty vrací úspěšný veřejný požadavek na konfiguraci widgetu, pokud není nastavena vlastní hodnota:
| Pole | Výchozí hodnota |
|---|---|
enabled | true, pokud widget není pro projekt vypnutý |
themeColor | #3b82f6 |
chatBgColor | #0f172a |
textColor | #f8fafc |
position | bottom-right; podporovány jsou všechny čtyři rohy |
iconType, iconSize | default, medium; hostovaný loader v16 v aktuálním zdrojovém kódu používá velikost pro spouštěč a ikonu |
iconEmoji, iconUrl | emoji s bublinou, null |
headerTitle | Chat with us (výchozí hodnota API) |
welcomeMessage | Hi! 👋 How can I help you today? (výchozí hodnota API) |
showBranding | true; u tarifu Free se vynucuje hodnota true |
localeMode, defaultLocale, allowLocaleOverride | auto, en, true (výchozí hodnoty) |
V aktuálním zdrojovém kódu zůstane widget při neúspěšném nebo neplatném načtení konfigurace nedostupný — náhradní rozhraní se nevykreslí. To se liší od neúspěšného načtení překladů: pokud se konfigurace načte úspěšně, ale katalog překladů není dostupný, widget se přesto zobrazí s vestavěnými anglickými popisky. Úspěšná konfigurace s enabled: false také zabrání vykreslení; API chatu pak požadavky odmítá s HTTP 403, včetně požadavků SDK. Než se spolehnete na chování aktuálního zdrojového kódu, ověřte verzi loaderu používanou ve vašem prostředí.
Hostovaný loader v16 v aktuálním zdrojovém kódu žádá o konfiguraci s hlavičkou Authorization: Bearer a po HTTP 400 jednou zopakuje požadavek s klíčem v parametru URL. Vydané SDK 0.1.4 používá stejný omezený fallback konfigurace, pokud stránka zpřístupňuje window.ChattyboxSDK. Loader v16 samostatně opakuje způsobilé úvodní GET požadavky na konfiguraci a překlady. Zprávy chatu používají vlastní transport loaderu. Při mountování SDK sdílí vydané SDK 0.1.4 pouze totožné možnosti a odmítne změněný klíč, endpoint, URL skriptu, locale nebo nastavení debug, dokud nebudou odebrány všechny odpovídající handly. Než se spolehnete na chování aktuálního zdrojového kódu, ověřte verzi loaderu používanou ve vašem prostředí.
Pokročilé možnosti
Nastavení v řídicím panelu vs. atributy skriptu
Většinu chování widgetu spravujte z řídicího panelu, abyste kvůli jednoduchým změnám nemuseli web znovu nasazovat.
V části Přizpůsobení → Vzhled spravujte barvy, pozici, ikonu, název hlavičky, uvítací zprávu, jazyk a označení ChattyBox. Část Instalace → Klíče a domény slouží ke správě veřejných klíčů a originů.
Veřejný klíč není tajný a neověřuje návštěvníky. Omezení originů je volitelná dodatečná ochrana, nikoli mechanismus ověřování. Pokud ho povolíte, udržujte seznam přesných originů v souladu s doménami, na kterých widget používáte; zkontrolujte také, zda vybraný klíč už nemá omezení připravené pro konkrétní web.
Atributy skriptu používejte pouze pro hodnoty, které widget potřebuje při načtení stránky:
data-api-keyidentifikuje veřejný klíč widgetu.data-api-urlurčuje, kam má widget odesílat požadavky. V produkci jde o stabilní URLhttps://...convex.site/chatz vašeho řídicího panelu.data-localežádá jazyk UI při inicializaci widgetu, pokud projekt povoluje přepsání skriptem; aktuální zdrojový kód loaderu sleduje také pozdější změny tohoto atributu.data-coloradata-positionpo úspěšném načtení konfigurace přepíší uloženou akcentní barvu a pozici. Upřednostněte hodnoty z řídicího panelu; tyto atributy mohou přebít pozdější změny na panelu.data-debug="true"zapne diagnostiku v konzoli; ve výchozím stavu je vypnutá.
Pokud se widget po instalaci nezobrazuje, přečtěte si Řešení problémů.
U nové zprávy se widget v aktuálním zdrojovém kódu pokouší odeslat origin a cestu aktuální stránky HTTP(S) pro analytiku Oblíbené spouštěče. Nekontroluje, zda je stránka veřejná. Neplatný nebo příliš dlouhý kontext vynechá a při opakování zachová kontext původního požadavku. Odstraní query stringy, fragmenty a přihlašovací údaje, ale cesta může obsahovat citlivé identifikátory. Widget také respektuje prefers-reduced-motion, nabízí označené pole pro zprávu a živá oznámení a citace zpřístupňuje přes klávesnici ovladatelný rozbalovací panel Zdroje.
Kontext stránky vychází z aktuální adresy HTTP(S), nikoli z kontroly, zda je stránka veřejná. Widget nenačítejte na citlivých trasách jen proto, že se odstraňují parametry dotazu. Loader může do /widget-error odesílat také hlášení chyb inicializace, konfigurace, překladů a chatu — pomocí beaconu nebo fetch — s délkou omezenými podrobnostmi chyby, locale, verzí a originem i cestou stránky. Tato hlášení nevyžadují zapnutý režim debug.
Chat vrací kompletní odpovědi JSON, nikoli tokeny ve streamu. Hostovaný loader v16 v aktuálním zdrojovém kódu vytváří pro každou logickou zprávu samostatný klíč idempotence a při transportních opakováních používá tentýž klíč. Server pak může vrátit uloženou odpověď, aniž by požadavek zpracoval znovu. Loader provede nejvýše 10 automatických transportních pokusů při chybách sítě, přerušeném čtení úspěšné odpovědi, HTTP 429, HTTP 5xx a odpovědi 409 s čitelnou hlavičkou Retry-After. Další opakování nenaplánuje, pokud by prodleva překročila 30sekundový rozpočet; nejde o pevný timeout probíhajícího požadavku. CORS v prohlížeči může hlavičku Retry-After skrýt. Headless sendMessage() tato automatická opakování neposkytuje; opakování úvodních GET požadavků loaderu a fallback konfigurace SDK 0.1.4 po HTTP 400 jsou samostatné, omezené mechanismy. Stav konverzace je pouze v paměti dané instance widgetu a po obnovení stránky nebo nové inicializaci se ztratí; zprávy uložené na serveru mohou zůstat. Zdroje se deduplikují a zobrazují se nejvýše tři; náhradní odpověď nemusí mít žádné zdroje. Než se na toto chování spolehnete, ověřte verzi loaderu používanou ve vašem prostředí.
Příklady pro konkrétní platformy najdete v průvodcích Docusaurus, MkDocs, VitePress, WordPress nebo GitBook.
Skrytí widgetu na určitých stránkách
Chcete-li widget vizuálně skrýt, použijte následující CSS pouze na vybraných stránkách (při globálním použití widget skryje všude):
.chattybox-widget {
display: none;
}
Skrytí pomocí CSS nezastaví inicializaci, požadavky API ani hlášení chyb a není nástrojem pro správu souhlasu či ochranu soukromí. Loader o souhlasu nerozhoduje: skript vkládejte až po udělení požadovaného souhlasu a po jeho odvolání ani na vyloučených trasách ho znovu nevkládejte. Při navigaci na straně klienta nebo odvolání souhlasu použijte window.ChattyBox.destroy() pouze tehdy, pokud loader ve vašem prostředí teardown podporuje; pouhé odebrání tagu <script> nestačí. Mount handly SDK 0.1.4 se počítají: pro konečný teardown odeberte všechny odpovídající handly. Teardown odstraní vlastní UI a styly a zruší čekající práci, nemůže však vzít zpět požadavky, které už zpracoval server. Widget znovu inicializujte pouze tehdy, pokud je souhlas udělen a aktuální trasa jeho zobrazení dovoluje.
Ovládání widgetu z prohlížeče
V aktuálním zdrojovém kódu v16 je window.ChattyBox k dispozici už během spouštění se stavem loading; i v této fázi lze zavolat destroy(). Po úspěšném dokončení inicializace ověřte window.ChattyBox?.status === 'ready' před voláním open(), close(), toggle() nebo sendMessage(text). Samotné načtení skriptu nezaručuje, že se dokončilo načtení konfigurace a překladů. destroy() odstraní widget a styly, přeruší práci instance a odstraní globální objekt; nevrátí zpět požadavek, který už zpracoval server. close() pouze zavře chatovací panel — spouštěcí tlačítko zůstane. sendMessage(text) vrací promise pro dokončení operace UI, nikoli promise s odpovědí; odeslání další zprávy během čekajícího požadavku se ignoruje. Tento globální objekt se liší od konstruktorů SDK v window.ChattyboxSDK. Než se na tyto funkce spolehnete, ověřte verzi loaderu používanou ve vašem prostředí.
Motivy světlého a tmavého vzhledu řízené webem (aktuální zdrojový kód)
Postup config-as-code v aktuálním zdrojovém kódu podporuje volitelné palety widget.theme.light a widget.theme.dark. Každá přijímá primaryColor, backgroundColor a textColor jako šestimístné hexadecimální barvy; vynechané barvy převezmou hodnoty ze základního widget.theme. Stávající konfigurace s jedním motivem fungují dál beze změny. Tato možnost vyžaduje CLI a backend z aktuálního zdrojového kódu a hostovaný loader v16; vydaný CLI/config 0.3.1 tato nová pole nepřijímá.
Nastavte data-theme="light" nebo data-theme="dark" na tagu skriptu loaderu ještě před jeho spuštěním a vyberte tak výchozí paletu. Poté propojte přepínač svého webu s API prohlížeče:
window.ChattyBox?.setTheme('light');
window.ChattyBox?.setTheme('dark');
window.ChattyBox?.setTheme(null); // Restore the configured base appearance.
Widget aktualizuje stávající styly bez resetování zpráv, zdrojů, rozepsaného textu nebo čekajícího požadavku. Výběr motivu nemění dostupnost widgetu ani neodstraní označení ChattyBox. Za ukládání preferencí a chování podle systémového motivu odpovídá váš web; widget pouze vybírá nakonfigurovanou paletu.
Vlastní integrace
Potřebujete přizpůsobenější nastavení než hostovaný widget? Vytvořte vlastní rozhraní pomocí JavaScript SDK nebo požádejte o pomoc s architekturou na support@chattybox.ai.
Vícejazyčná podpora
Níže popsané chování platí pro aktuální zdrojový kód: widget sleduje změny <html lang> a atributu data-locale skriptu loaderu a štítky aktualizuje na místě, aniž by resetoval konverzaci, rozepsaný text nebo čekající opakovaný požadavek. Samotná navigace jazyk nezmění; podle potřeby aktualizujte jeden z těchto atributů. Změny nastavení v řídicím panelu stále vyžadují novou inicializaci. Nepředpokládejte, že loader používaný ve vašem prostředí tuto podporu obsahuje.
Oficiálně podporované jazyky
Widget má katalogy překladů pro 14 jazyků. Všechny aktuální katalogy používají rozvržení zleva doprava. Katalogy UI nepřekládají text napsaný autorem projektu ani odpovědi vytvořené AI.
| Jazyk | Kód |
|---|---|
| Angličtina | en |
| Francouzština | fr |
| Němčina | de |
| Španělština | es |
| Italština | it |
| Nizozemština | nl |
| Portugalština | pt |
| Polština | pl |
| Švédština | sv |
| Indonéština | id |
| Estonština | et |
| Finština | fi |
| Velština | cy |
| Čeština | cs |
:::note UI jazyk a odpovědi Aktuální zdrojový kód hostovaného loaderu posílá rozpoznané UI locale spolu s chatovými požadavky. Backend detekuje jazyk otázky a pokouší se mu přizpůsobit vyhledávání a generování. Rozpoznaný signál jazyka otázky má při výběru jazyka produktových fallback zpráv přednost před UI locale; pokud detekce není průkazná nebo se opírá pouze o heuristiku anglického textu ASCII, UI locale může jazyk těchto zpráv určit. Nepřekládá fallback text nakonfigurovaný projektem ani nemění odpověď vygenerovanou AI. Kvalita odpovědí a dostupné jazyky závisí na indexovaném obsahu a nakonfigurovaném modelu; katalogy UI kvalitu odpovědi nezaručují. :::
Jak funguje detekce jazyka
Widget používá kaskádový systém detekce:
- Povolené přepsání skriptem - Podporované
data-localemá přednost, pokudallowLocaleOverridenenífalse— i v pevném režimu. - Pevný režim - Bez podporovaného a povoleného přepsání se použije
defaultLocalea jazyk stránky ani prohlížeče se ignoruje. - Automatický režim - Postupně se kontrolují
<html lang>,navigator.language, každá položkanavigator.languages, zastaraléuserLanguagea nakonecdefaultLocale; vybere se první podporovaný jazyk. - Normalizace - Při porovnávání nezáleží na velikosti písmen a rozpoznaná regionální locale, například
fr-CA, se převedou na podporovaný základní jazyk. Nepodporované hodnoty se přeskočí; není-li podporována žádná, použije se angličtina. Výchozí hodnoty jsou automatický režim, angličtina a povolené přepsání skriptem.
Vlastní názvy záhlaví a uvítací zprávy se zobrazují beze změny, automaticky se nepřekládají. Výchozí názvy a uvítací zprávy v aktuálním zdrojovém kódu používají lokalizované popisky. Pokud se překlady nenačtou po úspěšném načtení konfigurace, widget dál funguje s vestavěnými anglickými popisky.
Ruční přepsání jazyka
Chcete-li požádat o konkrétní jazyk bez ohledu na nastavení prohlížeče, povolte Povolit přepsání skriptem a před spuštěním loaderu přidejte podporovaný atribut data-locale:
<script
src="https://chattybox.ai/widget.js"
data-api-key="YOUR_API_KEY"
data-locale="de"
data-api-url="https://adorable-woodpecker-629.convex.site/chat"
async
></script>
:::tip Případ použití
To je obzvlášť užitečné pro vícejazyčný web, kde má každá jazyková verze vlastní URL (např. /de/, /fr/). Nastavte data-locale podle jazyka každé stránky a zkontrolujte vykreslené rozhraní.
:::
Jazyková nastavení v řídicím panelu
V řídicím panelu aplikace můžete nastavit jazykové preference widgetu pro každý projekt:
- Automatická detekce - Nejprve jazyk stránky, poté jazyky prohlížeče
- Pevné - Použije nakonfigurovaný výchozí jazyk, pokud jej nepřepíše povolené
data-locale - Povolit přepsání skriptem - Povolí či zakáže přepsání pomocí atributu
data-locale
Tato nastavení najdete v řídicím panelu → Přizpůsobení → Vzhled → Jazyk. Zkontrolujte stav automatického ukládání jazyka; před testováním opravte případné chyby nebo ukládání zkuste znovu.
Párování jazyka obsahu
Pro užitečné vícejazyčné prostředí indexujte veřejný obsah v jazycích návštěvníků a testujte zdroje; detekce ani vyhledávání nejsou zaručeny. Postupujte takto:
- Pomocí souboru
sitemap.xmlscrapujte všechny jazykové verze dokumentace. - Scraper se pokusí rozpoznat jazyk stránky; zkontrolujte obsah a citace.
- Vyhledávání se pokusí upřednostnit jazyk otázky, ale může použít jiný indexovaný obsah.
Nastavení v řídicím panelu aplikace: Při konfiguraci scrapování použijte URL sitemapu (např. https://yourdocs.com/sitemap.xml) k objevení jazykových verzí a pak ověřte indexované stránky. Sitemapy neobcházejí limity procházení ani vyloučení.
Řešení problémů
Widget se stále zobrazuje anglicky
- Tvrdé obnovení jako diagnostika - Obnovte stránku pomocí Ctrl+F5 nebo Cmd+Shift+R a v síťovém panelu prohlížeče zkontrolujte požadavky na widget a překlady
- Zkontrolujte
data-locale- Ověřte, že je atribut správně nastaven na podporovaný kód jazyka - Zkontrolujte režim projektu a povolení přepsání - Pevný režim nebo zakázané přepsání může záměrně ignorovat jazyk prohlížeče či
data-locale - Ověřte jazyk prohlížeče - Zkontrolujte, zda je preferovaný jazyk prohlížeče nastaven správně
- Zkontrolujte
langstránky - Ujistěte se, že stránka obsahuje<html lang="de">(nebo odpovídající kód)
Zdroje jsou ve špatném jazyce
- Scrapujte obsah znovu - Ověřte, že jsou indexovány všechny jazykové verze
- Použijte sitemap.xml - Ověřte, že požadované adresy URL byly skutečně indexovány; limity procházení a vyloučení je mohou vynechat.
- Zkontrolujte jazyk dotazu - AI se pokouší sladit jazyk odpovědi s jazykem dotazu
Chybějící překlady
- Zkontrolujte podporované jazyky a požadavky - Katalogy existují pouze pro 14 výše uvedených kódů; chybějící klíče používají vestavěné náhradní popisky.
Doporučené postupy
- Nastavte na stránkách
<html lang>- Pomáhá přístupnosti i detekci widgetu - Během vývoje testujte s
data-locale- Ověřte, že se každý jazyk vykreslí správně - Scrapujte všechny jazykové verze - Použijte
sitemap.xmlk objevení verzí a ověřte indexované stránky. - Prověřujte skutečné otázky - Kontrolujte konverzace a jazykově specifické mezery v obsahu; řídicí panel aktuálně neukazuje rozdělení locale widgetu