:::note Versiotila Julkaistu npm-SDK 0.1.4 ja hostattu widget.js v15 tukevat teardownia remove()- tai window.ChattyBox.destroy()-kutsulla: UI/tyylit poistetaan ja odottava alustus, uudelleenyritykset sekä chatit perutaan. v15-chat tekee enintään 10 yritystä 30 sekunnin ajoitusbudjetissa, ei kovana pyyntökohtaisena timeoutina. Headless-sendMessage() ei yritä automaattisesti uudelleen. :::

Hostatun widgetin mukauttaminen

Mukauta valmista käyttöliittymää, joka ladataan osoitteesta https://chattybox.ai/widget.js. Katso viralliset framework- ja alustakohtaiset asennusesimerkit asennusoppaista.

Ennen mukauttamista

Luo projekti, indeksoi sen sisältö ja varmista edustavat vastaukset Test Chat -toiminnolla ennen kuin käytät aikaa ulkoasuun. Katso koko järjestys kohdasta Näin pääset alkuun.

Määritä hostattu widget

1. Avaa hallintapaneeli ja valitse projektisi.
2. Siirry Embed-välilehdelle.
3. Esikatsele ja tallenna widgetin ulkoasu ja kielitoiminta.

Embed-välilehti hallitsee esitystapaa ja luo asennuskoodin, mutta julkisia avaimia hallitaan erikseen. Kun olet valmis asentamaan:

1. Avaa Public Keys ja luo selainavain.
2. Palaa Embed-välilehdelle, valitse avain ja kopioi luotu koodinpätkä. Avain toimii oletuksena tuotannossa, esikatseluissa, stagingissa ja localhostissa.
3. Ota halutessasi Public Keys > Edit origins -kohdassa käyttöön tarkka origin-rajoitus lisäsuojana.
4. Noudata alustasi koskevia asennusoppaita.

<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>

vinkki

Hallintapaneelissa tallennetut widgetin esitystavan muutokset tulevat voimaan seuraavassa widgetin alustuksessa ilman, että sivustosi koodinpätkää tarvitsee vaihtaa. Jo avoin sivu ei päivity reaaliajassa; lataa se uudelleen.

---

Visuaalinen mukauttaminen

Hallintapaneelin editorilla voit säätää tuettuja värejä, sijoittelua, kuvaketta ja tekstiä ilman sivustokoodin muokkaamista. Tarkista tulos hostatussa widgetissä: esikatselu ja loader eivät ole identtiset.

Hallintapaneelin säätimet

1. Accent Color - Valitse brändisi pääväri. Se vaikuttaa avaajaan, tärkeisiin korostuksiin ja käyttäjän viesteihin.

2. Position - Valitse, missä widget näkyy näytöllä.

3. Header Title - Määritä chat-ikkunan yläosassa näytettävä otsikko.

4. Welcome Message - Mukauta ensimmäistä viestiä, jonka kävijät näkevät avatessaan chatin.

5. ChattyBox Branding - Starter- ja sitä korkeammat paketit voivat piilottaa "Powered by ChattyBox" -alatunnisteen. Free-paketissa branding pysyy käytössä.

Editorissa on myös tausta- ja tekstivärin säätimet sekä oletusrobotti-, emoji-, kuva-URL- tai ladattu kuvake. Ladatun kuvakkeen koko saa olla enintään 512 KiB ja sen MIME-tyypin on oltava PNG, JPEG, WebP, SVG, GIF tai ICO. Editorissa tallennettava iconSize ei nykyisessä hostatussa loaderissa muuta kuvakkeen kokoa; älä odota small/medium/large-valinnan vaikuttavan.

huomautus

Tallenna muutokset ja lataa asennettu sivu uudelleen varmistaaksesi ne. Hallintapaneelin esikatselu on malli, ei hostattu widget. Config-lukitussa projektissa ulkoasu- ja locale-kentät hallitaan asetuksina koodina; käyttöoikeuden sallima branding säilyy erillisenä asetuksena.

Lisäasetukset

Hallintapaneelin asetukset ja skriptiattribuutit

