@skippr/live-agent-sdk 0.109.0 → 0.111.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +21 -22
- package/dist/esm/lib-exports.js +4208 -3755
- package/dist/skippr-sdk.css +1 -1
- package/dist/skippr-sdk.js +154 -154
- package/dist/types/components/ConsentBubble.d.ts +2 -2
- package/dist/types/components/ConsentNotice.d.ts +2 -3
- package/dist/types/components/LiveAgent.d.ts +1 -0
- package/dist/types/components/Sidebar.d.ts +1 -1
- package/dist/types/components/SplashAlwaysOn.d.ts +6 -1
- package/dist/types/components/SplashOptOut.d.ts +5 -0
- package/dist/types/components/SplashOverlay.d.ts +3 -5
- package/dist/types/components/SplashPanel.d.ts +1 -0
- package/dist/types/components/SplashPrimary.d.ts +6 -1
- package/dist/types/components/SplashScreen.d.ts +1 -1
- package/dist/types/context/LiveAgentContext.d.ts +19 -5
- package/dist/types/hooks/useAvailableModules.d.ts +3 -1
- package/dist/types/hooks/useSplash.d.ts +2 -2
- package/dist/types/hooks/useSplashMedia.d.ts +14 -0
- package/dist/types/hooks/useSplashOverlayOptOut.d.ts +7 -0
- package/dist/types/lib/constants.d.ts +43 -1
- package/dist/types/lib/locale.d.ts +2 -0
- package/dist/types/lib/panelAnchor.d.ts +14 -0
- package/dist/types/lib/splashPresentation.d.ts +1 -0
- package/dist/types/lib/splashStyles.d.ts +3 -0
- package/dist/types/lib/splashSurfaces.d.ts +22 -0
- package/dist/types/lib/voiceBar.d.ts +1 -0
- package/dist/types/lib-exports.d.ts +0 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -13,6 +13,7 @@ Embed product specialists that see, speak, and act in real time. Configure **mod
|
|
|
13
13
|
- **Bring your own button** — start, pause, and end sessions from your own UI with the `useLiveAgent` hook (see [Bring your own button](#bring-your-own-button))
|
|
14
14
|
- **Chat + transcript** — text messaging with voice transcripts merged into one thread
|
|
15
15
|
- **Session agenda** — structured phases with progress tracking
|
|
16
|
+
- **Seven languages, no wiring** — the splash card ships translated and follows your page's `<html lang>` on its own (see [Language](#language))
|
|
16
17
|
- **Flexible auth** — email OTP (direct auth) or backend-signed JWT (secret mode)
|
|
17
18
|
- **Drop-in integration** — one React component or script tag, no WebRTC code needed
|
|
18
19
|
- **Host-safe styles** — prefixed CSS that won't conflict with your app
|
|
@@ -232,30 +233,24 @@ function App() {
|
|
|
232
233
|
|
|
233
234
|
### Splash screen
|
|
234
235
|
|
|
235
|
-
When your workspace
|
|
236
|
+
When your workspace turns the splash on under Appearance, the SDK shows a pre-session card before the session starts: what the agent can do, the microphone and screen-access rows it needs, and a Start / Continue button. It is independent of the launcher style, so you can run both or turn the launcher off and let the card be the entry point.
|
|
236
237
|
|
|
237
|
-
|
|
238
|
-
import { LiveAgent, SplashOverlay } from '@skippr/live-agent-sdk';
|
|
238
|
+
There is nothing for you to place. Every embed gets the card — script tag and React alike — and your workspace also chooses where it appears: centred over the page on its own backdrop, or inside the chat panel. The SDK renders it either way and handles its own dismissal.
|
|
239
239
|
|
|
240
|
-
|
|
241
|
-
return (
|
|
242
|
-
<LiveAgent appKey="pk_live_your_key">
|
|
243
|
-
<SplashOverlay />
|
|
244
|
-
</LiveAgent>
|
|
245
|
-
);
|
|
246
|
-
}
|
|
247
|
-
```
|
|
240
|
+
#### Language
|
|
248
241
|
|
|
249
|
-
|
|
242
|
+
The card is translated into English, French, German, Italian, Spanish, and Portuguese (Portugal and Brazil). A page that says `<html lang="de">` renders a German card with no code change — the SDK reads `<html lang>`, then the browser preference. Pass `locale` only when `<html lang>` does not reflect the language on screen:
|
|
250
243
|
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
244
|
+
```tsx
|
|
245
|
+
<LiveAgent appKey="pk_live_your_key" locale="pt-BR" />
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
- **Any BCP-47 tag works.** `'de-AT'` and `'pt'` both resolve; a language Skippr does not ship falls back to English rather than failing.
|
|
249
|
+
- **You can rewrite any string, per language.** Pick a card language in the splash editor under Appearance. Fields you leave alone keep Skippr's translation, so clearing one restores it rather than blanking it. That includes the default capability rows — edit a row's English and set its copy for each language too, or those languages keep the original row's translation.
|
|
255
250
|
|
|
256
251
|
#### Placing the card yourself
|
|
257
252
|
|
|
258
|
-
Use `<SplashScreen>`
|
|
253
|
+
Use `<SplashScreen>` when you also want the card inline in your own layout — a sidebar, a grid cell, a panel, rather than centred over the page. In exchange for the placement control, you own the surrounding state:
|
|
259
254
|
|
|
260
255
|
```tsx
|
|
261
256
|
import { useState } from 'react';
|
|
@@ -283,14 +278,16 @@ function App() {
|
|
|
283
278
|
|
|
284
279
|
- **You own unmounting.** `<SplashScreen>` renders nothing once it no longer applies — the user dismissed it, a session is running, or your workspace has the splash turned off — but it stays mounted until you remove it.
|
|
285
280
|
- **Conditionally render your own wrapper too.** A styled slot (padding, border, grid cell) survives as an empty box when the card stops rendering, as in the example above.
|
|
281
|
+
- **It follows the workspace placement.** `<SplashScreen>` renders while your workspace shows the splash over the page. When the workspace moves the splash into the chat panel, the panel renders the card and `<SplashScreen>` renders nothing.
|
|
282
|
+
- **It only shows while the widget is closed.** The splash and the open widget panel never share the screen, so `<SplashScreen>` renders nothing once the user opens the panel and returns when they close it again.
|
|
286
283
|
|
|
287
284
|
#### Behaviour of both
|
|
288
285
|
|
|
289
|
-
- **
|
|
286
|
+
- **Dismissal is shared.** Closing or skipping either card dismisses the splash for the page load, so the SDK's own card and any `<SplashScreen>` you place come and go together.
|
|
290
287
|
- **Session start needs no callback.** `useLiveAgent()` already reports `isStarting` / `isConnected`, so read the session from there rather than mirroring it into your own state.
|
|
291
|
-
- **Bring it back after a skip.** Dismissal lasts for the page load, so the card returns on the next navigation. On a single-page app, call `reopenSplash()` from `useLiveAgent()` — wire it to a "Start guided tour" link or a help-menu item. Skipping never reveals a launcher
|
|
288
|
+
- **Bring it back after a skip.** Dismissal lasts for the page load, so the card returns on the next navigation. On a single-page app, call `reopenSplash()` from `useLiveAgent()` — wire it to a "Start guided tour" link or a help-menu item. Skipping never reveals a launcher that your workspace has turned off; the host owns when the card comes back.
|
|
292
289
|
- **Check the config before you build around it.** `useLiveAgent()` exposes `isSplashConfigured` so you can pick between the splash and your own launcher; it reflects the workspace setting only, not whether the card is on screen right now.
|
|
293
|
-
- **The card adapts to the agent.** When your workspace's default agent is an always-on expert,
|
|
290
|
+
- **The card adapts to the agent.** When your workspace's default agent is an always-on expert, the card renders a tips layout instead of the guided-tour one: contextual suggestions for the current page, each starting a session on click, plus a catch-all CTA. No prop switches this — it follows the agent configuration.
|
|
294
291
|
|
|
295
292
|
## API Reference
|
|
296
293
|
|
|
@@ -307,6 +304,7 @@ Self-contained widget component. Renders a floating button that opens a sidebar
|
|
|
307
304
|
| `getUserToken` | `() => Promise<string>` | — | Async callback returning a freshly signed JWT for secret mode. The SDK calls it to bootstrap, again proactively before the bearer expires, and once more on a `401` to re-bootstrap. |
|
|
308
305
|
| `userToken` | `string` | — | Static signed JWT for secret mode (testing). Exchanged for a bearer token but can't be refreshed once expired. `getUserToken` takes precedence when both are set. |
|
|
309
306
|
| `userContext` | `Record<string, string \| number \| boolean>` | — | Background facts about the current user so the agent can tailor the conversation (e.g. `{ name: 'Alex', plan: 'pro', signedUpDaysAgo: 3, hasCompletedSetup: false }`). Must be a flat object of strings, numbers, or booleans - nested objects and arrays are not supported. |
|
|
307
|
+
| `locale` | `string` | — | BCP-47 tag naming the language to render the splash card in, e.g. `'de'` or `'pt-BR'`. Only needed when your page's `<html lang>` does not reflect the language on screen — otherwise the card follows `<html lang>`, then the browser preference, with no configuration at all. A language Skippr does not ship falls back to English. |
|
|
310
308
|
| `variant` | `'floating' \| 'sidebar'` | `'floating'` | Widget display mode |
|
|
311
309
|
| `minimizable` | `boolean` | `true` | Whether the widget can be minimized |
|
|
312
310
|
| `defaultOpen` | `boolean` | `false` | Whether the panel starts open |
|
|
@@ -340,7 +338,7 @@ Hook for accessing session state and panel controls. Must be called within `<Liv
|
|
|
340
338
|
| `activeModule` | `Module \| null` | The module the current session was started with |
|
|
341
339
|
| `isLoadingModules` | `boolean` | Whether the picker list is being fetched |
|
|
342
340
|
| `modulesError` | `string \| null` | Error from fetching the picker list, if any |
|
|
343
|
-
| `isSplashConfigured` | `boolean` | Whether your workspace
|
|
341
|
+
| `isSplashConfigured` | `boolean` | Whether your workspace has the splash screen turned on. Configuration only — it does not tell you whether the splash is currently on screen |
|
|
344
342
|
|
|
345
343
|
```ts
|
|
346
344
|
interface Module {
|
|
@@ -395,7 +393,8 @@ Available on `window.Skippr` when using the script tag bundle.
|
|
|
395
393
|
|
|
396
394
|
| Method | Description |
|
|
397
395
|
|--------|-------------|
|
|
398
|
-
| `Skippr.initialize(config)` | Mount the widget. Accepts `appKey` (required), `agentId` (optional — omit for picker), `getUserToken`, `userToken`, `variant`, `minimizable`, `captureMode`. |
|
|
396
|
+
| `Skippr.initialize(config)` | Mount the widget. Accepts `appKey` (required), `agentId` (optional — omit for picker), `getUserToken`, `userToken`, `userContext`, `locale`, `variant`, `minimizable`, `captureMode`. |
|
|
397
|
+
| `Skippr.open()` | Surface the widget from your own button. Brings back a skipped splash screen, opens the chat panel when the splash lives in it, and otherwise reveals the voice bar. The only entry point when your workspace has the launcher turned off |
|
|
399
398
|
| `Skippr.logout()` | Revoke the current session server-side, clear stored auth tokens, and show the login form (direct auth mode) |
|
|
400
399
|
| `Skippr.destroy()` | Remove the widget from the page and clear auth tokens |
|
|
401
400
|
|