:::note Versiooni olek
Praeguse lähtekoodina kirjeldatud funktsioone kontrolliti kohalikus hostitud loaderis v16; see ei tähenda, et need oleksid teie keskkonnas kasutatavas loaderis olemas. Enne nendele tuginemist kontrollige loaderi versiooni. Avaldatud npm-SDK 0.1.4 pakub remove()-i; täielikuks teardowniks eemaldage kõik sama konfiguratsiooniga loodud mount-käepidemed. Teardown toimib ainult siis, kui loader toetab SDK saadetud eemaldamissignaali.
:::
Hostitud vidina kohandamine
Kohandage valmis kasutajaliidest, mida laaditakse aadressilt https://chattybox.ai/widget.js. Raamistike ja platvormide ametlikud paigaldusnäited leiate paigaldusjuhenditest.
Enne kohandamist
Looge projekt, indekseerige selle sisu ja kontrollige tüüpilisi vastuseid jaotises Testi vestlusrobotit, enne kui hakkate välimusele aega kulutama. Täielikku järjekorda kirjeldab Alustamise leht.
Hostitud vidina seadistamine
- Avage juhtpaneel ja valige oma projekt.
- Avage Kohanda → Välimus, et muuta vidina välimust, brändingut ja Keele seadeid.
- Kontrollige automaatse salvestamise olekut. Enne paigaldatud vidina testimist parandage valideerimisvead või proovige ebaõnnestunud salvestamist uuesti.
Paigalduskoodi ja avalikke võtmeid hallatakse jaotises Paigalda. Enne paigaldamist:
- Avage Paigalda → Võtmed ja domeenid, et kontrollida origini piirangu seadeid või luua avalik brauserivõti. Võti on mõeldud kliendipoolses koodis kasutamiseks ega ole saladus.
- Jaotises Paigalda → Veebisaidi paigaldamine valige sobiv võti ja kopeerige loodud koodilõik. Piiranguteta loodud võti võtab päringuid vastu eri originidelt; veebisaidi jaoks ettevalmistatud võti võib olla juba piiratud selle saidi originiga. Enne staging-keskkonnas või localhost'is kasutamist kontrollige valitud võtme seadeid.
- Soovi korral lubage täpsete originite piirang lisakaitseks. Originipiirang ei tuvasta ega autentiseeri külastajaid.
- Järgige oma platvormi paigaldusjuhendeid.
<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>
Juhtpaneelil salvestatud vidina esitlusmuudatused rakenduvad järgmisel vidina algkäivitusel ilma teie saidil olevat koodilõiku asendamata. Juba avatud leht ei uuene reaalajas; laadige see uuesti.
Visuaalne kohandamine
Juhtpaneeli redaktor võimaldab muuta toetatud vidina värve, asukohta, ikooni ja teksti ilma saidi koodi muutmata. Kontrollige tulemust hostitud vidinas, sest eelvaade ja loader ei ole identsed.
Juhtpaneeli juhtelemendid
-
Rõhuvärv - Valige oma brändi põhivärv. See mõjutab avajat, olulisi esiletõsteid ja kasutaja sõnumeid.
-
Vidina asukoht - Valige, kus vidin ekraanil kuvatakse.
-
Päise pealkiri - Määrake vestlusakna ülaosas kuvatav pealkiri.
-
Tervitussõnum - Kohandage esimest sõnumit, mida külastajad vestluse avamisel näevad.
-
ChattyBoxi bränding - Starteri ja kõrgema paketi kasutajad saavad jaluse „Powered by ChattyBox” välja lülitada. Free-paketis peab bränding jääma nähtavaks.
Redaktoris saab muuta ka Vidina tausta ja Teksti värvi ning valida vidina ikooniks vaikeikooni, emotikoni, pildi URL-i või üles laaditud pildi. Üles laaditud ikoon võib olla kuni 512 KiB ning peab kasutama lubatud MIME-pilditüüpi (PNG, JPEG, WebP, SVG, GIF või ICO). Ikooni suuruse valik kuvatakse ainult siis, kui ikooniks on valitud pildi URL või üles laaditud pilt. Praeguse lähtekoodi hostitud v16 loader kasutab iconSize-i avaja ja ikooni suuruse määramiseks; enne sellele käitumisele tuginemist kontrollige, millist loaderi versiooni teie keskkond kasutab.
Kontrollige vastava automaatse salvestamise olekut ja laadige seejärel paigaldatud leht muudatuste kontrollimiseks uuesti. Juhtpaneeli eelvaade on makett, mitte hostitud vidin ise. Konfiguratsiooniga lukustatud projektides hallatakse välimuse ja lokaadi välju config-as-code'i kaudu; õigustatud paketiga projektides saab brändingut siiski eraldi salvestada.
Konfiguratsiooni vaikeväärtused
Kui kohandatud väärtust pole määratud, tagastab edukas avalik vidina konfiguratsioonipäring järgmised vaikeväärtused:
| Väli | Vaikeväärtus |
|---|---|
enabled | true, kui vidinat pole projekti jaoks välja lülitatud |
themeColor | #3b82f6 |
chatBgColor | #0f172a |
textColor | #f8fafc |
position | bottom-right; toetatud on kõik neli nurka |
iconType, iconSize | default, medium; praeguse lähtekoodi hostitud v16 kasutab suurust avaja ja ikooni jaoks |
iconEmoji, iconUrl | jutumulli emotikon, null |
headerTitle | Chat with us (API vaikeväärtus) |
welcomeMessage | Hi! 👋 How can I help you today? (API vaikeväärtus) |
showBranding | true; Free-projektides sunnitakse see väärtuseks true |
localeMode, defaultLocale, allowLocaleOverride | auto, en, true (vaikeväärtused) |
Praeguse lähtekoodi hostitud loader jätab vidina ebaõnnestunud või vigase konfiguratsioonipäringu korral kättesaamatuks ega kuva asendusliidest. See erineb tõlgete laadimise veast: kui konfiguratsioonipäring õnnestus, kuid tõlkekataloog pole saadaval, kuvatakse vidin siiski sisseehitatud ingliskeelsete siltidega. Ka edukas konfiguratsioonivastus väärtusega enabled: false takistab vidina kuvamist; vestluse API lükkab sellise vidina päringud tagasi HTTP 403-ga, sh SDK päringud. Enne praeguse lähtekoodi käitumisele tuginemist kontrollige, millist loaderi versiooni teie keskkond kasutab.
Praeguse lähtekoodi hostitud v16 loader saadab konfiguratsioonipäringu koos päisega Authorization: Bearer ning kordab päringut ühe korra URL-i päringuparameetris oleva võtmega ainult HTTP 400 korral. Avaldatud SDK 0.1.4 kasutab sama piiratud konfiguratsiooni varumehhanismi, kui leht pakub window.ChattyboxSDK-d. Hostitud v16 kordab eraldi korduskatsele sobivaid käivitusaegseid konfiguratsiooni ja tõlgete GET-päringuid. Vestlussõnumite jaoks kasutab loader oma transporti. SDK mount'imisel jagab avaldatud SDK 0.1.4 ainult identseid suvandeid ning keeldub muudetud võtme, otspunkti, skripti URL-i, lokaadi või silumisseade korral uut mount'i tegemast, kuni kõik vastavad käepidemed on eemaldatud. Enne praeguse lähtekoodi käitumisele tuginemist kontrollige, millist loaderi versiooni teie keskkond kasutab.
Täpsemad valikud
Juhtpaneeli seaded ja skriptiatribuudid
Enamikku vidina käitumisest tuleks hallata juhtpaneelilt, et lihtsate muudatuste jaoks ei peaks veebisaiti uuesti juurutama.
Kasutage jaotist Kohanda → Välimus värvide, asukoha, ikooni, päise pealkirja, tervitussõnumi, keele ja ChattyBoxi brändingu jaoks. Jaotises Paigalda → Võtmed ja domeenid hallatakse avalikke võtmeid ja origin’e.
Avalik võti ei ole saladus ega autentiseeri külastajaid. Originipiirang on valikuline lisakaitse, mitte autentimine. Kui selle lubate, hoidke täpsete originite loend sünkroonis domeenidega, kus vidin töötab; kontrollige ka, kas valitud võtmel on konkreetse veebisaidi jaoks piirang juba olemas.
Kasutage skriptiatribuute ainult väärtuste jaoks, mida vidin vajab lehe laadimise ajal:
data-api-keytuvastab avaliku vidinavõtme.data-api-urlütleb vidinale, kuhu päringud saata. Tootmises on see juhtpaneelilt pärit stabiilnehttps://...convex.site/chatURL.data-localetaotleb kasutajaliidese kindlat keelt, kui projekt lubab skripti ülekirjutust. Praeguse lähtekoodi loader jälgib ka selle atribuudi hilisemaid muudatusi.data-colorjadata-positionalistavad pärast edukat konfiguratsioonipäringut salvestatud rõhuvärvi ja asukoha. Eelista juhtpaneeli väärtusi; need atribuudid võivad varjata hilisemaid juhtpaneeli muudatusi.data-debug="true"lülitab sisse konsoolidiagnostika; vaikimisi on see välja lülitatud.
Uue sõnumi korral püüab praeguse lähtekoodi vidin lisada Populaarsed käivitajad analüütika jaoks praeguse HTTP(S)-lehe origini ja tee, kontrollimata, kas leht on avalik. Vigane või liiga pikk kontekst jäetakse välja; korduskatsed säilitavad algse päringu konteksti. Query-stringid, fragmendid ja mandaadid eemaldatakse, kuid teed võivad sisaldada tundlikke identifikaatoreid. Vidin austab ka eelistust prefers-reduced-motion, pakub sildistatud sõnumisisendit ja reaalajas teavitusi ning kuvab viited klaviatuuriga kasutatava Allikad avamisvaliku kaudu.
Lehekontekst võetakse praegusest HTTP(S)-URL-ist, mitte kontrollist, kas leht on avalik. Ärge laadige vidinat tundlikele teedele üksnes seetõttu, et query-stringid eemaldatakse. Loader võib saata algkäivituse, konfiguratsiooni, tõlgete ja vestluse veateateid ka aadressile /widget-error, kasutades beacon'it või fetch'i; teated sisaldavad pikkuselt piiratud vea üksikasju, lokaati, versiooni ning lehe origini ja teed. Nende teadete saatmiseks pole silumisrežiim vajalik.
Vestlus tagastab täielikud JSON-vastused, mitte tokenite voogu. Praeguse lähtekoodi hostitud v16 loob iga loogilise sõnumi jaoks eraldi idempotentsusvõtme ja kasutab sama võtit transpordi korduskatsetel. Server võib siis tagastada salvestatud vastuse päringut uuesti töötlemata. Loader teeb kuni 10 automaatset transpordikatset võrguvigade, eduka vastusekeha lugemise katkemise, HTTP 429, HTTP 5xx ja loetava Retry-After päisega 409 korral. Kui viivitus ületaks 30-sekundilise eelarve, uut katset ei ajastata; see pole käimasoleva päringu range timeout. Brauseri CORS võib Retry-After päise peita. Headless sendMessage() seda korduskatsete käitumist ei paku; hostitud loaderi käivitusaegsed GET-korduskatsed ja SDK 0.1.4 konfiguratsiooni HTTP 400 varumehhanism on eraldi piiratud käitumised. Vestluse olek püsib selle vidinainstantsi mälus ning kaob lehe uuesti laadimisel või uuesti käivitamisel; serverisse salvestatud sõnumid võivad alles jääda. Allikad deduplikeeritakse ja kuvatakse kuni kolm kirjet; varuvastusel ei pruugi allikaid olla. Enne praeguse lähtekoodi käitumisele tuginemist kontrollige, millist loaderi versiooni teie keskkond kasutab.
Kui vidin pärast paigaldamist ei ilmu, vaadake tõrkeotsingut.
Platvormipõhiste näidete jaoks alustage Docusauruse, MkDocsi, VitePressi, WordPressi või GitBooki juhendist.
Vidina peitmine kindlatel lehtedel
Vidina visuaalseks peitmiseks lisa järgmine CSS ainult valitud lehtedel (kui rakendad seda kõikjal, peidab see vidina kõigil lehtedel):
.chattybox-widget {
display: none;
}
CSS-iga peitmine ei peata algkäivitust, API-päringuid ega veateavitust ning ei ole nõusoleku- ega privaatsuskontroll. Loader ei otsusta nõusoleku üle: lisage skript alles pärast nõutava nõusoleku saamist ning ärge lisage seda uuesti pärast nõusoleku tühistamist ega välistatud marsruutidel. Kliendipoolse marsruudivahetuse või nõusoleku tühistamise korral kasutage window.ChattyBox.destroy()-i ainult siis, kui teie keskkonna loader toetab teardown'i; ainult <script>-sildi eemaldamisest ei piisa. SDK 0.1.4 mount-käepidemed on viitearvestusega: lõpliku teardown'i käivitamiseks eemaldage kõik vastavad käepidemed. Teardown eemaldab vidina enda UI ja stiilid ning katkestab ootel töö, kuid ei saa tagasi võtta päringuid, mida server on juba töödelnud. Käivitage vidin uuesti ainult siis, kui nõusolek on olemas ja praegune marsruut lubab seda.
Vidina juhtimine brauserist
Praeguse lähtekoodi hostitud v16 puhul on window.ChattyBox olemas juba käivitumise ajal olekuga loading ning selles etapis saab kutsuda ka destroy()-it. Pärast edukat algkäivitust kontrollige enne open(), close(), toggle() või sendMessage(text) väljakutsumist, et window.ChattyBox?.status === 'ready'. Skripti laadimine üksi ei tähenda, et konfiguratsioon ja tõlked oleksid laaditud. destroy() eemaldab vidina ja stiilid, katkestab instantsi elueaga seotud töö ning kustutab globaalse objekti; see ei saa tagasi võtta päringut, mida server juba töötles. close() sulgeb ainult vestluspaneeli, avamisnupp jääb alles. sendMessage(text) tagastab UI-toimingu lubaduse, mitte vastuse lubaduse; uue sõnumi saatmist eiratakse, kui teine päring on veel pooleli. See globaalne objekt erineb window.ChattyboxSDK SDK-konstruktoritest. Enne sellele käitumisele tuginemist kontrollige, millist loaderi versiooni teie keskkond kasutab.
Veebisaidi juhitavad päeva-/ööteemad (praegune lähtekood)
Praeguse lähtekoodi config-as-code'i töövoog toetab valikulisi palette widget.theme.light ja widget.theme.dark. Mõlemas saab määrata kuuekohalised kuueteistkümnendvärvid primaryColor, backgroundColor ja textColor; määramata värvid pärivad baasväärtused widget.theme-ist. Olemasolevad ühe teemaga konfiguratsioonid töötavad endiselt muutmata. Selleks on vaja praeguse lähtekoodiga CLI-t ja taustsüsteemi ning hostitud loaderit v16; avaldatud CLI/config 0.3.1 neid uusi välju ei aktsepteeri.
Määrake loaderi skriptis enne selle käivitumist data-theme="light" või data-theme="dark", et valida algne palett. Seejärel ühendage saidi lüliti brauseri API-ga:
window.ChattyBox?.setTheme('light');
window.ChattyBox?.setTheme('dark');
window.ChattyBox?.setTheme(null); // Restore the configured base appearance.
Vidin uuendab olemasolevaid stiile, lähtestamata sõnumeid, allikaid, mustandteksti ega ootel päringut. Teema valimine ei muuda vidina lubatust ega eemalda ChattyBoxi brändingut. Eelistuse salvestamise ja operatsioonisüsteemi teema järgimise eest vastutab teie sait; vidin valib ainult seadistatud paleti.
Kohandatud integratsioonid
Kas vajate hostitud vidinast kohandatumat lahendust? Looge oma kasutajaliides JavaScripti SDK abil või kirjutage arhitektuurialase abi saamiseks aadressil support@chattybox.ai.
Mitmekeelne tugi
Praeguse lähtekoodi ChattyBoxi vidin määrab kasutajaliidese lokaadi projekti fikseeritud või automaatrežiimi põhjal. See jälgib <html lang>-i ja loaderi skripti data-locale-i muutusi ning uuendab silte olemasolevas vidinas, lähtestamata vestlust, mustandteksti ega ootel korduskatset. Navigeerimine üksi keelt ei muuda; vajaduse korral uuendage üht neist atribuutidest. Juhtpaneeli seadete muudatused nõuavad vidina uuesti algkäivitamist. Ärge eeldage, et teie keskkonnas kasutatav loader seda tuge pakub.
Ametlikult toetatud keeled
Vidinal on 14 keele tõlkekataloogid. Kõik praegused kataloogid kasutavad vasakult paremale paigutust. Kasutajaliidese kataloogid ei tõlgi projekti autori kirjutatud teksti ega AI loodud vastuseid.
| Keel | Kood |
|---|---|
| Inglise | en |
| Prantsuse | fr |
| Saksa | de |
| Hispaania | es |
| Itaalia | it |
| Hollandi | nl |
| Portugali | pt |
| Poola | pl |
| Rootsi | sv |
| Indoneesia | id |
| Eesti | et |
| Soome | fi |
| Kõmri | cy |
| Tšehhi | cs |
:::note Kasutajaliidese keel ja vastused Praeguse lähtekoodi hostitud loader saadab vestluspäringutega kaasa tuvastatud kasutajaliidese lokaadi. Taustsüsteem tuvastab küsimuse keele ning proovib kasutada keeleteadlikku otsingut ja genereerimist. Toote enda varusõnumite puhul on tuvastatud küsimuse keele signaal kasutajaliidese lokaadist olulisem; kui tuvastus pole kindel või tugineb ainult ASCII-tähtedel põhinevale inglise keele heuristikale, võib kasutajaliidese lokaal määrata varusõnumi keele. Projekti enda kirjutatud varusõnumit kuvatakse muutmata kujul; lokaal ei tõlgi seda ega muuda AI loodud vastust. Vastuste keel ja kvaliteet sõltuvad indekseeritud sisust ja seadistatud mudelist; kasutajaliidese kataloog ei taga vastuse kvaliteeti. :::
Kuidas keele tuvastamine töötab
Vidin kasutab ahelas toimivat tuvastussüsteemi:
- Lubatud skripti ülekirjutus - Toetatud
data-localevõidab, kuiallowLocaleOverrideei olefalse— ka fikseeritud režiimis. - Fikseeritud režiim - Kui lubatud ülekirjutust pole, kasutatakse
defaultLocale-i ja lehe või brauseri keelt eiratakse. - Automaatne režiim - Proovitakse järjest lehe
<html lang>-i,navigator.language-it, kõikinavigator.languages-i väärtusi, pärandväärtustuserLanguagening seejäreldefaultLocale-i; valitakse esimene toetatud keel. - Normaliseerimine - Suur- ja väiketähti ei eristata ning toetatud piirkondlikud väärtused, näiteks
fr-CA, teisendatakse toetatud põhikeeleks. Toetamata kandidaadid jäetakse vahele; kui ükski kandidaat ei sobi, kasutatakse inglise keelt.
Praeguse lähtekoodi hostitud loaderis kuvatakse projekti kohandatud päisepealkiri ja tervitussõnum muutmata kujul; vaikepealkiri ja tervitussõnum kasutavad lokaliseeritud silte. Kui tõlgete laadimine ebaõnnestub, jäävad kasutusele sisseehitatud ingliskeelsed sildid. Enne sellele käitumisele tuginemist kontrollige oma keskkonna loaderi versiooni.
Keele käsitsi ülekirjutamine
Konkreetse keele taotlemiseks sõltumata brauseri seadetest lülitage sisse Luba skripti ülekirjutus ja lisage enne loaderi käivitamist toetatud keelekoodiga atribuut 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 Kasutusjuht
See on eriti kasulik mitmekeelse veebisaidi puhul, kus igal keeleversioonil on oma URL (nt /de/, /fr/). Määrake data-locale vastavaks iga lehe keelele; praeguse lähtekoodi loader rakendab ka atribuudi hilisemad muudatused. Üksnes marsruudi muutumisest keele valimiseks ei piisa.
:::
Juhtpaneeli keeleseaded
Rakenduse juhtpaneel võimaldab projekti kaupa vidina keele-eelistusi seadistada:
- Tuvasta automaatselt - Kasutab kõigepealt lehe keelt, seejärel külastaja brauseri keelt
- Fikseeritud - Kasutab seadistatud vaikekeelt, välja arvatud juhul, kui lubatud
data-localeselle üle kirjutab - Luba skripti ülekirjutus - Lubab või keelab atribuudi
data-localeülekirjutamise
Need seaded leiate juhtpaneelist → Kohanda → Välimus → Keel. Kontrollige keele automaatse salvestamise olekut ning lahendage vead enne testimist.
Sisu keele sobitamine
Kasuliku mitmekeelse kogemuse jaoks indekseerige avalikku sisu külastajate keeltes ja kontrollige viiteid; tuvastus ega otsing ei ole garanteeritud. Selleks tehke järgmist:
- Kraapige dokumentatsiooni kõik keeleversioonid faili
sitemap.xmlabil. - Kraapija püüab lehe keelt tuvastada; kontrollige sisu ja viiteid.
- Otsing püüab eelistada küsimuse keelt, kuid võib kasutada muud indekseeritud sisu.
Seadistamine rakenduse juhtpaneelil: kasutage kraapimise seadistamisel oma sitemap.xml URL-i (nt https://yourdocs.com/sitemap.xml) keeleversioonide leidmiseks ning kontrollige seejärel indekseeritud lehti. Saidikaardid ei möödu roomamispiirangutest ega välistustest.
Tõrkeotsing
Vidin näitab endiselt inglise keelt
- Sundvärskendus diagnostikana - Laadige leht uuesti klahvidega Ctrl+F5 või Cmd+Shift+R ja kontrollige brauseri võrgupaneelil vidina- ja tõlkepäringuid
- Kontrollige
data-locale-i - Veenduge, et atribuut on õigesti määratud toetatud keelekoodile - Kontrollige projekti režiimi ja ülekirjutamise luba - Fikseeritud režiim ja keelatud ülekirjutused võivad brauseri keelt või
data-locale-i tahtlikult eirata - Kontrollige brauseri keelt - Veenduge, et brauseri eelistatud keel on õigesti seadistatud
- Kontrollige lehe HTML-i lang-atribuuti - Veenduge, et lehel on
<html lang="de">(või sobiv kood)
Allikad on vales keeles
- Kraapige sisu uuesti - Veenduge, et kõik keeleversioonid on indekseeritud
- Kasutage sitemap.xml-i - Kontrollige, et soovitud URL-id oleksid tõesti indekseeritud; roomamispiirangud ja välistused võivad need välja jätta
- Kontrollige päringu keelt - AI proovib vastuse keelt päringu keelega sobitada
Tõlked puuduvad
- Kontrollige toetatud keeli ja päringuid - Kataloogid on olemas ainult ülal loetletud 14 koodi jaoks; puuduvate võtmete korral kasutatakse sisseehitatud varusilte
Head tavad
- Määrake lehtedel
<html lang>- See aitab nii juurdepääsetavuse kui ka vidina tuvastamisega - Testige arenduse ajal
data-locale-iga - Kontrollige, et iga keel renderdub õigesti - Kraapige kõik keeleversioonid - Kasutage
sitemap.xml-i leidmiseks ja kontrollige indekseeritud lehti - Vaadake üle päris küsimused - Kontrollige vestlusi ja keelepõhiseid sisulünki; juhtpaneel ei näita praegu vidina lokaadi jaotust
UI-kataloog ei tõlgi vastuseid ega tingimata kõiki kasutajaliidese tekste.