Liigu põhisisu juurde

:::note Versiooni olek Avaldatud npm-SDK ja majutatud widget.js on versioonitud eraldi: avaldatud SDK versioon on 0.1.4, majutatud vidina praegune lähtekood aga v16. remove() eeldab teardowni toetavat loaderit — kontrollige juurutatud versiooni, eriti isemajutuse korral. SDK-l 0.1.4 puudub reaktiivne locale’i muutmise API; majutatud v16 praegune lähtekood võib tuvastatud locale’i muutumisel toote enda silte värskendada, järgides projekti poliitikat. Peata sendMessage() ei korda päringut automaatselt. Ajalooline majutatud v15 võib kavandada kuni 10 vestluspäringu katset 30-sekundilise korduskatsete akna jooksul; see pole juba käimasoleva päringu range ajalimiit. :::

Integreerimine AI-koodiassistendiga

Soovitatav integratsioon on @openstaticfish/chattybox npm-pakett. Selle abil saab rakendusekood seadistada avaliku võtme ja API URL-i, laadida püsivast brauseripoolsest paigutusest ChattyBoxi hallatava hõljuva vidina või kasutada täielikult kohandatud kasutajaliidese jaoks peata klienti.

Eraldiseisev widget.js-skript on dokumenteeritud viimasena ehituseta varuvariandina saitidele, kuhu ei saa npm-pakette installida.

Enne alustamist​

Seadistage vestlusrobot enne, kui palute assistendil oma rakendust muuta:

  • Kontrollige jaotises Testi vestlusrobotit tüüpilisi vastuseid ja allikaviiteid.
  • Jaotises Paigalda → Võtmed ja domeenid kontrollige või looge avalik brauserivõti ja selle origin’i seadeid. Veebisaidi jaoks ette valmistatud võti võib olla juba piiratud; piirangud on valikuline lisakaitse, mitte külastajate autentimine.
  • Jaotises Paigalda → Veebisaidi paigaldamine valige sobiv võti ja kopeerige loodud koodilõik. Kui see sisaldab data-api-url-i, kasutage seda; vastasel korral hankige enne integreerimist juurutuse konfiguratsioonist õige vidina HTTP-lõpp-punkt.
  • Otsustage, kas rakendusele sobib püsivalt hõljuv vidin või vajate kohandatud kasutajaliidest, mille paigutus ja teardown on marsruudipõhised.

Need on avalikud brauserimandaadid, kuid vältige siiski keskkonnaspetsiifiliste väärtuste commit’imist. Ärge andke kunagi kaasa konfiguratsiooni juurutustokenit, administraatori mandaati ega muud keskkonnafaili.

Soovitus: laadige hallatav kasutajaliides npm-ist​

See on Reacti, Next.js-i, Vite’i ja teiste paketipõhiste brauserirakenduste vaikeprompt.

Juhis
Integreeri ChattyBoxi npm-pakett

Integreeri ChattyBox sellesse rakendusse, kasutades @openstaticfish/chattybox npm-paketti.

Avalik brauserikonfiguratsioon:
- API-võti: [PASTE PUBLIC WIDGET KEY]
- API URL: [PASTE WIDGET API URL]

Vidina võti on avalik ja võib sisalduda brauserikoodis; see pole saladus ega külastajate autentimise vahend. Origin’i piirangud on valikuline lisakaitse, mitte autentimine. Veebisaidi jaoks ette valmistatud võti võib olla juba piiratud: kontrolli selle seadeid ning luba piirangu korral kõik nõutud tootmise, eelvaate, testkeskkonna ja localhost’i origin’id (täpne skeem, host ja port). Ära küsi kunagi konfiguratsiooni juurutustokenit, administraatori mandaate ega muid saladusi ega lisa neid brauserikoodi.

Kasuta võtme, origin’i seadete ja loodud koodilõigu kontrollimiseks armatuurlaua praeguseid jaotisi **Testi vestlusrobotit**, **Paigalda → Võtmed ja domeenid** ja **Paigalda → Veebisaidi paigaldamine** ning veendu, et need käivad õige vestlusroboti kohta.

Uuri esmalt raamistikku, marsruutimismudelit, paketihaldurit, keskkonnamuutujate tavasid ja rakenduse püsivat paigutust. Ütle mulle enne muutmist, milliseid faile kavatsed muuta. Küsi minult, kui marsruudid, kus ChattyBox peaks ilmuma, on ebaselged.

