JavaScript SDK

:::note Versiooni olek Avaldatud npm-SDK 0.1.4 valideerib baseUrl-i, mähendab loetamatud vastuse kehad ja proovib config HTTP 400 ainult ühe korra uuesti. Koos widget.js v15-ga toetavad remove()/window.ChattyBox.destroy() teardowni; headless sendMessage() ei korda automaatselt. :::

npm-pakett on ChattyBoxi integreerimiseks soovitatav viis. Importige oma rakendusse üks klient, seadistage selle avalik võti ja API URL ning laadige hallatav kasutajaliides sinna, kus rakendus seda vajab, või kasutage peata meetodeid oma komponentidega.

Kiire alustamine

bun add @openstaticfish/chattybox

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

const chattybox = new Chattybox({
  apiKey: import.meta.env.PUBLIC_CHATTYBOX_API_KEY,
  baseUrl: import.meta.env.PUBLIC_CHATTYBOX_API_URL,
});

const widget = chattybox.mountWidget();

// Hoia see laadija lehe eluea jooksul alles, ka SPA-navigeerimisel.

Kutsuge mountWidget() välja pärast document.body olemasolu, mitte renderdamise või serveripoolse käituse ajal. See lisab ujuva vidina document.body alla, mitte komponendi sisse. { locale: 'fr' } taotleb prantsuse keelt vaid algkäivitamisel ning ainult siis, kui projekt lubab skripti lokaadi override’e.

Hankige avalik konfiguratsioon

1. Looge projekt ja indekseerige oma sisu.
2. Testige juhtpaneelil tüüpilisi küsimusi.
3. Avage Public Keys ja looge brauserivõti. See toimib tootmises, eelvaadetes, testkeskkonnas ja localhostis vaikimisi.
4. Avage Embed, valige see võti ning kopeerige loodud koodilõigu juures kuvatav vidina API URL.

Avalikud vidina API-võtmed on mõeldud brauserikoodis kasutamiseks. Need tuvastavad projekti, kuid ei ole haldusmandaadid. Valikulise lisakaitse jaoks lubage jaotises Public Keys > Edit origins piirang ning lisage täpsed brauseri origin’id. Piirang võrdleb skeemi, hostinime ja porti, mitte teid ega wildcard-alamdomeene; Node’i fetch ei lisa Origin-i ega Referer-it automaatselt. Pakett on ESM-klient tänapäevastele Node.js-i ja brauserirakendustele, mis pakuvad fetch-i.

Laadige hostitud vidin koodist

Kasutage seda, kui soovite ChattyBoxi hallatavat kasutajaliidest, kuid tahate rakendusekoodist juhtida, kuhu see laaditakse:

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

const chattybox = new Chattybox({
  apiKey: import.meta.env.PUBLIC_CHATTYBOX_API_KEY,
  baseUrl: import.meta.env.PUBLIC_CHATTYBOX_API_URL,
});

const widget = chattybox.mountWidget();

// Kasutage widget.remove() ainult sihipäraseks teardown'iks või nõusoleku tagasivõtuks.

mountWidget() tagastab käepideme sünkroonselt enne skripti või UI valmisolekut. Avaldatud SDK-s 0.1.4 jagavad identsed mountid skripti ja igal käepidemel on viide: remove() on idempotentne ning ainult viimane käepide katkestab algkäivituse, korduskatsed ja käimasoleva chati, eemaldades seejärel UI, stiilid, fondilingid, skripti ja globaalse API. Erinev võti, API URL, scriptUrl, lokaat või debug-valik lükatakse tagasi, kuni käepidemeid on alles. widget.js v15-ga teeb sama teardowni window.ChattyBox.destroy(). Hoidke loader püsivas shell’is; ärge kombineerige SDK mount’i plugina, GTM-sildi ega eraldi skriptiga. Ready-promise’i, konteineri sihtmärki ega reaktiivset lokaadi-API-t ei ole.

Looge oma kasutajaliides

Kasutage allolevaid peata meetodeid, kui teie rakendus haldab sõnumiloendit, sisendit, laadimis- ja veaseisundeid, allikaviiteid ning juurdepääsetavust.

Sõnumi saatmine

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

const chattybox = new Chattybox({
  apiKey: import.meta.env.PUBLIC_CHATTYBOX_API_KEY,
  baseUrl: import.meta.env.PUBLIC_CHATTYBOX_API_URL,
});

const answer = await chattybox.sendMessage({
  message: 'How do I get started?',
});

console.log(answer.message);
console.log(answer.sources);

Seadke PUBLIC_CHATTYBOX_API_URL Embed-kaardil kuvatud täpseks vidina API URL-iks. SDK aktsepteerib nii juurutuse juur-URL-i kui ka /chat-iga lõppevat URL-i.

Vastus sisaldab järgmist:

Väli	Tüüp	Kirjeldus
message	string	Genereeritud vastus.
conversationId	string	Selle vestluse jätkamiseks kasutatav identifikaator.
sources	string[]	Vastuse jaoks hangitud allikate URL-id.

Vestluse jätkamine

Hoidke tagastatud vestluse ID-d oma kasutajaliidese olekus ja saatke see järgmise sõnumiga:

const followUp = await chattybox.sendMessage({
  message: 'Can you explain the second step?',
  conversationId: answer.conversationId,
});

Ärge kasutage sama vestluse ID-d omavahel mitteseotud külastajate puhul. Looge uus vestlus, jättes nende esimese sõnumi juures conversationId välja. ID rühmitab salvestatud sõnumeid, kuid praegune avalik genereerimistee ei saada varasemaid käike mudelile; tehke jätkuküsimus iseseisvaks.

Vigade käsitlemine

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

try {
  await chattybox.sendMessage({ message: 'Where is the API reference?' });
} catch (error) {
  if (error instanceof ChattyboxError) {
    console.error(error.status, error.code, error.message);
  }
}

ChattyboxError.status sisaldab HTTP olekut. code on olemas siis, kui API tagastab struktureeritud veakoodi.

Projekti seadete ja tõlgete taaskasutamine

SDK pakub ka meetodeid getWidgetConfig() ja getWidgetTranslations(locale). Need toetavad kliente, kes soovivad hostitud vidina projekti seadeid ja lokaliseeritud silte taasesitada:

const [config, labels] = await Promise.all([
  chattybox.getWidgetConfig(),
  chattybox.getWidgetTranslations('en'),
]);

Täielikult kohandatud kasutajaliides võib neid eirata. Hoidke iga külastaja conversationId-i tema brauseris või seansi olekus; ärge jagage kunagi üht globaalset vestluse ID-d. sendMessage() aktsepteerib ainult message, valikulist conversationId-d ja idempotencyKey-d; see ei saada lehekonteksti (sourceUrl või sourcePath), lokaati ega mudelivalikuid. Peata SDK ei paku automaatseid retry’sid, timeout’i, streaming’ut ega UI-olekut.

Järgmised sammud

• Eelistate hallatavat ehituseta kasutajaliidest? Installige widget.js.
• Kohandage hostitud kasutajaliidest jaotises Hostitud vidina kohandamine.
• Testige enne käivitamist origin’i piiranguid, varuvastuseid, allikaviiteid ja mobiilikäitumist käivituseelse kontrollnimekirja abil.