Виджет

Бұл бет машиналық аудармамен жасалған және тексерілуде. Қателер болуы мүмкін - ағылшын нұсқасын қараңыз.

Фреймворкке тәуелсіз жалғыз веб-компонент. Ол беттің бұрышында іске қосу батырмасын көрсетеді және чаты бар бүйір панелін ашады. Ол shadow root ішінде жұмыс істейді, сондықтан хост беттің CSS-і оны бұза алмайды. Қарапайым HTML-де, React, Vue, Svelte немесе Angular-да бірдей жұмыс істейді.

Орнату

<script src="https://unpkg.com/@shalotts/pleiades-widget/dist/pleiades-widget.js" defer></script>

<pleiades-chat
  agent-url="https://agent.example.com"
  publishable-key="pk_your_channel_key"
></pleiades-chat>
html

Тек WebMCP polyfill керек, чатсыз ба? Бұл сол пакеттің жеке кіру нүктесі (виджет оны өзі орнатады):

import { installWebMcpPolyfill } from "@shalotts/pleiades-widget/webmcp-polyfill";

installWebMcpPolyfill();
js

agent-url және publishable-key мәндері әкімші панеліндегі арнаңыздан алынады. Виджет сондай-ақ нативті қолдауы жоқ беттерде WebMCP polyfill орнатады, сондықтан құралдарыңыз кез келген браузерде жұмыс істейді.

Конфигурация қате болса, элемент ештеңе көрсетпейді және консольге бір [pleiades-widget] <code> жолын жазады. Қателер бөлімін қараңыз.

Атрибуттар

Барлық баптау атрибуттар арқылы жасалады. Біреуін өзгерту виджетті қайта монтаждайды.

