@askly/widget 2.3.0 → 2.4.0

package/README.md

@@ -15,51 +15,38 @@ Askly is an **embeddable AI support chat widget** for React and plain HTML. Drop
 - 📚 **RAG (docs-grounded)** — replies grounded in your own documentation, not hallucinated.
 - 🎙️ **Voice chat** — customers can talk to the assistant, not just type.
 - 🙋 **Human handoff** — one-click escalation to a live agent when needed.
-- ⚛️ **React + CDN** — use as an npm module or a single `<script>` tag.
+- ⚛️ **React + CDN** — use as an npm module, or a single `<script>` tag on any site (no React required).
 - 🎨 **Fully themeable** — colors, logo, position, and copy configured in the portal.
 
 ## Installation
 
-### NPM
-```bash
-npm install @askly/widget
-```
+### Script tag (any website)
 
-### CDN
-Include the UMD build directly in your HTML:
-```html
-<!-- React Dependencies -->
-<script crossorigin src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
-<script crossorigin src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
+One line, before `</body>`. The bundle is self-contained — no React or other dependencies on your page:
 
-<!-- Askly SDK -->
-<script src="https://unpkg.com/@askly/widget@latest/dist/index.umd.js"></script>
+```html
+<script src="https://unpkg.com/@askly/widget@latest/dist/widget.js" data-app-id="YOUR_APP_ID" async></script>
 ```
 
-## Quick Start
+That's the whole install. Your branding — name, logo, theme, welcome message — loads automatically from your Askly portal settings.
 
-All you need is your `widgetId` — copy it from the **Widget setup** screen in your Askly tenant portal. Everything else (name, theme, logo, welcome message, voice, etc.) is configured there and loaded automatically; the init props below are optional overrides.
+### NPM (React / bundlers)
+
+```bash
+npm install @askly/widget
+```
 
 ```javascript
 import Askly from '@askly/widget';
 
-Askly.init({ widgetId: "your-widget-id" });
+Askly.init({ appId: "YOUR_APP_ID" });
 ```
 
-For CDN initialization:
-```html
-<script>
-  Askly.init({ widgetId: "your-widget-id" });
-</script>
-```
+The npm builds (`index.esm.js` / `index.umd.js`) treat React as a peer dependency, so your bundle isn't double-shipping it.
 
-Alternatively, initialize automatically via a single script tag:
-```html
-<script
-  src="https://unpkg.com/@askly/widget@latest/dist/index.umd.js"
-  data-widget-id="your-widget-id"
-></script>
-```
+## Quick Start
+
+All you need is your `appId` — copy it from **Widget → Install Code** in your Askly tenant portal. Everything else (name, theme, logo, welcome message, voice, etc.) is configured there and loaded automatically; the init props below are optional overrides.
 
 > The widget talks to Askly's hosted backend automatically — there is nothing else to configure.
 
@@ -69,11 +56,13 @@ The `Askly.init()` method accepts an object with the following configuration opt
 
 | Option | Type | Required | Default | Description |
 | :--- | :--- | :--- | :--- | :--- |
-| `widgetId` | `string` | **Yes** | - | Your widget ID, from the tenant portal's Widget setup screen. |
+| `appId` | `string` | **Yes** | - | Your app ID, from the tenant portal's **Widget → Install Code** screen. Script tag: `data-app-id`. |
+
+> `widgetId` and `orgId` are still accepted as deprecated aliases for `appId`, so existing embeds keep working.
 
 ### Configured in the portal
 
-The widget's appearance and behaviour — display name, logo, theme color, welcome message, position, voice, sounds, timestamps, "powered by" text, and so on — are set on the **Widget setup** screen in your Askly portal and loaded automatically by `widgetId`. **You do not pass these in code.** (They remain accepted as optional `init()` overrides for advanced cases, but the portal is the source of truth.)
+The widget's appearance and behaviour — display name, logo, theme color, welcome message, position, voice, sounds, timestamps, "powered by" text, and so on — are set on the **Widget** screen in your Askly portal and loaded automatically by `appId`. Logos are uploaded right there and apply instantly. **You do not pass these in code.** (They remain accepted as optional `init()` overrides for advanced cases, but the portal is the source of truth.)
 
 ### Identifying an authenticated user
 
@@ -140,6 +129,28 @@ instead of calling `identify()` separately:
 | `timestamp` | `number` | Signature timestamp. |
 | `signature` | `string` | HMAC request signature (same value as `hash` above). |
 
+### Asking visitors for their email
+
+Anonymous visitors can't be replied to once they close the tab — the answer just waits in a widget
+they may never reopen. So the widget can ask for an email, and Askly delivers the reply there
+instead when they've gone.
+
+Configured on the **Widget** screen in your portal, not in code:
+
+| Mode | Behaviour |
+| :--- | :--- |
+| **When it matters** *(default)* | A dismissible prompt after the assistant replies, and a required one only once a conversation is waiting on your team — the point where email is the only way to reach them. Barely affects how many people start a chat. |
+| **Before every chat** | Nobody can send a first message without an email. Captures the most addresses, at a cost of roughly 30% fewer conversations — including ones the assistant would have resolved on its own. |
+| **Never** | Visitors are never asked. |
+
+Anyone whose address you already have — from `identify()`, a previous chat, or because they typed
+it — is never asked again.
+
+An address given this way is **not verified**: it proves the person wants replies there, not who
+they are. It is never used to match them to an existing contact, so nobody can read someone else's
+conversation history by typing their address. Only addresses given through this prompt are ever
+emailed; one merely spotted in the text of a message is not consent to write to them.
+
 ### Restricting the widget to certain pages
 
 Control where the widget appears using URL **path prefixes** (matched against `window.location.pathname`).
@@ -151,10 +162,10 @@ Control where the widget appears using URL **path prefixes** (matched against `w
 
 ```javascript
 // Show ONLY on support & docs pages
-Askly.init({ widgetId: "your-widget-id", includePaths: ["/support", "/docs"] });
+Askly.init({ appId: "YOUR_APP_ID", includePaths: ["/support", "/docs"] });
 
 // Show everywhere EXCEPT admin & checkout
-Askly.init({ widgetId: "your-widget-id", excludePaths: ["/admin", "/checkout"] });
+Askly.init({ appId: "YOUR_APP_ID", excludePaths: ["/admin", "/checkout"] });
 ```
 
 Via script tag, use comma-separated values: `data-include-paths="/support,/docs"` or `data-exclude-paths="/admin,/checkout"`.
@@ -172,7 +183,7 @@ Callbacks are functions, so they can only be attached in code (not from the port
 
 ```javascript
 Askly.init({
-  widgetId: "your-widget-id",
+  appId: "YOUR_APP_ID",
   onMessageSent: (message) => console.log("Sent:", message),
   onMessageReceived: (reply) => console.log("Received:", reply),
   onChatOpened: () => console.log("Opened"),
@@ -183,7 +194,7 @@ Askly.init({
 
 ## Backend Integration
 
-None required. The widget talks to Askly's hosted backend automatically — you only provide a `widgetId`.
+None required. The widget talks to Askly's hosted backend automatically — you only provide an `appId`.
 
 ## Development