Hallitse suurinta osaa widgetin toiminnasta hallintapaneelista, jotta verkkosivustoa ei tarvitse julkaista uudelleen yksinkertaisten muutosten vuoksi.

Käytä hallintapaneelia väreihin, sijaintiin, kuvakkeeseen, otsikkoon, tervetuloviestiin, oletuskieliin, julkisten avainten hallintaan, haravointiin ja Analyticsiin.

Jos projektisi käyttää julkisen avaimen origin-rajoituksia, pidä rajoitukset synkronoituna widgetin asennusverkkotunnusten kanssa.

Käytä skriptiattribuutteja vain arvoille, joita widget tarvitsee sivun latautuessa:

• data-api-key tunnistaa julkisen widget-avaimen.
• data-api-url kertoo widgetille, minne pyynnöt lähetetään. Tuotannossa se on hallintapaneelista saatava vakaa https://...convex.site/chat-URL.
• data-locale pyytää tiettyä widgetin käyttöliittymäkieltä alustuksessa vain, jos projekti sallii skriptiohjauksen.

Jos widget ei näy asennuksen jälkeen, katso vianmääritys.

Alustakohtaisia esimerkkejä saat aloittamalla Docusaurus-, MkDocs-, VitePress-, WordPress- tai GitBook-oppaasta.

Widgetin piilottaminen tietyillä sivuilla

Jos sinun on piilotettava widget valituilla sivuilla, voit tehdä sen CSS:llä:

.chattybox-widget {
  display: none;
}

CSS-piilotus ei estä alustusta, API-pyyntöjä tai virheraportointia eikä ole suostumus- tai yksityisyydenhallinta. Estä lataus jättämällä scripti pois kyseisiltä sivupyynnöiltä. Asiakaspuolen reittisiirtymiä tai suostumuksen peruutusta varten hostattu widget.js v15 tarjoaa window.ChattyBox.destroy()-kutsun ja julkaistu SDK 0.1.4 käyttää remove()-kutsua samaan teardowniin.

Mukautetut integraatiot

Tarvitsetko hostattua widgetiä räätälöidymmän toteutuksen? Rakenna oma käyttöliittymä JavaScript SDK:lla tai pyydä arkkitehtuurineuvoja osoitteesta support@chattybox.ai.

Monikielinen tuki

ChattyBox-widget ratkaisee käyttöliittymän lokaalin alustuksessa projektin Fixed- tai Auto-tilan mukaan; se ei seuraa myöhempiä attribuutti- tai asiakaspuolen reittimuutoksia.

Virallisesti tuetut kielet

Widgetillä on käännösluettelot 14 kielelle. Luettelo ei tarkoita, että kaikki näkyvät tai saavutettavat merkkijonot ovat käännettyjä, eikä se takaa vastausten laatua.

Kieli	Koodi
Englanti	en
Ranska	fr
Saksa	de
Espanja	es
Italia	it
Hollanti	nl
Portugali	pt
Puola	pl
Ruotsi	sv
Indonesia	id
Viro	et
Suomi	fi
Kymri	cy
Tšekki	cs

:::note Käyttöliittymän kieli ja vastaukset Käyttöliittymän lokaalia ei lähetetä chatin kieliparametrina. Taustajärjestelmä tunnistaa kysymyksen kielen ja yrittää kielitietoista hakua ja generointia; vastausten kieli ja laatu riippuvat indeksoidusta sisällöstä ja mallista. :::

Näin kielen tunnistus toimii

Widget käyttää ketjutettua tunnistusjärjestelmää:

1. Sallittu skriptiohitus - Ei-tyhjä data-locale voittaa vain, kun allowLocaleOverride ei ole false, myös Fixed-tilassa.
2. Fixed-tila - Ilman sallittua ohitusta käytetään defaultLocale-arvoa.
3. Auto-tila - Käytetään ensimmäistä ei-tyhjää arvoa: sivun <html lang>, selaimen navigator.language (tai vanha userLanguage) ja lopuksi defaultLocale.
4. Normalisointi - Tuettu alueellinen arvo, kuten fr-CA, supistetaan peruskoodiksi; tukematon arvo muuttuu heti englanniksi kokeilematta seuraavaa ehdokasta.

