:::note Versionsstatus
Den incheckade aktuella källkoden för den hostade loadern identifierar sig som v16. Beteendet som uttryckligen anges som aktuellt källbeteende nedan är inte ett påstående om vilken loaderversion som är driftsatt; kontrollera den driftsatta versionen innan du förlitar dig på det. Det publicerade npm-SDK:t 0.1.4 använder referensräknade mount-handtag: ta bort alla handtag med identiska alternativ för att utlösa den slutliga teardownen.
:::
Anpassa den hostade widgeten
Anpassa det färdiga gränssnittet som laddas från https://chattybox.ai/widget.js. Se Installationsguiderna för kanoniska installationsexempel för framework och plattform.
Innan du anpassar
Skapa projektet, indexera innehållet och verifiera representativa svar i Testa chatbot innan du lägger tid på presentationen. Se Kom igång för hela ordningen.
Konfigurera den hostade widgeten
- Gå till din instrumentpanel och välj projektet.
- Öppna Anpassa → Utseende för att ändra widgetens utseende, varumärke och språk.
- Kontrollera den relevanta sparstatusen. Åtgärda valideringsfel eller försök spara igen om en ändring misslyckas innan du testar widgeten.
Installationskod och offentliga nycklar hanteras under Installera. När du är redo att installera:
- Öppna Installera → Nycklar & domäner för att kontrollera eller skapa en offentlig webbläsarnyckel och granska dess origininställningar.
- Öppna Installera → Installation på webbplatsen, välj en lämplig nyckel och kopiera kodfragmentet. En nyckel utan begränsningar fungerar från alla origins; en nyckel som förberetts för en webbplats kan redan vara begränsad till webbplatsens origin. Kontrollera den valda nyckeln innan du använder staging eller localhost.
- Du kan aktivera en exakt originbegränsning som extra skydd. Den autentiserar inte besökare; webbläsarnyckeln är offentlig och besökaren behöver inte logga in.
- Följ Installationsguiderna för din plattform.
<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>
Ändringar av widgetens presentation som sparas i instrumentpanelen används vid nästa widgetinitiering utan att kodfragmentet på webbplatsen behöver bytas ut. Redan öppna sidor uppdateras inte live; ladda om för att hämta sparade inställningar.
Visuell anpassning
Instrumentpanelens editor låter dig justera stödda widgetfärger, placering, ikon och text utan att redigera webbplatsens kod. Kontrollera resultatet i den hostade widgeten; förhandsvisningen och loadern är inte identiska.
Kontroller i instrumentpanelen
-
Accentfärg - Välj varumärkets primära färg. Den påverkar startknappen, viktiga markeringar och användarmeddelanden.
-
Widgetposition - Välj var widgeten ska visas på skärmen.
-
Rubrik - Ange titeln som visas högst upp i chattfönstret.
-
Välkomstmeddelande - Anpassa det första meddelandet som besökare ser när de öppnar chatten.
-
Visa ChattyBox-varumärket - Varumärket måste visas med Free. Starter och högre planer kan dölja sidfoten ”Drivs av ChattyBox”.
Redigeraren har även Widgetbakgrund och Textfärg, samt standardrobot, emoji, bild-URL eller uppladdad bild som widgetikon. Uppladdade ikoner får vara högst 512 KiB och måste ha en accepterad bild-MIME-typ (PNG, JPEG, WebP, SVG, GIF eller ICO). Storlekskontrollen iconSize visas bara för ikoner av typen url eller upload. Den aktuella källkodens hostade v16-loader använder iconSize för att ändra storleken på startknappen och ikonen. Kontrollera den driftsatta loadern innan du förlitar dig på det beteendet.
Bekräfta relevant autosparstatus och ladda sedan om den installerade sidan för att verifiera ändringarna. Utseendets sparstatus heter Sparstatus för utseende; språkinställningarnas heter Sparstatus för språk och varumärkets Sparstatus för varumärke. Om en sparning misslyckas kan du välja Försök att spara igen. Förhandsvisningen i instrumentpanelen är en mock, inte den hostade widgeten. I config-låsta projekt hanteras utseende och språk via config-as-code; projekt med rätt behörighet kan fortfarande spara varumärkesinställningen separat.
Standardvärden för konfiguration
Det här är standardvärdena i ett lyckat offentligt widget-config-svar när inget anpassat värde finns:
| Fält | Standardvärde |
|---|---|
enabled | true, om det inte har inaktiverats för projektet |
themeColor | #3b82f6 |
chatBgColor | #0f172a |
textColor | #f8fafc |
position | bottom-right; alla fyra hörn stöds |
iconType, iconSize | default, medium; aktuell källkod v16 använder storleken för startknappen och ikonen. Storlekskontrollen visas bara för iconType-värdena url och upload |
iconEmoji, iconUrl | pratbubbla-emoji, null |
headerTitle | Chat with us (API:ets standardvärde) |
welcomeMessage | Hi! 👋 How can I help you today? (API:ets standardvärde) |
showBranding | true; varumärket är alltid aktiverat för Free |
localeMode, defaultLocale, allowLocaleOverride | auto, en, true (standardvärden) |
Om konfigurationshämtningen misslyckas eller svaret är ogiltigt blir widgeten otillgänglig i den aktuella källkodens loader v16; ingen reservwidget visas. Om konfigurationen hämtas men översättningarna inte gör det kan widgeten ändå visas med inbyggda engelska etiketter. Kontrollera den driftsatta loaderns version innan du förlitar dig på detta källkodsbeteende.
Ett lyckat svar med enabled: false hindrar också widgeten från att visas; chatt-API:t avvisar då förfrågningar med HTTP 403, även från SDK:t. I aktuell källkod v16 begär den hostade loadern konfiguration med Authorization: Bearer och försöker en gång till med nyckeln i en frågeparameter endast efter HTTP 400. Den gör även separata återförsök för startens konfigurations- och översättningshämtningar. Detta är skilt från återförsöken för chattmeddelanden nedan. Det publicerade SDK:t 0.1.4 använder samma config-fallback endast när sidan exponerar window.ChattyboxSDK. SDK:ts mount-delning gäller identiska alternativ; ändring av nyckel, endpoint, skript-URL, locale eller debug-inställning nekas tills alla matchande handtag har tagits bort. Kontrollera den driftsatta loaderns version innan du förlitar dig på loaderns källkodsbeteende.
Avancerade alternativ
Inställningar i instrumentpanelen kontra skriptegenskaper
De flesta av widgetens beteenden bör hanteras från instrumentpanelen, så att enkla ändringar inte kräver att webbplatsen distribueras på nytt.
Använd instrumentpanelen för färger, position, ikon, rubrik, välkomstmeddelande, standardspråk, hantering av offentliga nycklar, skrapning och analys.
Om du aktiverar en originbegränsning för en offentlig nyckel ska du hålla dess exakta origins synkroniserade med domänerna där widgeten används. Begränsningen är valfri, ett extra skydd och inte besökarautentisering.
Använd skriptegenskaper endast för värden som widgeten behöver när sidan laddas:
data-api-keyidentifierar den offentliga widgetnyckeln.data-api-urlanger vart widgeten ska skicka förfrågningar. I produktion är detta en stabilhttps://...convex.site/chat-URL från instrumentpanelen.data-localebegär ett specifikt språk för widgetens gränssnitt om projektet tillåter skriptöverskrivning. Loadern i aktuell källkod v16 följer även senare ändringar av attributet och uppdaterar språket på plats.data-colorochdata-positionåsidosätter sparad accentfärg respektive position efter en lyckad konfigurationshämtning. Föredra instrumentpanelens värden; attributen kan dölja senare ändringar där.data-debug="true"aktiverar konsoldiagnostik; det är avstängt som standard.
För varje nytt meddelande försöker den hostade loadern i aktuell källkod skicka den aktuella sidans giltiga HTTP(S)-origin och sökväg för analysen Populära triggers. Den kontrollerar inte om sidan är offentligt tillgänglig. Ogiltig eller för lång kontext utelämnas; återförsök behåller det ursprungliga meddelandets kontext. Frågesträng, fragment och autentiseringsuppgifter tas bort, men sökvägar kan innehålla känsliga identifierare. Ladda inte widgeten på känsliga sidor bara för att frågesträngen tas bort.
Sidkontexten hämtas från aktuell HTTP(S)-URL, inte genom att kontrollera om sidan är offentlig, och påverkar inte vilka indexerade källor som hämtas. Loadern kan även skicka initierings-, konfigurations-, översättnings- och chattfel till /widget-error via beacon eller fetch. Rapporten kan innehålla begränsade feldetaljer, locale, version och sidans origin/sökväg; debug-läge krävs inte. Den aktuella källkodens widget respekterar även prefers-reduced-motion, har en etiketterad meddelandeinmatning och live-annonseringar samt visar källhänvisningar i den tangentbordstillgängliga Källor-panelen.
Chatten använder kompletta JSON-svar, inte tokenströmning. Loadern i aktuell källkod v16 skapar en idempotensnyckel per meddelande och gör högst 10 automatiska transportförsök vid nätverksfel, avbruten läsning av ett lyckat svar, HTTP 429, HTTP 5xx och HTTP 409 med en läsbar Retry-After-header. Den schemalägger inga fler försök om väntetiden skulle överskrida 30-sekundersbudgeten; detta är inte en hård timeout för en begäran som redan pågår. Webbläsarens CORS-regler kan dölja Retry-After. Samma idempotensnyckel används vid återförsök, så servern kan spela upp det lagrade svaret i stället för att behandla meddelandet igen. Det automatiska chattåterförsöket gäller inte headless sendMessage() i SDK:t; startens GET-återförsök och SDK 0.1.4-fallbacken efter config-400 är separata begränsade beteenden. Samtalstillståndet finns i minnet för widgetinstansen och försvinner vid omladdning eller ominitiering, även om redan lagrade servermeddelanden kan finnas kvar. Källhänvisningar dedupliceras och begränsas till tre visade poster; reservsvar kan sakna källor. Kontrollera den driftsatta loaderns version innan du förlitar dig på detta källkodsbeteende.
Om widgeten inte visas efter installationen kan du läsa Felsökning.
För plattformsspecifika exempel kan du börja med Docusaurus, MkDocs, VitePress, WordPress eller GitBook.
Dölj widgeten på specifika sidor
Om du bara vill dölja widgeten visuellt kan du använda CSS på de utvalda sidorna (om du använder den globalt döljs widgeten överallt):
.chattybox-widget {
display: none;
}
Att dölja widgeten med CSS stoppar inte initiering, API-anrop eller felrapportering och är inte en samtyckes- eller integritetskontroll. Loadern fattar inget samtyckesbeslut: vänta med att lägga in skriptet tills nödvändigt samtycke finns och förhindra att det läggs in igen efter återkallat samtycke eller på uteslutna sidor. Att bara ta bort skripttaggen stoppar inte en redan laddad widget. För navigering mellan klientrutter eller återkallat samtycke tillhandahåller den aktuella källkodens hostade widget.js v16 window.ChattyBox.destroy(). Ta bort alla identiska SDK 0.1.4-mount-handtag för att signalera slutlig teardown. Kontrollera att den driftsatta loadern stöder teardown. Teardown tar bort widgetens egna UI/stilar och avbryter väntande arbete, men kan inte ångra en begäran som servern redan har behandlat.
Webbläsarkontroller
I aktuell källkod v16 finns window.ChattyBox redan under initieringen med status: 'loading' och destroy(). Om du anropar destroy() då avbryts initieringen. open(), close(), toggle() och sendMessage(text) finns först efter att initieringen är klar; kontrollera att window.ChattyBox?.status === 'ready' innan du anropar dem. Att skriptet har laddats betyder inte att konfiguration och översättningar är klara. destroy() tar bort widgetens egna element/stilar, avbryter dess arbete och rensar globalen, men kan inte ångra en begäran som servern redan har behandlat. close() stänger bara chattpanelen; startknappen finns kvar. sendMessage(text) returnerar ett löfte för UI-operationen, inte ett löfte om svaret; anrop medan ett annat meddelande väntar ignoreras. Den här globalen är skild från SDK-konstruktörerna på window.ChattyboxSDK. Kontrollera den driftsatta loaderns version innan du förlitar dig på beteendet.
Webbplatsstyrda ljusa och mörka teman (aktuell källkod)
Arbetsflödet config-as-code i aktuell källkod stöder valfria paletter widget.theme.light och widget.theme.dark. Var och en kan innehålla primaryColor, backgroundColor och textColor i sexsiffrigt hexformat; utelämnade färger ärvs från grundläggande widget.theme. Befintliga konfigurationer med ett enda tema fortsätter att fungera. Detta kräver CLI/backend i aktuell källkod och hostad loader v16; publicerad CLI/config 0.3.1 godtar inte de nya fälten. Detta är inte ett påstående om vilken loaderversion som är driftsatt.
Ange data-theme="light" eller data-theme="dark" på loaderskriptet innan det körs för att välja startpalett. Koppla sedan webbplatsens växlare till webbläsar-API:t:
window.ChattyBox?.setTheme('light');
window.ChattyBox?.setTheme('dark');
window.ChattyBox?.setTheme(null); // Restore the configured base appearance.
Widgeten uppdaterar befintliga stilar utan att återställa meddelanden, källor, utkast eller en väntande begäran. Temavalet kan inte inaktivera widgeten eller ta bort varumärket. Webbplatsen ansvarar för att spara inställningen och hantera operativsystemets tema; widgeten väljer bara den konfigurerade paletten.
Anpassade integrationer
Behöver du en mer skräddarsydd konfiguration än den hostade widgeten? Bygg ett eget gränssnitt med JavaScript SDK eller kontakta support@chattybox.ai för arkitekturhjälp.
Flerspråkigt stöd
Den hostade widgeten i aktuell källkod v16 väljer UI-locale enligt projektets Fixed- eller Auto-läge. Den följer ändringar av <html lang> och loaderskriptets data-locale, och uppdaterar etiketter på plats utan att återställa konversation, utkast eller väntande återförsök. En navigering väljer inte i sig ett nytt språk; uppdatera något av dessa attribut när det behövs. Ändringar i instrumentpanelen kräver fortfarande ominitiering. Detta beskriver aktuell källkod, inte nödvändigtvis den driftsatta loadern.
Officiellt stödda språk
Widgeten har översättningskataloger för 14 språk. Alla aktuella kataloger använder layout från vänster till höger. Projektets egna texter och AI-genererade svar översätts inte av UI-katalogerna. En katalog innebär inte att varje synlig eller tillgänglig sträng är översatt och garanterar inte svarskvalitet.
| Språk | Kod |
|---|---|
| Engelska | en |
| Franska | fr |
| Tyska | de |
| Spanska | es |
| Italienska | it |
| Nederländska | nl |
| Portugisiska | pt |
| Polska | pl |
| Svenska | sv |
| Indonesiska | id |
| Estniska | et |
| Finska | fi |
| Walesiska | cy |
| Tjeckiska | cs |
:::note UI-språk och svar Widgeten i den aktuella källkoden skickar den valda UI-lokalen med chattförfrågningarna. Backend upptäcker frågans språk och försöker språkmedveten hämtning och generering. En identifierad språksignal i frågan har företräde framför UI-lokalen för produktens egna reservmeddelanden; om språkidentifieringen är osäker eller enbart bygger på den ASCII-baserade engelska heuristiken kan UI-lokalen styra språket. Utan någon av signalerna används produktens standardvärden. Projektets egna reservmeddelanden visas ordagrant och AI-genererade svar översätts inte av UI-lokalen. Varken svarsspråk eller svarskvalitet garanteras; det beror bland annat på indexerat innehåll och modell. Detta beskriver beteendet i aktuell källkod. :::
Så fungerar språkidentifiering
Widgeten använder ett kaskadbaserat system för identifiering:
- Tillåten skriptåsidosättning - Ett
data-locale-värde som stöds vinner omallowLocaleOverrideinte ärfalse, även i Fixed-läge. - Fixed-läge - Utan en tillåten, stödd åsidosättning används
defaultLocale; sidans och webbläsarens språk ignoreras. - Auto-läge - Widgeten väljer det första stödda språket bland sidans
<html lang>,navigator.language, varje värde inavigator.languages, äldreuserLanguageoch slutligendefaultLocale. - Normalisering - Språkjämförelsen är skiftlägesokänslig och stödda regionala värden som
fr-CAreduceras till baskoden. Värden som inte stöds hoppas över; om inget värde stöds används engelska.
Standardvärdena är Auto-läge, engelska och tillåtna skriptåsidosättningar. Egna rubriker och välkomstmeddelanden visas ordagrant. Aktuella standardrubriker och välkomstmeddelanden lokaliseras; om översättningarna inte kan hämtas används inbyggda engelska etiketter.
Manuellt språkbyte
För att ange ett visst språk från början aktiverar du Tillåt överskrivning via skript och lägger till ett data-locale-attribut med ett språk som stöds innan loadern körs. I aktuell källkod v16 kan du också ändra attributet efter initieringen; widgeten uppdaterar då språket på plats.
<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 Användningsfall
Detta är särskilt användbart på en flerspråkig webbplats där varje språkversion har en egen URL (t.ex. /de/, /fr/). Ange data-locale enligt sidans språk och kontrollera det renderade gränssnittet.
:::
Språkinställningar i instrumentpanelen
I appens instrumentpanel kan du konfigurera widgetens språkpreferenser per projekt:
- Upptäck automatiskt - Använder sidans språk före besökarens webbläsarspråk
- Fast - Använder det konfigurerade standardspråket om inte ett tillåtet
data-localeåsidosätter det - Tillåt överskrivning via skript - Aktiverar eller inaktiverar åsidosättning med attributet
data-locale
Du hittar inställningarna i instrumentpanelen → projekt → Anpassa → Utseende → Widgetspråk. Kontrollera Sparstatus för språk och åtgärda fel eller välj Försök att spara igen innan du testar.
Matcha innehållets språk
För en användbar flerspråkig upplevelse ska du indexera offentligt innehåll på besökarnas språk och testa källorna; identifiering och hämtning är inte garanterade. Så här gör du:
- Upptäck önskade publika språkversioner med
sitemap.xmloch kontrollera sedan vilka URL:er som faktiskt indexerades. - Skraparen försöker upptäcka sidans språk; granska innehåll och källor.
- Hämtningen försöker föredra frågans språk men kan falla tillbaka på annat indexerat innehåll.
Konfiguration i appens instrumentpanel: Använd URL:en till din sitemap.xml (t.ex. https://yourdocs.com/sitemap.xml) när du konfigurerar skrapningen för att upptäcka språkversioner och kontrollera sedan de indexerade sidorna. Webbplatskartor kringgår inte crawlgränser eller undantag.
Felsökning
Widgeten visas fortfarande på engelska
- Hård uppdatering som diagnostik - Läs in sidan med Ctrl+F5 eller Cmd+Shift+R och kontrollera widget- och översättningsförfrågningar i webbläsarens nätverkspanel. Om konfigurationshämtningen misslyckas visas ingen reservwidget; om konfigurationen lyckas men översättningshämtningen misslyckas kan engelska etiketter användas.
- Kontrollera
data-locale- Kontrollera att attributet är korrekt inställt på en kod för ett stödspråk - Kontrollera projektets läge och tillstånd för överskrivning - Fast läge och inaktiverad överskrivning kan avsiktligt ignorera webbläsarens språk eller
data-locale - Verifiera webbläsarens språk - Kontrollera att webbläsarens föredragna språk är korrekt inställt
- Kontrollera sidans HTML lang - Kontrollera att sidan har
<html lang="de">(eller motsvarande kod)
Källorna är på fel språk
- Skrapa om innehållet - Kontrollera att de önskade publika språkversionerna verkligen indexerades
- Använd sitemap.xml - Kontrollera att önskade URL:er verkligen indexerades; crawlgränser och undantag kan utelämna dem
- Kontrollera frågans språk - AI:n försöker matcha svarsspråket med frågans språk
Översättningar saknas
- Kontrollera stödda språk - Endast de 14 koderna ovan har kataloger; saknade etiketter kan använda engelsk reservtext
Bästa praxis
- Ange
<html lang>på sidorna - Hjälper både tillgänglighet och identifiering av widgeten - Testa med
data-localeunder utvecklingen - Kontrollera att varje språk återges korrekt - Upptäck språkversioner - Använd
sitemap.xmlför upptäckt och kontrollera de indexerade sidorna; webbplatskartor kringgår inte crawlgränser eller undantag - Granska verkliga frågor - Kontrollera konversationer och språkspecifika innehållsluckor; instrumentpanelen visar för närvarande ingen fördelning av widgetens språkversioner
UI-katalogen översätter inte svar eller allt UI. Se avsnittet ovan om samtycke och teardown; källkoden för den hostade loadern är v16, men det är inte ett påstående om vilken version som är driftsatt.