Nõuded:
1. Installi @openstaticfish/chattybox selle paketihalduriga, mida see repositoorium juba kasutab.
2. Salvesta avalik API-võti ja API URL raamistiku brauserile eksponeeritud keskkonnamuutujate tava kasutades. Lisa näidiskeskkonnafaili kohatäitjate nimed, kuid ära commit’i tegelikke väärtusi.
3. Impordi Chattybox paketist @openstaticfish/chattybox ja loo üks klient apiKey ja baseUrl-iga.
4. Kutsu client.mountWidget() välja ainult brauserikoodis pärast seda, kui `document.body` on olemas, ja püsivast rakenduse kestast. Ujuv vidin lisatakse `document.body` alla, mitte komponendi sisse.
5. Hoia laadija lubatud SPA-navigeerimise ajal alles. SDK `0.1.4` loendab viiteid ainult identsete mount-valikute puhul; sihipärase teardown’i korral kutsu `remove()` välja iga tagastatud käepideme puhul. Majutatud `widget.js` v15 korral eemaldab viimane käepide vidina enda UI ja stiilid ning tühistab ootel algkäivituse, korduskatsed ja käimasoleva vestluspäringu; `window.ChattyBox.destroy()` on majutatud vidina vastav meetod. Kontrolli, kas juurutatud loader toetab teardown’i. Ära laadi vidinat enne nõutud nõusolekut ega tundlikel/privaatsetel marsruutidel; tee teardown SPA-marsruudi välistamisel või nõusoleku tagasivõtmisel. Ainult UI peitmisest või skriptisildi eemaldamisest ei piisa. Teardown ei saa tagasi võtta päringut, mille server on juba töödelnud.
6. Ära lisa widget.js-i käsitsi, loo backend-proksit ega teist loaderit. SDK lükkab muudetud võtme, API URL-i, skripti URL-i, locale’i või debug-valikud tagasi, kuni kõik olemasolevad vastavad käepidemed on eemaldatud; vanu valikuid ei säilitata kunagi vaikselt.
7. Säilita olemasolev navigeerimine, renderduse piirid, lokaliseerimine, analüütika, nõusolekud ja stiilid. SDK locale’i valik järgib projekti skripti ülekirjutamise poliitikat; SDK-l `0.1.4` puudub reaktiivne locale’i värskendamise API ja ready-promise. Majutatud `widget.js` v16 praegune lähtekood võib tuvastatud locale’i muutumisel toote enda silte värskendada; enne sellele eraldi versiooniga seotud käitumisele tuginemist kontrolli juurutatud loaderit. Majutatud v15 kavandab kuni 10 vestluspäringu katset 30-sekundilise korduskatsete akna jooksul, mitte ei määra juba käimasolevale päringule ranget ajalimiiti; peata sendMessage() ei korda päringut automaatselt. SDK `0.1.4` valideerib baseUrl-i ja pakib vastuse sisu lugemise vead ümber.
8. Tee väikseim sihipärane muudatus ja ära juuruta seda.
9. Käivita repositooriumi build, lint, tüübikontroll ja asjakohased testid.
10. Teata muudetud failid, seadistatavad keskkonnamuutujad, kasutajaliidese laadimiskoht ja viis, kuidas seda juurutatud saidil testida.

Järgnev kood on brauseri elutsükli callback’i näide, mitte serveripoolse renderduse ajal tipptasemel tehtav kutse. Kutsu seda alles pärast `document.body` olemasolu ja hoia sihipärase teardown’i jaoks käepidet alles:

import { Chattybox } from '@openstaticfish/chattybox';

const client = new Chattybox({
  apiKey: PUBLIC_CHATTYBOX_API_KEY,
  baseUrl: PUBLIC_CHATTYBOX_API_URL,
});

function mountInBrowserLifecycle() {
  if (typeof window === 'undefined' || typeof document === 'undefined' || !document.body) return null;
  return client.mountWidget();
}

// Kutsu lubatud brauseri elutsüklis ja hoia tagastatud käepide alles.

Looge kohandatud kasutajaliides​

Valige see, kui teie rakendus peab hallatava kasutajaliidese laadimise asemel ise haldama sõnumiloendit, sisendit, laadimisolekuid, vigu, allikaviiteid ja paigutust.

Juhis
Loo peata ChattyBoxi kasutajaliides

Loo kohandatud vestlusroboti kasutajaliides, kasutades @openstaticfish/chattybox npm-paketti ja selle peata klienti.

Avalik brauserikonfiguratsioon:
- API-võti: [PASTE PUBLIC WIDGET KEY]
- API URL: [PASTE WIDGET API URL]

