JavaScript SDK

:::note Versiotila Julkaistu npm-SDK 0.1.4 validoi baseUrl-arvon, kapseloi lukukelvottomat vastausrungot ja yrittää config-HTTP-400:n uudelleen vain kerran. widget.js v15:n kanssa remove()/window.ChattyBox.destroy() tukee teardownia; headless-sendMessage() ei yritä automaattisesti uudelleen. :::

npm-paketti on suositeltu tapa integroida ChattyBox. Tuo yksi asiakas sovellukseesi, määritä sen julkinen avain ja API-URL ja liitä ylläpidetty käyttöliittymä siihen, missä sovelluksesi tarvitsee sitä, tai käytä headless-metodeja omien komponenttiesi kanssa.

Pika-aloitus

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,
});

chattybox.mountWidget();

// Pidä loader sivun elinkaaren ajan myös SPA-navigoinnissa.

Kutsu mountWidget() vasta kun document.body on olemassa, ei renderöinnin tai palvelinsuorituksen aikana. Se lisää kelluvan widgetin document.body-alle; { locale: 'fr' } pyytää kieltä vain alustuksessa, jos projekti sallii script-overriden.

Hanki julkinen määritys

1. Luo projekti ja indeksoi sisältösi.
2. Testaa edustavia kysymyksiä hallintapaneelissa.
3. Avaa Public Keys ja luo selainavain. Se toimii oletuksena production-, preview-, staging- ja localhost-origineista.
4. Avaa Embed, valitse kyseinen avain ja kopioi luodun koodinpätkän yhteydessä näkyvä widgetin API-URL.

Julkiset widgetin API-avaimet on tarkoitettu näkymään selainkoodissa. Ne tunnistavat projektin, mutta eivät ole hallintatunnuksia. Origin-rajoitus on vapaaehtoinen lisäsuoja ja täsmää tarkasti schemeen, hostiin ja porttiin; se ei ole autentikointia. Rajoitettu avain tarkistaa pyynnön Origin-otsakkeen tai Referer-otsakkeen originin, joten Node.js:n fetch ei lähetä näitä selaimen otsakkeita automaattisesti. Paketti on ESM-asiakas nykyaikaisille Node.js- ja selainohjelmille, jotka tarjoavat fetch-funktion.

Liitä hostattu widget koodista

Käytä tätä, kun haluat ChattyBoxin ylläpidetyn käyttöliittymän mutta haluat hallita sen liittämispaikkaa sovelluskoodista:

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,
});

chattybox.mountWidget({ locale: 'fr', debug: false });

mountWidget() palauttaa kahvan ennen kuin script tai UI on valmis. Julkaistussa SDK:ssa 0.1.4 identtiset mountit jakavat scriptin ja jokaisella kahvalla on viite: remove() on idempotentti ja vasta viimeinen kahva keskeyttää alustuksen, uudelleenyritykset ja käynnissä olevan chatin sekä poistaa sitten UI:n, tyylit, fonttilinkit, scriptin ja globaalin API:n. Eri avain, API-URL, scriptUrl, locale tai debug-valinta hylätään niin kauan kuin kahvoja on. widget.js v15:n kanssa window.ChattyBox.destroy() tekee saman teardownin. Ready-promisea, konttikohdetta tai reaktiivista locale-päivitystä ei ole.

Rakenna oma käyttöliittymä

Käytä alla olevia headless-metodeja, kun sovelluksesi hallitsee viestiluetteloa, syötettä, lataus- ja virhetiloja, lähdeviitteitä ja saavutettavuutta.

Lähetä viesti

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

Aseta PUBLIC_CHATTYBOX_API_URL täsmälleen Embed-välilehdellä näkyväksi widgetin API-URL:ksi. SDK hyväksyy sekä käyttöönoton juuriosoitteen että /chat-päätteisen URL:n.

Vastaus sisältää:

Kenttä	Tyyppi	Kuvaus
message	string	Luotu vastaus tai määritetty varavastaus.
conversationId	string	Tämän keskustelun jatkamiseen käytettävä tunniste.
sources	string[]	Vastaukseen haettujen lähteiden URL-osoitteet; varavastauksella ne voivat olla tyhjät.

Jatka keskustelua

Pidä palautettu keskustelun tunniste käyttöliittymäsi tilassa ja lähetä se seuraavan viestin mukana:

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

Älä käytä samaa keskustelun tunnistetta toisiinsa liittymättömillä kävijöillä. Luo uusi keskustelu jättämällä conversationId pois heidän ensimmäisestä viestistään. Tunniste ryhmittelee tallennetut viestit, mutta nykyinen julkinen generointipolku ei välitä aiempia vuoroja mallille; tee jatkokysymyksestä omavarainen.

Käsittele virheet

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 sisältää HTTP-tilakoodin. code on mukana, kun API palauttaa rakenteisen virhekoodin.

Käytä projektin asetuksia ja käännöksiä uudelleen

SDK tarjoaa myös metodit getWidgetConfig() ja getWidgetTranslations(locale). Niiden avulla asiakkaat voivat toisintaa hostatun widgetin projektiasetukset ja lokalisoidut tunnisteet:

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

Täysin mukautettu käyttöliittymä voi jättää ne huomiotta. Säilytä kunkin kävijän conversationId hänen selaimensa tai istuntonsa tilassa; älä koskaan jaa yhtä yleistä keskustelun tunnistetta. sendMessage() hyväksyy vain message-, conversationId- ja idempotencyKey-arvot: se ei lähetä sivukontekstia (sourceUrl tai sourcePath), localea eikä malliasetuksia. Vahvista ennen lähetystä enintään 2 000 merkin ei-tyhjä viesti ja käytä yhtä yksilöllistä idempotenssiavainta loogista viestiä kohden.

Seuraavat vaiheet

• Haluatko mieluummin ylläpidetyn käyttöliittymän ilman build-vaihetta? Asenna widget.js.
• Mukauta hostattua käyttöliittymää kohdassa Hostatun widgetin mukauttaminen.
• Testaa ennen julkaisua origin-rajoitukset, varavastaukset, lähdeviitteet ja mobiilikäyttäytyminen julkaisun tarkistuslistan avulla.