SDK JavaScript

:::note Statws fersiwn Mae'r SDK npm 0.1.4 cyhoeddedig yn dilysu baseUrl, yn amlapio corff ymateb na ellir ei ddarllen, ac yn ailgeisio config HTTP 400 unwaith yn unig. Gyda widget.js v15 mae teardown remove()/window.ChattyBox.destroy() ar gael; nid yw headless sendMessage() yn ailgeisio’n awtomatig. :::

Y pecyn npm yw’r ffordd a argymhellir i integreiddio ChattyBox. Ffurfweddwch un cleient a llwythwch y widget arnofiol a gynhelir o gynllun porwr parhaus, neu defnyddiwch y dulliau di-ben gyda’ch cydrannau eich hun.

Cychwyn Cyflym

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

// Cadwch y loader am oes y dudalen, gan gynnwys llywio SPA.

Galwch mountWidget() ar ôl i document.body fodoli, nid wrth rendro nac SSR. Caiff y widget ei ychwanegu o dan document.body, nid yn eich cydran; dim ond wrth gychwyn ac os caniateir diystyru sgript y mae { locale: 'fr' } yn gweithio.

Cael Eich Ffurfweddiad Cyhoeddus

1. Crëwch brosiect a mynegeiwch eich cynnwys.
2. Profwch gwestiynau cynrychioliadol yn y dangosfwrdd.
3. Agorwch Public Keys a chrewch allwedd porwr. Mae cyfyngu tarddiadau union yn ddewisol.
4. Agorwch Embed, dewiswch yr allwedd honno, a chopïwch URL API y widget a ddangosir gyda’r pyt a gynhyrchir.

Mae allweddi API widget cyhoeddus wedi’u cynllunio i ymddangos mewn cod porwr. Maent yn nodi prosiect ond nid ydynt yn fanylion rheoli. Mae cyfyngiadau tarddiad union yn ddewisol; maent yn paru cynllun, enw gwesteiwr a phorth, nid llwybrau nac wildcard subdomains. Mae’r pecyn yn gleient ESM ar gyfer rhaglenni Node.js cyfredol a phorwyr sy’n darparu fetch.

Atodi’r Widget Lletyol o’r Cod

Defnyddiwch hwn pan fyddwch eisiau rhyngwyneb ChattyBox a gynhelir, gan reoli o god eich rhaglen ble mae’n cael ei atodi:

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

// Defnyddiwch widget.remove() ar gyfer teardown bwriadol.

Mae mountWidget(options?) yn dychwelyd handlen yn syth, cyn i'r sgript lwytho neu i'r UI fod yn barod. Yn SDK cyhoeddedig 0.1.4, mae mountiau unfath yn rhannu'r sgript ac mae gan bob handlen gyfeiriad: mae remove() yn idempotent, a dim ond yr handlen olaf sy'n canslo cychwyn, ailgeisiadau a chat sy'n rhedeg, wedyn yn tynnu UI, arddulliau, dolenni ffont, y sgript a'r API byd-eang. Gwrthodir allwedd, URL API, scriptUrl, locale neu opsiwn debug gwahanol tra bo handlenni'n bodoli. Gyda widget.js v15, mae window.ChattyBox.destroy() yn gwneud yr un teardown. Peidiwch â chymysgu'r SDK â GTM, ategyn neu loader arall; nid oes ready promise, container target na diweddariad locale adweithiol.

Adeiladu Eich UI Eich Hun

Defnyddiwch y dulliau di-ben isod pan mai eich rhaglen sy’n berchen ar restr negeseuon, mewnbwn, cyflwr llwytho a gwallau, dyfyniadau a hygyrchedd.

Anfon Neges

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

Gosodwch PUBLIC_CHATTYBOX_API_URL i union URL API y widget o’r tab Embed. Mae’r SDK yn derbyn naill ai wraidd y deployment neu URL sy’n gorffen â /chat.

Mae’r ymateb yn cynnwys:

Maes	Math	Disgrifiad
message	string	Ateb neu fallback; rhowch fel testun neu Markdown diogel.
conversationId	string	Dynodwr a ddefnyddir i barhau’r sgwrs hon.
sources	string[]	URLau ffynhonnell; gall fallback fod yn wag.

Mae sendMessage(input) yn derbyn dim ond message, conversationId dewisol neu null, ac idempotencyKey dewisol. Nid yw'n anfon sourceUrl, sourcePath, locale na dewisiadau model. Dilyswch neges nad yw'n wag a hyd trimiedig uchaf o 2,000 nod cyn ei hanfon.

Parhau â Sgwrs

Cadwch ID y sgwrs a ddychwelwyd yng nghyflwr eich UI a’i anfon gyda’r neges nesaf:

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

Peidiwch ag ailddefnyddio un ID sgwrs ar gyfer ymwelwyr nad ydynt yn gysylltiedig. Mae hepgor conversationId neu ddefnyddio null yn dechrau sgwrs newydd. Mae’r ID yn grwpio negeseuon a gedwir yn unig: nid yw’r generadur cyfredol yn pasio troeon blaenorol i’r model, felly rhaid i gwestiynau dilynol gynnwys eu cyd-destun eu hunain.

Trin Gwallau

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

Mae ChattyboxError.status yn cynnwys statws HTTP ac mae code yn ddewisol; ni chaiff gwallau rhwydwaith eu lapio. Mae'r SDK yn anfon idempotencyKey fel Idempotency-Key ond nid yw'n creu un nac yn ailgeisio i chi. Cadwch yr un allwedd unigryw a'r un mewnbwn ar gyfer retry; peidiwch ag ailgeisio pob 409 yn ddall.

Ailddefnyddio Gosodiadau Prosiect a Chyfieithiadau

Mae’r SDK hefyd yn darparu getWidgetConfig() a getWidgetTranslations(locale). Mae’r dulliau hyn yn cefnogi cleientiaid sydd am atgynhyrchu gosodiadau prosiect a labeli lleol y widget lletyol:

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

Gall UI cwbl bersonol eu hanwybyddu. Cadwch conversationId pob ymwelydd ym mhorwr neu gyflwr sesiwn yr ymwelydd hwnnw; peidiwch byth â rhannu un ID sgwrs byd-eang. Mae getWidgetTranslations(locale) yn derbyn un o'r 14 cod catalog; nid yw fr-CA na FR yn cael eu normaleiddio gan yr SDK fel y mae'r widget lletyol yn ei wneud.

Camau Nesaf

• Gwell gennych UI a gynhelir heb adeiladu? Gosodwch widget.js.
• Addaswch y UI lletyol yn Addasu’r widget lletyol.
• Cyn lansio, profwch gyfyngiadau tarddiad, atebion wrth gefn, dyfyniadau ac ymddygiad symudol gyda’r rhestr wirio lansio.