АтрибутӘдепкіСипаттамасы
agent-urlміндеттіОркестратордың базалық URL-ы. Тек https; localhost, 127.0.0.1 және [::1] үшін қарапайым http қабылданады. URL ішінде пайдаланушы аты мен құпиясөз болмауы керек.
publishable-keyміндеттіАрнаның ашық кілті. pk_ және одан кейін A-Za-z0-9_- таңбаларынан кемінде 8 таңба болуы керек.
positionbottom-leftІске қосу батырмасының бұрышы: bottom-left, bottom-right, top-left, top-right. Панель сол жақтан шығады. Белгісіз мәндер bottom-left болып қалады.
headingлокализацияланғанПанель тақырыбы.
greetingлокализацияланғанБірінші хабарлама көпіршігі.
placeholderлокализацияланғанХабарлама жолындағы қолдау мәтіні.
lang<html lang>, әйтпесе браузер тіліen, ru немесе kk. Тек алғашқы екі әріп оқылады (ru-RU жұмыс істейді); қалғаны ағылшын тілі болады.
customer-contextжоқСайт бұрыннан білетін фактілердің жазық JSON-объектісі, мысалы '{"city":"Almaty","tier":"gold"}'. Мәндер жол, сан немесе булев болуы керек; басқа өрістер консольдағы қатемен алынып тасталады. Әр хабарламамен бірге жіберіледі.
hotkeymod+jПанельді ашады және жабады. mod — Ctrl, ал Mac-та Cmd. Басқа мысалдар: ctrl+shift+k, alt+/. Бос мән оны өшіреді.
mic-hotkeymod+shift+spaceПанель ашық кезде диктовканы бастайды және тоқтатады. Формат бірдей. Бос мән өшіреді.
expose-tools-toжоқТерезелері осы беттің құралдарын postMessage арқылы тізімдей және іске қоса алатын origin-дердің үтірмен бөлінген тізімі (https://a.example,https://b.example). * және жарамсыз origin-дер еленбейді. Құралдар бөлімін қараңыз.
examplesкірістірілген үшеуіБірінші хабарламаға дейін көрсетілетін үш ұсынысқа дейін: жолдардың JSON-массиві, '["Find a jacket","Where is my order?"]'. '[]' оларды жасырады. Талданбайтын мән кірістірілгендерді сақтайды.
openжоқБулев атрибут. Панель ашық күйде басталады. Сондай-ақ open property.
test-apiжоқБулев атрибут. Браузерді автоматтандыру үшін window.pleiadesChat.send(text) функциясын да ашады. Әдепкіде өшірулі: өндірістік беттерде глобалды айнымалы жоқ.

Диктовка бар жерде браузердің Web Speech API-ін пайдаланады. Ол жоқ жерде микрофон батырмасы бұғатталған болып көрінеді.

Элемент әдістері мен property-лері

const chat = document.querySelector("pleiades-chat");
js
МүшеСипаттамасы
chat.openopen атрибутын көрсететін property. Панельді ашу немесе жабу үшін оны орнатыңыз.
chat.toggle()open мәнін ауыстырады.
chat.send(text)text мәтінін келуші теріп, «Жіберу» түймесін басқандай жібереді. Панельді ашады, беттің құрал шақыруларын орындайды және кезек аяқталғанда resolve болады. Ешқашан reject болмайды.
chat.resetSession()Сол келуші үшін жаңа сөйлесу: жаңа тред, бос панель, беттің құралдары қайта жарияланады. Ешқашан reject болмайды.
chat.getVisitorToken()Осы браузердің келуші токенімен resolve болады (қажет болса сессияны құрады), ал элемент бапталмаған кезде undefined қайтарады. Оны серверіңізге identify үшін беріңіз.
chat.agentUrl, publishableKey, position, heading, greeting, placeholder, lang, customerContext, examples, hotkey, micHotkey, exposeToolsToАтрибуттарды көрсететін property-лер (жолдар). null немесе undefined орнату атрибутты жояды.

send()

const r = await chat.send("book a double room for two nights from Friday");
// { requestId?, reply, steps: [{ text, phase }], status: "done" | "failed" | "error", error? }
js
ӨрісМағынасы
status: "done"Мақсатқа жетті.
status: "failed"Сервер жұмыс істеді, бірақ сайт тапсырманы орындай алмады. error өрісінде сайттың өз соңғы жауабы болады (бар болса).
status: "error"Бос емес, бапталмаған, хабарлама тым ұзын, сервер қатесі немесе тоқтатылды. error не болғанын айтады.
replyКезектегі ассистенттің түпкілікті мәтіні.
stepsКезек үшін көрсетілген прогресс жолдары; phase — running, done немесе failed.
requestIdКезектің бірінші tool_call идентификаторы (әкімшідегі /flow/<id> бетінде жұмысты ашады). Браузер жағындағы құрал шақыруы жоқ кезекте болмайды.

resetSession()

Оркестратор әр сөйлесу бойынша фактілерді сақтайды (қай дүкен ашық, соңғы табылған тауар). Бір қосымшаны екіншісіне ауыстыратын бет әр ауыстыру сайын сброс жасауы керек:

picker.addEventListener("change", () => chat.resetSession());
js

Әр түрлі сайттар бөлек арналарды қолдануы керек (әрқайсысына бір publishable-key); кілтті ауыстыру әрқайсысына өз сөйлесуін береді, ол беттерді қайта жүктегенде сақталады.

Тақырыптандыру

CSS айнымалыларын элементке орнатыңыз:

АйнымалыМақсаты
--pleiades-accent, --pleiades-accent-fgАкцент түсі және оның үстіндегі мәтін.
--pleiades-bg, --pleiades-fgПанель фоны және мәтіні.
--pleiades-muted, --pleiades-muted-fgҚосымша беттер және мәтін.
--pleiades-borderЖиектер.
--pleiades-destructive, --pleiades-destructive-fgҚате түсі және оның үстіндегі мәтін.
--pleiades-font-familyҚаріп.
--pleiades-font-scaleБарлық мәтін өлшемдерінің көбейткіші; әдепкі 1.5. 1 ықшам 14 px негіз береді.
pleiades-chat {
  --pleiades-accent: #0b6e4f;
  --pleiades-accent-fg: #fff;
  --pleiades-font-family: "Inter", sans-serif;
}
css

Токендерден тыс кез келген нәрсе үшін CSS Shadow Parts қолданыңыз:

pleiades-chat::part(panel) { border-radius: 0; }
pleiades-chat::part(send)  { text-transform: uppercase; }
css

Үлгілерде бар part-тар: launcher, panel, header, close, messages, error, mode, hint, tooltip, composer, input, send, mic, link.

@shalotts/pleiades-widget/style.css — виджет өзінің shadow root ішіне енгізетін дәл сол stylesheet. Оны класс атаулары үшін анықтама ретінде қолданыңыз; оны бетке қосу ештеңе істемейді, өйткені shadow DOM оны ол жерде қолданбайды.

Типтер

Пакет TypeScript декларацияларымен, соның ішінде HTMLElementTagNameMap жазбасымен жеткізіледі, сондықтан document.querySelector("pleiades-chat") типтелген. React JSX үшін augmentation-ды бір рет импорттаңыз:

import type {} from "@shalotts/pleiades-widget/react";
ts

Қателер

Конфигурация қателері бір рет [pleiades-widget] <code>: <advice> түрінде жазылады және ештеңе көрсетілмейді.

КодСебебі
missing_agent_urlagent-url бос.
invalid_agent_urlhttp(s) URL емес немесе оның ішінде пайдаланушы аты не құпиясөз бар.
insecure_agent_urllocalhost емес хостқа http.
missing_keypublishable-key бос.
secret_keyКілт sk_ деп басталады. Оны ашылып қалған деп санап, ауыстырыңыз.
invalid_keyКүтілген пішіндегі pk_ кілті емес.

Қате customer-context invalid_customer_context жазады және алынып тасталады; виджет жұмысын жалғастырады.

Орындалу уақытындағы ақаулар панельде көрсетіледі. Олар API статусынан алынады: жауаптың болмауы — желі қатесі және composer-ді бұғаттайды, 403 — тыйым салынған, 413 — «тым ұзын», 429 — жылдамдық шектелген, code: "task_failed" бар терминал ағын error-ы сайттың кеңесін көрсетеді және composer-ді ешқашан бұғаттамайды. Арна рұқсат етпейтін origin браузерде желі қатесі сияқты көрінеді: сервер CORS тақырыптарынсыз 403 жауап береді, сондықтан браузер себебін жасырады.

Қауіпсіздік

  • Тек pk_ кілттері. Виджет sk_ кілтімен іске қосудан бас тартады. Құпия кілт identify үшін серверіңізде тұруы керек.
  • agent-url үшін тек https (localhost-тан басқа), сондықтан келуші токені ашық мәтінмен ешқашан жіберілмейді.
  • Рұқсат етілген origin-дер. Арна оны қолдана алатын origin-дерді тізімдейді; сервер Origin тақырыбын тексереді, оны браузер жасанды түрде жасай алмайды. Көшірілген кілт басқа сайтта пайдасыз.
  • Бетте құпия жоқ. Кілт келуші токенін алу үшін бір рет жіберіледі. Кейінгі әр сұраныста тек токен болады.
  • Сұраныстар credentials: "omit" және cache: "no-store" қолданады: cookie жоқ, ештеңе кэшталмайды.
  • Токен мен тред идентификаторы localStorage ішінде agent URL мен кілттен алынған атаумен сақталады, сондықтан екі сайт сессияны ешқашан бөліспейді. Сақтау бұғатталса, виджет жадыға көшеді.
  • Хабарлама мәтіні textContent арқылы көрсетіледі, ешқашан HTML ретінде емес.
  • customer-context ішіне құпия деректерді салмаңыз. Оны бірнеше қысқа фактімен (ел, қала, тариф белгісі) шектеңіз, есімдерді, email-дерді немесе телефон нөмірлерін ешқашан салмаңыз.
  • Бетте тіркелген құралдар оркестратор үшін сенімсіз деректер, ал expose-tools-to болмаса, басқа терезе оларға қол жеткізе алмайды.

Скриптті өзіңіз хостласаңыз, оны Subresource Integrity арқылы бекітіңіз.