:::note Stav verzí Vydané npm SDK 0.1.4 s hostovaným widget.js v15 podporuje teardown přes remove() nebo window.ChattyBox.destroy(): odstraní UI/styly a zruší čekající inicializaci, retry i probíhající chat. Chat v15 provede nejvýše 10 pokusů v plánovacím rozpočtu 30 s, nikoli jako pevný timeout každého požadavku. sendMessage() v headless SDK automaticky neopakuje požadavky. :::

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 Test Chat, teprve potom věnujte čas vzhledu. Kompletní postup najdete v části Začínáme.

Nakonfigurujte hostovaný widget

1. Otevřete řídicí panel a vyberte projekt.
2. Přejděte na kartu Embed.
3. Prohlédněte si a uložte vzhled widgetu a chování jazyků.

Karta Embed řídí prezentaci a generuje instalační kód, veřejné klíče se však spravují samostatně. Až budete připraveni k instalaci:

1. Otevřete Public Keys a vytvořte klíč pro prohlížeč.
2. V případě potřeby volitelně omezte jeho přesné originy na zamýšlený web.
3. Vraťte se do Embed, vyberte klíč a zkopírujte vygenerovaný úryvek.
4. 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>

tip

Uložené změny se načtou při další inicializaci; otevřenou stránku je nutné obnovit.

---

Vizuální přizpůsobení

ChattyBox obsahuje plně integrovaný vizuální editor. Vzhled a dojem widgetu můžete dokonale sladit se svou značkou, aniž byste se dotkli kódu.

Ovládací prvky v řídicím panelu

1. Accent Color - Vyberte hlavní barvu značky. Ovlivňuje spouštěč, hlavní zvýraznění a zprávy uživatele.

2. Position - Zvolte, kde se widget na obrazovce zobrazí.

3. Header Title - Nastavte název zobrazený v horní části okna chatu.

4. Welcome Message - Přizpůsobte první zprávu, kterou návštěvníci uvidí po otevření chatu.

poznámka

Změny uložte a ověřte po obnovení stránky; náhled dashboardu není hostovaný widget.

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.

Řídicí panel použijte pro barvy, pozici, ikonu, název záhlaví, uvítací zprávu, výchozí jazyky, správu veřejných klíčů, scraping a analytiku.

Pokud projekt používá omezení originů veřejného klíče, udržujte tato omezení synchronizovaná s doménami, na kterých je widget nainstalován.

Atributy skriptu používejte pouze pro hodnoty, které widget potřebuje při načtení stránky:

• data-api-key identifikuje veřejný klíč widgetu.
• data-api-url určuje, kam má widget odesílat požadavky. V produkci jde o stabilní URL https://...convex.site/chat z vašeho řídicího panelu.
• data-locale žádá jazyk UI při inicializaci pouze tehdy, když projekt povoluje přepsání skriptem.

Pokud se widget po instalaci nezobrazuje, přečtěte si Řešení problémů.

Widget pro Popular Triggers automaticky odesílá aktuální HTTP(S) stránku bez query/fragmentu. CSS display:none nezastaví inicializaci ani požadavky; k nezavedení vynechte skript. Hostovaný widget.js v15 poskytuje window.ChattyBox.destroy() a vydané SDK 0.1.4 poskytuje remove() pro teardown.

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

Pokud potřebujete widget na vybraných stránkách skrýt, můžete to udělat pomocí CSS:

.chattybox-widget {
  display: none;
}

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

Widget určí jazyk UI jen při inicializaci podle režimu projektu Fixed nebo Auto; nesleduje změny tras SPA.

Oficiálně podporované jazyky

Widget má katalogy překladů pro 14 jazyků. Katalog neznamená, že je přeložen každý viditelný nebo přístupný řetězec, ani nezaručuje kvalitu odpovědí.

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 Katalog UI není jazykový parametr chatu ani záruka kvality odpovědi; ta závisí na otázce, modelu a indexovaném obsahu. :::

Jak funguje detekce jazyka

Widget používá kaskádový systém detekce:

1. Neprázdné data-locale vyhraje jen při Allow Script Override.
2. V Fixed se použije defaultLocale.
3. V Auto: <html lang>, poté jazyk prohlížeče a výchozí jazyk.
4. Nepodporovaná hodnota přejde rovnou na angličtinu; podporované regionální hodnoty se zkrátí na základní kód.

Ruční přepsání jazyka

Chcete-li požádat o konkrétní jazyk bez ohledu na nastavení prohlížeče, povolte Allow Script Override a před spuštěním loaderu přidejte 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:

• Auto-detect - Nejdříve jazyk stránky, poté prohlížeče
• Fixed Language - Výchozí jazyk, pokud jej nepřepíše povolené data-locale
• Allow Script Override - Povolí či zakáže přepsání pomocí atributu data-locale

Tato nastavení najdete v řídicím panelu → Projekt → karta Embed → část Widget Language.

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:

1. Pomocí souboru sitemap.xml scrapujte všechny jazykové verze dokumentace.
2. Scraper se pokusí rozpoznat jazyk stránky; zkontrolujte obsah a citace.
3. 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
• Ověřte jazyk prohlížeče - Zkontrolujte, zda je preferovaný jazyk prohlížeče nastaven správně
• Zkontrolujte lang strá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 - Katalogy mají pouze 14 výše uvedených kódů; chybějící popisky mohou použít anglickou zálohu.

Doporučené postupy

1. Nastavte na stránkách <html lang> - Pomáhá přístupnosti i detekci widgetu
2. Během vývoje testujte s data-locale - Ověřte, že se každý jazyk vykreslí správně
3. Scrapujte všechny jazykové verze - Použijte sitemap.xml k objevení verzí a ověřte indexované stránky.
4. Prověřujte skutečné otázky - Kontrolujte konverzace a jazykově specifické mezery v obsahu; řídicí panel aktuálně neukazuje rozdělení locale widgetu