Widget

Un singur tag <script>, un buton flotant, un modal sau un panou inline (§61).

Nepublicat încă

@callagent/web-sdk este private: true, deci nici pachetul npm, nici bundle-ul cdn.callagent.dev la care se face referire mai jos nu sunt publicate. Tag-ul de script este forma cu care se va livra widget-ul; astăzi se construiește dintr-un checkout (pnpm --filter @callagent/web-sdk build produce dist/widget.global.js) și îl servești singur. Widget-ul depinde și de aceeași rută neimplementată POST /api/v1/client/calls ca Web SDK, deci nu poate încă porni un apel către un control plane real.

<script
  src="https://cdn.callagent.dev/widget.js"
  data-public-key="ca_pk_…"
  data-assistant-id="01J…"
  data-mode="voice"
  data-theme="auto"
  data-accent="#4f46e5"
  data-position="bottom-right"
  data-locale="en"
  data-greeting="Hi! Ask me anything about your order."></script>

17.38 KB gzipped (15.39 KB brotli), fără runtime de framework, fără jQuery, fără CSS global.

Atribute

Atribut	Valori	Implicit
data-public-key	ca_pk_…	obligatoriu (sau data-token)
data-token	un JWT emis de backend-ul tău	—
data-assistant-id	ULID de assistant	—
data-api-url	origin-ul control plane-ului	https://api.callagent.dev
data-mode	voice, chat, voice+chat	voice
data-theme	light, dark, auto	auto
data-accent	orice culoare CSS	#4f46e5
data-position	bottom-right, bottom-left, top-right, top-left	bottom-right
data-variant	floating, inline	floating
data-target	selector, obligatoriu pentru inline	—
data-locale	en, ro, fr, de	limba browserului
data-greeting	text afișat înainte să înceapă apelul	—
data-variables / data-metadata	obiecte JSON	—
data-auto-open	true / false	false
data-branding	false ascunde atribuirea	true
data-z-index	număr întreg	2147483000
data-auto	false ca să montezi din JavaScript în schimb	true

Un atribut JSON malformat este ignorat, în loc să împiedice montarea widget-ului.

Din JavaScript

<script src="https://cdn.callagent.dev/widget.js" data-auto="false"></script>
<script>
  const widget = CallAgentWidget.mount({
    publicKey: 'ca_pk_…',
    assistantId: '01J…',
    variant: 'inline',
    target: '#assistant',
    strings: { launcherLabel: 'Call the vet' },   // suprascrie orice string încorporat
  });

  widget.open();
  widget.close();
  widget.destroy();
</script>

widget.client este CallAgent-ul din spate, așa că tool-urile client-side se înregistrează pe el exact ca în SDK.

Izolare

Totul se randează într-un Shadow DOM cu all: initial pe :host. Nimic din ce definește widget-ul nu poate ajunge la pagina gazdă, și nimic de pe pagina gazdă — un preflight Tailwind, un reset agresiv — nu poate ajunge înăuntru. Widget-ul adaugă exact un element în document.body și zero foi de stil în document.

Accesibilitate

• Launcher-ul și fiecare control sunt accesibile de la tastatură, cu un inel de focus vizibil.
• Panoul este role="dialog" aria-modal="true", are un nume accesibil și captează Tab; Escape îl închide și readuce focusul pe launcher.
• Transcrierea este role="log" aria-live="polite". Rezultatele intermediare refolosesc un singur element în loc să adauge fiecare revizuire, așa că un cititor de ecran nu citește aceeași propoziție de cinci ori.
• prefers-reduced-motion: reduce dezactivează animația de intrare, pulsul și scroll-ul lin.
• String-urile furnizate de gazdă sunt escapate, nu injectate ca markup.

Localizare

en, ro, fr și de sunt livrate în bundle; un tag regional cade înapoi pe limba lui de bază și apoi pe engleză. Orice string poate fi suprascris prin strings, așa că un client își poate livra propria limbă fără să aștepte o versiune nouă.

Demo

pnpm --filter @callagent/web-sdk build
pnpm --filter @callagent/web-sdk demo

apps/web-sdk/demo/index.html montează ambele variante, expune fiecare opțiune ca un control și înregistrează un tool client-side de demonstrație.