@moveo-ai/web-client 0.112.0 → 0.113.0

package/README.md

@@ -219,8 +219,16 @@ payload listed below.
 
 `onAnalyticsEvent` receives every interaction the widget tracks, identified by
 the `event` field: `session_start`, `session_end`, `message_sent` (the user sent
-a message — never carries the text), `launcher_clicked`, `rating_submitted`, and
-the rest of the `AnalyticsEvent` enum in `src/hooks/useAnalytics.ts`.
+a message — never carries the text), `launcher_clicked`,
+`teaser_quick_reply_clicked` (a teaser reply the visitor tapped, carrying its
+configured `label`), `teaser_composer_submitted` (the visitor sent their own
+line from the teaser — carries no properties, because the text is theirs),
+`rating_submitted`, and the rest of the `AnalyticsEvent` enum in
+`src/hooks/useAnalytics.ts`.
+
+No event carries message text. `properties` is forwarded verbatim by
+integrations to their own analytics vendors, so anything the visitor typed stays
+out of it — only copy the integration itself configured appears there.
 
 It also receives one event that is not an interaction: **`widget_loaded`**,
 raised as soon as the widget renders on the page. It carries no `session_id`,
@@ -324,6 +332,200 @@ MoveoAI.init({
 });
 ```
 
+### Teaser
+
+The teaser is the invitation shown beside the closed launcher. `variant` picks
+its shape, and each variant declares only the fields it renders, so a
+placeholder on a variant with no input is a compile error rather than a silent
+no-op.
+
+| Variant          | Needs           | Renders                                                             |
+| ---------------- | --------------- | ------------------------------------------------------------------- |
+| `callout`        | `message`       | The line in the bubble. The default, and the teaser as it is today. |
+| `question_chips` | `quick_replies` | Tappable questions **in place of** the line, at most three.         |
+| `composer`       | `message`       | The line with an input under it.                                    |
+| `none`           | —               | Launcher only.                                                      |
+
+```javascript
+MoveoAI.init({
+  integrationId: 'YOUR_INTEGRATION_ID',
+  teaser: {
+    variant: 'question_chips',
+    quick_replies: ['Compare products', 'Help me choose'],
+  },
+});
+
+MoveoAI.init({
+  integrationId: 'YOUR_INTEGRATION_ID',
+  teaser: {
+    variant: 'composer',
+    message: 'Tell me what you sell and I will narrow it down.',
+    placeholder: 'e.g. a two-till bakery',
+  },
+});
+```
+
+With no `variant`, replies mean `question_chips` and their absence means
+`callout`, so the shorthand `{ quick_replies: [...] }` keeps working.
+
+#### A different teaser per page
+
+`teaser.pages[]` varies the teaser by URL. The **first** entry whose `url`
+appears in the page's URL wins, so specific paths belong above general ones, and
+the `teaser` block itself covers everywhere else.
+
+```javascript
+MoveoAI.init({
+  integrationId: 'YOUR_INTEGRATION_ID',
+  teaser: {
+    // The block is the teaser wherever no `pages[]` entry matches.
+    variant: 'callout',
+    message: 'Anything I can help with?',
+    pages: [
+      {
+        url: '/products/flex',
+        variant: 'question_chips',
+        quick_replies: ['Explain Flex to me', 'Compare Flex and Station Duo'],
+      },
+      {
+        url: '/shop',
+        variant: 'composer',
+        message: 'Nine systems here. Tell me what you sell.',
+        placeholder: 'e.g. a two-till bakery',
+      },
+    ],
+  },
+});
+```
+
+`url` is **a hint, not a pattern**: it matches when it appears anywhere in the
+page's URL, compared case-insensitively. Nothing is escaped and nothing is
+compiled, so a stray `.` or `(` cannot change what matches or throw. This is the
+one thing `pages[]` does differently from the `page_triggers` it replaces, whose
+keys were compiled with `new RegExp`.
+
+`pages[]` is an array and not a map keyed by URL so that precedence is visible
+to whoever wrote it. `variant: 'none'` on the block, with a `pages[]` entry that
+opts back in, gives a teaser on those pages and nowhere else.
+
+**It follows the visitor.** `clientUrl` is read once when the widget loads, so on
+a single-page app it names the page the visitor arrived on for the rest of the
+visit. When `pages[]` is configured the loader watches for navigation and relays
+the new URL, and the teaser re-resolves. An integration that configures no
+`pages[]` is not watched at all, because the watcher patches `history` and never
+restores it.
+
+**Chips replace the line, they do not sit under it.** Asking the question and
+offering the answers says the same thing twice, and a bubble above
+content-width chips leaves a ragged edge.
+
+**Chips carry no dismiss.** `callout` and `composer` keep theirs, because both
+cover part of the page. A chip is cheap to ignore, and a close control in the
+stack reads as a fourth, broken chip. `close_opening_message_click` therefore
+does not fire for `question_chips`.
+
+**A variant degrades rather than rendering an empty surface.**
+`question_chips` with no replies falls back to `callout`; `callout` or
+`composer` with no line resolves to `none`.
+
+#### Sending
+
+A tapped chip and a typed composer line take the same path: the widget opens
+and the text is sent as the visitor's first message, once the session is ready
+and the visitor form, if any, is done. It replaces the configured
+`welcome_trigger_message` for that conversation, so the visitor's own words
+open it.
+
+#### While the visitor is reading
+
+A configured teaser steps out of the way as the host page scrolls, and fades
+back a second after it stops. It is out of reach while it is out of sight, so a
+keyboard cannot land on a chip nobody can see.
+
+This applies only to an integration that sets a `teaser`. An integration with
+nothing but a `welcome_message` keeps the opening message it has always had,
+sitting still, and no scroll listener is attached to its pages.
+
+#### When it appears, and when it gives up
+
+Two optional clocks, both **off unless set**, so an integration that configures
+neither behaves exactly as it does today — the teaser appears as soon as it has
+something to say, and stays.
+
+```javascript
+MoveoAI.init({
+  integrationId: 'YOUR_INTEGRATION_ID',
+  teaser: {
+    message: 'Anything I can help with?',
+    show_after: 8, // wait 8s before inviting
+    hide_after: 45, // retire after 45s on screen
+  },
+});
+```
+
+| Field        | Unit    | Off | Clamped to | Means                                                 |
+| ------------ | ------- | --- | ---------- | ----------------------------------------------------- |
+| `show_after` | seconds | `0` | 1–60       | Wait this long before the teaser appears.             |
+| `hide_after` | seconds | `0` | 5–300      | Retire it after this long, for the rest of the visit. |
+
+Both are **block-level**, not per-page: they describe the visit, not the page. A
+`pages[]` entry with its own delay would restart the clock on every navigation
+of a single-page app, so the teaser would arrive later on each page and, past a
+few, never at all.
+
+`show_after` counts **settled** seconds, and any scroll starts it over: the
+invitation waits for a calm moment rather than arriving in the middle of a
+gesture. The trade is that a visitor who scrolls more often than the delay never
+settles for long enough and never sees the teaser at all — pick the number
+against how the page is actually read, because a long delay on a page people
+scan continuously invites nobody.
+
+It is counted from the moment the teaser has something to say, not from the page
+loading — the config arrives over postMessage, so a clock started earlier would
+come out shortest on exactly the slow pages a delay matters on. A
+`showTeaserMessage()` call is never held behind it: the host asking for the
+teaser means now.
+
+`hide_after` counts the time the teaser is **on screen**. The clock pauses while
+the visitor scrolls it out of the way and resumes with what is left, so a
+visitor who spent the budget scrolling has not spent it ignoring the teaser.
+Once retired, the teaser is gone for the visit; the launcher is not.
+
+A malformed value — negative, non-numeric, infinite — reads as off rather than
+being clamped up to the minimum, so a bad config cannot start hiding a teaser
+the integration can see today.
+
+#### The line
+
+Precedence, highest first:
+
+1. A line handed to **`showTeaserMessage('...')`**, for as long as it is set.
+   Calling it with no argument clears the override and hands the teaser back to
+   the config.
+2. **`page_triggers[].opening_message`** for this URL.
+3. **`teaser.message`** (or the `pages[]` entry's).
+4. The deprecated top-level **`welcome_message`**.
+
+`message` supersedes `welcome_message`, which is still read when `message` is
+absent. The two legacy sources above it stay ahead of `teaser.message` on
+purpose: per-page copy an integration already relies on, or a line the host
+asked for by name, must not be replaced by a default someone adds later.
+
+`page_triggers` is **deprecated and frozen**. It still varies the line and the
+auto-sent opener by URL for the five integrations that set it, and it is not
+removed, because one of them is a live customer. New work belongs on
+`teaser.pages[]`.
+
+`manual_teaser_mode` and `showTeaserMessage()` keep their meaning.
+
+#### Restyling it
+
+The teaser follows the accent out of the box. The bubble reads
+`--color-opening-message-background` and
+`--color-opening-message-foreground`, and the chips and the composer field
+read the `--color-options-*` set. All five are in
+[CSS Variables](#css-variables), and are set through `setCSSVariables()`.
+
 ### Inactivity Timeout
 
 The widget opens an inactivity modal once the visitor goes quiet, and asks
@@ -447,15 +649,21 @@ A colour that says "defaults to" follows `--color-accent` — or the colour name
 — until you set it. So an accent alone restyles the links, the rating, the send
 icon and the launcher, and `--color-chat-background` follows the background.
 
-Four more colours have no `theme_colors` key, so they are set through
+Six more colours have no `theme_colors` key, so they are set through
 `setCSSVariables()` only:
 
-| Variable                     | Controls                                             |
-| ---------------------------- | ---------------------------------------------------- |
-| `--color-chat-background`    | The area behind the messages; follows the background |
-| `--color-options-background` | Quick reply button background                        |
-| `--color-options-foreground` | Quick reply button label; defaults to the accent     |
-| `--color-options-border`     | Quick reply button border; defaults to the accent    |
+| Variable                             | Controls                                                            |
+| ------------------------------------ | ------------------------------------------------------------------- |
+| `--color-chat-background`            | The area behind the messages; follows the background                |
+| `--color-options-background`         | Quick reply buttons, and the teaser chips and composer field        |
+| `--color-options-foreground`         | Quick reply labels, the teaser composer text, and a chip under the pointer or the focus ring; defaults to the accent |
+| `--color-options-border`             | Quick reply borders, the teaser composer field, and a chip under the pointer or the focus ring; defaults to the accent |
+| `--color-opening-message-background` | The teaser bubble, on `callout` and `composer`; defaults to the accent |
+| `--color-opening-message-foreground` | The teaser bubble text; defaults to the visitor's own bubble text colour |
+
+The two `opening-message` names are the teaser's, from before it was called
+one. They are the only lever that moves the bubble off the accent, so an
+integration whose accent is too dark to invite anybody sets them here.
 
 #### Renamed variables
 

package/dist/63.min.js.LICENSE.txt

@@ -1,6 +1,6 @@
 /*!
  * 
- *   @moveo-ai/web-client v0.112.0
+ *   @moveo-ai/web-client v0.113.0
  *   Copyright (c) Moveo.ai (TM)
  *
  */

package/dist/752.min.js.LICENSE.txt

@@ -1,6 +1,6 @@
 /*!
  * 
- *   @moveo-ai/web-client v0.112.0
+ *   @moveo-ai/web-client v0.113.0
  *   Copyright (c) Moveo.ai (TM)
  *
  */

package/dist/882.min.js.LICENSE.txt

@@ -1,6 +1,6 @@
 /*!
  * 
- *   @moveo-ai/web-client v0.112.0
+ *   @moveo-ai/web-client v0.113.0
  *   Copyright (c) Moveo.ai (TM)
  *
  */

package/dist/929.min.js.LICENSE.txt

@@ -1,6 +1,6 @@
 /*!
  * 
- *   @moveo-ai/web-client v0.112.0
+ *   @moveo-ai/web-client v0.113.0
  *   Copyright (c) Moveo.ai (TM)
  *
  */