Vidina võti on avalik; origin’i piirangud on valikuline lisakaitse, mitte külastajate autentimine. Veebisaidi jaoks ette valmistatud võti võib olla juba piiratud — kontrolli selle seadeid jaotises **Paigalda → Võtmed ja domeenid**. Loodud koodilõigu ja API URL-i leiad jaotisest **Paigalda → Veebisaidi paigaldamine**.

Uuri esmalt rakenduse raamistikku, komponendisüsteemi, olekumustreid, stiile, juurdepääsetavuse tavasid ja testiseadistust. Paku komponendipiirid ja failid välja enne muutmist.

Nõuded:
1. Installi @openstaticfish/chattybox repositooriumi olemasoleva paketihalduriga.
2. Seadista üks Chattyboxi klient apiKey ja baseUrl-iga, kasutades brauserile eksponeeritud keskkonnamuutujaid; ära commit’i tegelikke väärtusi.
3. Kasuta sendMessage() ja hoia conversationId sõnumite rühmitamiseks külastaja- või seansipõhises olekus; lähtesta see kasutaja või seansi muutumisel. Ära jaga seda kunagi omavahel mitteseotud külastajate vahel. Sama ID korral saab mudel kuni 12 viimast salvestatud sõnumit, igaüks kärbitud 2 000 tähemärgini — mitte kogu vestlust ega püsivat mälu. Avalik võti, origin’i piirangud ega conversationId ei autendi külastajaid ega kaitse privaatseid vestlusi. Ära saada tundlikke andmeid: sõnumeid võidakse salvestada ja need võivad olla projekti omanikele nähtavad; kohaliku oleku tühjendamine ei kustuta serverikirjeid.
4. Renderda vastused turvaliselt teksti või puhastatud Markdownina. Renderda HTTP(S)-allikad järjestust säilitavate ligipääsetavate linkidena. Ära lisa kunagi usaldamata toorest HTML-i ega ohtlikke lingiskeeme.
5. Rakenda ootel-, tühja- ja veaolek ning korduskatse. Varuvastusel võivad olla tühjad sources-väljad; üldist wasAnswered-lippu pole. Kui backend tagastab providerError-i, kitsenda seda turvaliselt valikulise väljana ja näita tavalise vastuse asemel üldist teenusepakkuja tõrget; ära korda pimesi lõpetatud võtmega päringut. Avaldatud SDK 0.1.4 ei pruugi praeguse lähtekoodi vastusevälju tüübistada, seega arvesta nende puudumisega. Käsitle nii ChattyboxError-it kui ka pakkimata võrguvigu; code on valikuline.
6. Lükka tagasi tühjad sõnumid ja sõnumid, mille kärbitud pikkus ületab 2 000 tähemärki; väldi topeltesitamist ning hoia klaviatuuri ja ekraanilugeja kasutuskogemus toimivana. Peata sendMessage() ei korda päringut automaatselt: kasuta iga loogilise sõnumi jaoks üht unikaalset idempotencyKey’d ning kordamisel täpselt sama sisendit. Ära korda pimesi iga 409-vastust. SDK 0.1.4 kordab getWidgetConfig() päringut HTTP 400 järel ainult ühe korra; majutatud v15 kordab eraldi käivituse GET-päringuid.
7. Laadi kasutajaliides ainult minu määratud marsruutidel või paigutuses.
8. Järgi olemasolevaid komponente ja stiile, selle asemel et lisada uus disainisüsteem.
9. Ära laadi widget.js-i ega kutsu mountWidget().
10. Käivita build, lint, tüübikontroll ja asjakohased testid, seejärel teata muudetud failid ja kontrolliplaan.

Märkused raamistike kohta​

Lisage assistendile vajaduse korral üks täiendav lause:

  • Next.js App Router: „Kasuta püsivas paigutuses väikest Client Component’i ja kutsu mountWidget() välja ainult brauseri effect’ist, mitte renderdamisel.“
  • React SPA: „Laadi püsivast rakenduse kestast. Kui komponent omab viimast SDK 0.1.4 käepidet, tagasta sihipärase teardown’i jaoks remove(); vastasel korral hoia jagatud loaderit marsruudivahetuste ajal alles.“
  • Docusaurus: „Algväärtusta brauserikoodist src/theme/Root-is ja hoia loader lubatud dokumentatsioonis navigeerimise ajal alles. Enne kliendipoolsetele keelemuutustele tuginemist kontrolli juurutatud majutatud loaderi versiooni ja locale’i käitumist; armatuurlaua seadistuse muutmine nõuab endiselt uut algkäivitust.“
  • Vue, Nuxt, Svelte või muu raamistik: „Kasutage püsivas paigutuses ainult kliendipoolset mount-lifecycle’it; täieliku teardown’i vajadusel valige peata liides.“