Kielen manuaalinen ohitus

Jos haluat pyytää tiettyä kieltä selaimen asetuksista riippumatta, ota käyttöön Allow Script Override ja lisää data-locale-attribuutti ennen loaderin käynnistymistä:

<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 Käyttötapaus Tämä on erityisen hyödyllistä monikielisillä sivustoilla, joissa jokaisella kieliversiolla on oma URL (esim. /de/, /fr/). Aseta data-locale vastaamaan kunkin sivun kieltä ja tarkista renderöity käyttöliittymä. :::

Hallintapaneelin kieliasetukset

Sovelluksen hallintapaneelissa voit määrittää widgetin kieliasetukset projektikohtaisesti:

• Auto-detect - Käyttää sivun kieltä ennen kävijän selaimen kieltä
• Fixed Language - Käyttää määritettyä oletuskieltä, ellei sallittu data-locale ohita sitä
• Allow Script Override - Ottaa data-locale-attribuutin ohituksen käyttöön tai pois käytöstä

Löydät nämä asetukset hallintapaneelista → Project → Embed-välilehti → Widget Language -osio.

Sisällön kielen yhteensovitus

Hyödyllistä monikielistä kokemusta varten indeksoi julkista sisältöä kävijöidesi kielillä ja testaa lähteet; tunnistus ja haku eivät ole taattuja. Toimi näin:

1. Haravoi dokumentaation kaikki kieliversiot sitemap.xml-tiedoston avulla.
2. Haravointiohjelma yrittää tunnistaa sivun kielen; tarkista sisältö ja lähteet.
3. Haku yrittää suosia kysymyksen kieltä, mutta voi käyttää muuta indeksoitua sisältöä.

Käyttöönotto sovelluksen hallintapaneelissa: käytä haravointia määrittäessäsi sitemap.xml-URL-osoitetta (esim. https://yourdocs.com/sitemap.xml) kieliversioiden löytämiseen ja tarkista sitten indeksoidut sivut. Sivustokartat eivät ohita haravointirajoja tai poissulkuja.

Vianmääritys

Widget näkyy edelleen englanniksi

• Pakota päivitys diagnostiikkaa varten - Lataa sivu uudelleen näppäinyhdistelmällä Ctrl+F5 tai Cmd+Shift+R ja tarkista widget- ja käännöspyynnöt selaimen verkkopaneelista
• Tarkista data-locale - Varmista, että attribuutti on asetettu oikein tuettuun kielikoodiin
• Varmista selaimen kieli - Tarkista, että selaimen ensisijainen kieli on asetettu oikein
• Tarkista sivun HTML lang - Varmista, että sivulla on <html lang="de"> (tai oikea koodi)

Lähteet ovat väärällä kielellä

• Haravoi sisältö uudelleen - Varmista, että kaikki kieliversiot on indeksoitu
• Käytä sitemap.xml-tiedostoa - Varmista, että halutut URL-osoitteet todella indeksoitiin; haravointirajat ja poissulut voivat jättää niitä pois
• Tarkista kyselyn kieli - AI pyrkii vastaamaan kyselyn kielellä

Käännöksiä puuttuu

• Tarkista tuetut kielet - Vain yllä olevilla 14 koodilla on luettelot; puuttuvat tunnisteet voivat käyttää englanninkielistä varavaihtoehtoa

Parhaat käytännöt

1. Aseta sivuille <html lang> - Se auttaa saavutettavuudessa ja widgetin tunnistuksessa
2. Testaa data-locale-attribuutilla kehityksen aikana - Varmista, että jokainen kieli näkyy oikein
3. Haravoi kaikki kieliversiot - Käytä sitemap.xml-tiedostoa löytämiseen ja tarkista indeksoidut sivut
4. Tarkista aidot kysymykset - Tarkastele keskusteluja ja kielikohtaisia sisältöaukkoja; hallintapaneeli ei tällä hetkellä näytä widgetin kielialuejakaumaa