Vaadake olemasolev SDK-integratsioon üle​

Juhis
Vaata minu ChattyBoxi SDK-integratsioon üle

Vaata see ChattyBoxi integratsioon üle ilma juurutamata ja sõltumatut koodi muutmata.

Kontrolli, et:
1. @openstaticfish/chattybox on installitud ja imporditud, mitte selle käitumist dubleerivalt uuesti loodud.
2. Üks Chattyboxi klient saab soovitud avaliku API-võtme ja API URL-i.
3. Brauseri keskkonnamuutujad järgivad selle raamistiku avalike muutujate nimekonventsioone ega paljasta privaatseid mandaate.
4. Majutatud vidin kasutab püsivat kesta ja remove()-i kasutatakse ainult UI sihipäraseks teardown’iks, SPA-navigeerimise järel marsruudilt eemaldamiseks või nõusoleku tagasivõtmisel. Kohandatud liidesel on päris komponendi puhastus.
5. Kliendipoolne navigeerimine ja arendusaegne uuesti ühendamine ei loo duplikaatinstantsse.
6. Olemasolevad renderduspiirid, lokaliseerimine, analüütika, nõusolekud, juurdepääsetavus ja paigutus jäävad alles. Origin’i piirangud on valikulised, mitte külastaja autentimine; veebisaidi jaoks ette valmistatud võti võib olla juba piiratud. Piiratud võti vajab lubatud päringu origin’i ja Node’i fetch ei lisa brauseri päiseid automaatselt. Kontrolli, et privaatsed marsruudid on välistatud ja nõusoleku tagasivõtmisel tehakse initsialiseeritud vidinale aktiivselt teardown, mitte ei peideta seda lihtsalt ära.
7. Implementatsioonil on sobivad testid ja see ei sisalda sõltumatut refaktoreerimist.

Tagasta leiud raskusastme järgi koos failiteede ja reaviidetega. Paku ainult väikseimaid ohutuid parandusi ja anna täpsed kontrollikäsud.

Pole npm-i ega build-etappi?​

Kasutage juhendit widget.js installimiseks ainult siis, kui sait ei saa npm-pakette kasutada — näiteks tavalise HTML-i, CMS-i kohandatud koodi välja või Google Tag Manageri puhul.

Juhis
Installi varuvidina skript

Installi sellele saidile hostitud ChattyBoxi vidin, kasutades täpselt seda skripti, mille minu ChattyBoxi vaade „Veebisaidi paigaldamine“ genereeris:

[PASTE COMPLETE WIDGET SCRIPT]

Uuri esmalt saiti ja tuvasta kõige turvalisem sisestuskoht avalikel lehtedel. Laadi muutmata skript täpselt üks kord ja alles pärast nõutud nõusoleku saamist; välista privaatsed, administraatori ja checkout’i marsruudid. SPA-marsruudi muutumisel või nõusoleku tagasivõtmisel tee juba käivitatud vidinale teardown enne välistatud olekusse sisenemist ning algkäivita see uuesti ainult siis, kui see on lubatud. Kontrolli, kas juurutatud loader toetab teardown’i; ainult UI peitmisest või skriptisildi eemaldamisest ei piisa ning teardown ei saa tagasi võtta juba töödeldud päringuid. Säilita CSP-käitumine, ära avalda privaatseid mandaate ega konfiguratsiooni juurutustokenit, ära juuruta muudatust ning teata muudetud kohast koos brauseritestimise plaaniga.

Testige tulemust​

  1. Vaadake diff üle ja kinnitage, et tegelikke mandaate ei commit’itud.
  2. Käivitage projekti tavaline build, lint, tüübikontroll ja testid.
  3. Juurutage tavapärase ülevaatusprotsessi kaudu.
  4. Kontrollige soovitud marsruute privaatses brauseriaknas, sealhulgas kliendipoolset navigeerimist.
  5. Esitage toetatud küsimus, avage allikaviide ja testige varukäitumist.
  6. Kontrollige mobiilipaigutust, klaviatuuri kasutamist ja brauserikonsooli.

Jätkake SDK viitega ja käivituseelse kontrollnimekirjaga.