@returningai/widget-sdk 1.2.16 → 1.4.0

package/README.md

@@ -10,12 +10,14 @@ Your access credentials stay on your server. Your server exchanges them for a **
 
 **Step 1 — Create an access key pair** (one-time, from your dashboard):
 
-Go to **Community Settings > Integrations > SDK Access** and click **Create SDK Key**. Enter a name and optional allowed origins.
+Go to **Community Settings > Integrations > SDK Access** and click **Create SDK Key**. Enter a name and optional allowed origins (required in production; localhost is auto-allowed in dev).
 
 The dashboard will display your `accessId` and `accessKey`. The `accessKey` is shown **once only** — save it securely.
 
 Store both values in your server environment variables.
 
+> **Rotating or revoking keys:** The same dashboard page lists existing keys and lets you revoke or replace them. Revocation takes effect immediately for token issuance, and forces active sessions to re-auth on their next page load.
+
 **Step 2 — Exchange credentials for an embed token on every page load** (Node.js example):
 
 ```js
@@ -26,13 +28,22 @@ const response = await fetch('https://YOUR_API_URL/v2/api/widget-access-keys/tok
   body: JSON.stringify({
     accessId: process.env.RAI_ACCESS_ID,
     accessKey: process.env.RAI_ACCESS_KEY,
+    // userIdentifiers keys MUST be `data-*` prefixed — they match the
+    // `dataAttribute` value of each field configured in your widget's
+    // User Identifier Fields (e.g. the dashboard stores "data-email",
+    // "data-user-id", not bare "email"/"userId").
+    userIdentifiers: {
+      'data-user-id': [YourUserObject].id,
+      'data-email': [YourUserObject].email,
+      // ...any other fields configured for this widget
+    },
   }),
 })
 const { data } = await response.json()
-// data.embedToken expires in 15 minutes
+// data.embedToken expires in 15 minutes and carries signed identity claims
 ```
 
-**Step 3 — Embed** (only the short-lived token appears in HTML):
+**Step 3 — Embed** (only the short-lived token appears in HTML — no identity attributes):
 
 ```html
 <div id="returning-ai-widget-YOUR_WIDGET_ID" style="width:100%;height:600px"></div>
@@ -40,14 +51,14 @@ const { data } = await response.json()
   data-widget-id="YOUR_WIDGET_ID"
   data-widget-type="store"
   data-theme="dark"
-  data-email="user@example.com"
   data-embed-token="eyJ..."
-  api-url="YOUR_API_URL"
   widget-url="YOUR_WIDGET_URL"
 ></script>
 ```
 
-The SDK validates the token on widget load. If the token is expired or invalid, the widget shows an error screen. Tokens expire after 15 minutes — regenerate on each page render.
+`api-url` is optional. The SDK resolves the widget server from `domain-key` when provided and uses production by default; pass `api-url` only if you need to override the widget auth server.
+
+The server validates the token and extracts identity from its signed claims. If the token is expired, invalid, or its identifiers don't satisfy the widget's configured User Identifier Fields, the widget shows an error screen. Tokens expire after 15 minutes — regenerate on each page render.
 
 ---
 
@@ -81,6 +92,8 @@ Set the `data-widget-type` attribute to choose which widget to display. The Widg
 | `referral-conditions` | Referral widget |
 | `custom` | Custom widget |
 
+All examples below use **Access Key Embed** (recommended) — identity is signed into `data-embed-token` server-side per the [Quick Start](#quick-start). Swap `data-embed-token="eyJ..."` for `data-*` identifier attributes if you want [Public Embed](#user-identifier-attributes) instead.
+
 ### Store widget
 
 ```html
@@ -89,8 +102,7 @@ Set the `data-widget-type` attribute to choose which widget to display. The Widg
   data-widget-id="YOUR_WIDGET_ID"
   data-widget-type="store"
   data-theme="dark"
-  data-email="user@example.com"
-  api-url="YOUR_API_URL"
+  data-embed-token="eyJ..."
   widget-url="YOUR_WIDGET_URL"
 ></script>
 ```
@@ -103,8 +115,7 @@ Set the `data-widget-type` attribute to choose which widget to display. The Widg
   data-widget-id="YOUR_WIDGET_ID"
   data-widget-type="channel"
   data-theme="dark"
-  data-email="user@example.com"
-  api-url="YOUR_API_URL"
+  data-embed-token="eyJ..."
   widget-url="YOUR_WIDGET_URL"
 ></script>
 ```
@@ -119,8 +130,7 @@ Set the `data-widget-type` attribute to choose which widget to display. The Widg
   data-widget-id="YOUR_WIDGET_ID"
   data-widget-type="social"
   data-theme="dark"
-  data-email="user@example.com"
-  api-url="YOUR_API_URL"
+  data-embed-token="eyJ..."
   widget-url="YOUR_WIDGET_URL"
 ></script>
 ```
@@ -133,8 +143,7 @@ Set the `data-widget-type` attribute to choose which widget to display. The Widg
   data-widget-id="YOUR_WIDGET_ID"
   data-widget-type="milestone"
   data-theme="dark"
-  data-email="user@example.com"
-  api-url="YOUR_API_URL"
+  data-embed-token="eyJ..."
   widget-url="YOUR_WIDGET_URL"
 ></script>
 ```
@@ -147,12 +156,13 @@ Set the `data-widget-type` attribute to choose which widget to display. The Widg
   data-widget-id="YOUR_WIDGET_ID"
   data-widget-type="custom"
   data-theme="dark"
-  data-email="user@example.com"
-  api-url="YOUR_API_URL"
+  data-embed-token="eyJ..."
   widget-url="YOUR_WIDGET_URL"
 ></script>
 ```
 
+> **Custom widgets:** `YOUR_WIDGET_ID` is the base64-encoded `_id` of the CustomWidget record (not the community ID). The custom element variant `<rai-custom-widget widget-id="...">` uses this same base64 value — it's the one widget type where raw ObjectIds are not accepted.
+
 ---
 
 ## Attributes
@@ -170,18 +180,20 @@ All attributes can be provided with or without the `data-` prefix — both work.
 |-----------|----------|---------|-------------|
 | `data-widget-id` | **Yes** | — | Your widget ID (from dashboard) |
 | `data-widget-type` | **Yes** | `store` | Widget type (see table above) |
-| `api-url` | **Yes**\* | — | Auth API base URL (from dashboard) |
+| `api-url` | No | Production widget server | Optional widget auth server override. Defaults from `domain-key` when provided |
 | `widget-url` | **Yes**\* | — | Widget URL (from dashboard). \*Not required when using `data-bundle-url` |
 | `data-bundle-url` | No | — | URL to the widget IIFE bundle — triggers [bundle mode](#bundle-mode) (non-iframe) |
-| `data-domain-key` | Bundle mode | — | Environment key: `SGTR`, `STG`, or `PROD`. Required for bundle mode on external sites |
+| `data-domain-key` | No | `PROD` | Environment key: `SGTR`, `STG`, or `PROD`. Used to resolve default environment URLs when overrides are omitted |
 | `data-theme` | No | `light` | `light` or `dark` |
-| `data-email` | Recommended | — | User's email for identification |
-| `data-embed-token` | Access Key only | — | Short-lived token from your server |
+| `data-email` | Public Embed only | — | User's email for identification. **Access Key Embed:** omit — identity is signed into `data-embed-token` |
+| `data-embed-token` | Access Key Embed only | — | Short-lived JWT from your server. Carries signed user identifiers — no `data-*` identifier attributes needed |
 | `data-locale` | No | — | BCP 47 locale tag (e.g. `fr-FR`) |
-| `data-eager` | No | — | Load immediately instead of waiting until visible |
+| `data-eager` | No | — | Load immediately instead of waiting until visible (presence-based boolean) |
 | `data-auto-refresh` | No | `true` | Auto-refresh access token before expiry |
 | `data-debug` | No | `false` | Verbose console logging |
 | `data-custom-data` | No | — | JSON object forwarded to the widget |
+| `data-retry-label` | No | `Retry` | Label text for the retry button on the error screen |
+| `data-v2-api-url` | No | Domain-key default | Optional V2 API override for bundle mode. Safe to omit for standard environments |
 
 ### Custom element attributes
 
@@ -189,20 +201,22 @@ All attributes can be provided with or without the `data-` prefix — both work.
 |-----------|----------|---------|-------------|
 | `community-id` | **Yes**\* | — | Your community ID (raw ObjectId from dashboard). \*Custom widgets use `widget-id` instead |
 | `channel-id` | **Channel only** | — | Channel ID (raw ObjectId) — required for `<rai-channel-widget>` |
-| `api-url` | **Yes** | — | Auth API base URL (from dashboard) |
+| `api-url` | No | Production widget server | Optional widget auth server override. Defaults from `domain-key` when provided |
 | `widget-url` | **Yes**\* | — | Widget URL (from dashboard). \*Not required when using `bundle-url` |
 | `bundle-url` | No | — | URL to the widget IIFE bundle — triggers [bundle mode](#bundle-mode) (non-iframe) |
-| `domain-key` | Bundle mode | — | Environment key: `SGTR`, `STG`, or `PROD`. Required for bundle mode on external sites |
+| `domain-key` | No | `PROD` | Environment key: `SGTR`, `STG`, or `PROD`. Used to resolve default environment URLs when overrides are omitted |
 | `theme` | No | `light` | `light` or `dark` |
-| `data-email` | Recommended | — | User's email for identification |
-| `embed-token` | Access Key only | — | Short-lived token from your server |
+| `data-email` | Public Embed only | — | User's email for identification. **Access Key Embed:** omit — identity is signed into `embed-token` |
+| `embed-token` | Access Key Embed only | — | Short-lived JWT from your server. Carries signed user identifiers — no `data-*` identifier attributes needed |
 | `width` | No | `100%` | CSS width |
 | `height` | No | `600px` | CSS height |
 | `locale` | No | — | BCP 47 locale tag (e.g. `fr-FR`) |
-| `eager` | No | — | Load immediately instead of waiting until visible |
+| `eager` | No | — | Load immediately instead of waiting until visible (presence-based boolean) |
 | `auto-refresh` | No | `true` | Auto-refresh access token before expiry |
 | `debug` | No | `false` | Verbose console logging |
 | `custom-data` | No | — | JSON object forwarded to the widget |
+| `retry-label` | No | `Retry` | Label text for the retry button on the error screen |
+| `v2-api-url` | No | Domain-key default | Optional V2 API override for bundle mode. Safe to omit for standard environments |
 
 > **`widget-id` vs `community-id`:** The script-tag method uses `data-widget-id` which is a pre-encoded identifier (base64). The custom element method uses raw ObjectIds — `community-id` for most widget types, plus `channel-id` for channel widgets. The SDK handles the encoding internally.
 
@@ -218,21 +232,23 @@ Custom elements don't need a container div — they size themselves using `width
 
 ### User Identifier Attributes
 
-Pass any `data-*` attribute to identify the current user. Which identifiers are available is configured per community in your dashboard.
+> **Access Key Embed:** Do **not** put identifiers in HTML. Pass them inside the `userIdentifiers` object when exchanging your access credentials for an embed token (Step 2). Identity is cryptographically signed into the token so it cannot be tampered with from the browser.
+>
+> **Public Embed:** Pass any `data-*` attribute to identify the current user. Which identifiers are available is configured per community in your dashboard.
 
 ```html
+<!-- Public Embed — identifiers in HTML -->
 <script src="https://unpkg.com/@returningai/widget-sdk/dist/rai-widget.iife.js"
   data-widget-id="YOUR_WIDGET_ID"
   data-widget-type="store"
   data-email="user@example.com"
   data-user-id="12345"
   data-account-id="abc"
-  api-url="YOUR_API_URL"
   widget-url="YOUR_WIDGET_URL"
 ></script>
 ```
 
-Any `data-*` attribute not reserved by the SDK is forwarded to the auth API as a user identifier.
+In Public Embed mode, any `data-*` attribute not reserved by the SDK is forwarded to the auth API as a user identifier.
 
 ---
 
@@ -240,7 +256,12 @@ Any `data-*` attribute not reserved by the SDK is forwarded to the auth API as a
 
 When you set the `bundle-url` attribute, the widget renders directly in the page DOM instead of inside an iframe. This gives full CSS cascade — `html[data-theme]` and Tailwind classes apply to the widget content naturally.
 
-`widget-url` is not needed in bundle mode. `domain-key` is required so the widget resolves the correct environment URLs.
+- `widget-url` is **not** needed in bundle mode (the widget is loaded directly from `bundle-url`).
+- `api-url` is optional. The SDK resolves the widget auth server from `domain-key` when provided, or defaults to production.
+- `domain-key` is optional. When omitted, the SDK defaults to production (`PROD`).
+- Environment URL variables such as `window.api_url` are optional overrides. Standard `SGTR`, `STG`, and `PROD` environments resolve from `domain-key`.
+
+Both examples below use Access Key Embed and target staging. Omit `domain-key` for production.
 
 ```html
 <!-- Script-tag approach -->
@@ -249,20 +270,18 @@ When you set the `bundle-url` attribute, the widget renders directly in the page
   data-widget-id="YOUR_WIDGET_ID"
   data-widget-type="store"
   data-theme="dark"
-  data-email="user@example.com"
+  data-embed-token="eyJ..."
   data-bundle-url="YOUR_BUNDLE_URL"
-  data-domain-key="YOUR_DOMAIN_KEY"
-  api-url="YOUR_API_URL"
+  data-domain-key="STG"
   data-eager
 ></script>
 
 <!-- Custom element approach -->
 <rai-store-widget
   community-id="YOUR_COMMUNITY_ID"
-  api-url="YOUR_API_URL"
   bundle-url="YOUR_BUNDLE_URL"
-  domain-key="YOUR_DOMAIN_KEY"
-  data-email="user@example.com"
+  domain-key="STG"
+  embed-token="eyJ..."
   theme="dark"
   width="100%"
   height="100vh"
@@ -288,7 +307,9 @@ The bundle must export a `mount(container, config)` function on its global (e.g.
 
 ## Framework Usage (Custom Elements)
 
-When using a frontend framework (React, Vue, Angular), you can use custom HTML element tags instead of the script-tag method. Custom elements use raw IDs (`community-id`, `channel-id`) instead of the pre-encoded `data-widget-id`.
+When using a frontend framework (React, Vue, Angular), you can use custom HTML element tags instead of the script-tag method. Custom elements use raw ObjectIds (`community-id`, `channel-id`) instead of the pre-encoded `data-widget-id` — the SDK handles the encoding internally. (Exception: `<rai-custom-widget>` uses `widget-id` with a base64-encoded value — see the [attributes table](#custom-element-attributes).)
+
+All examples below use **Access Key Embed** — pass the short-lived token your server minted into `embed-token`. For [Public Embed](#user-identifier-attributes), replace `embed-token` with `data-*` identifier attributes.
 
 ### Plain HTML
 
@@ -299,8 +320,7 @@ When using a frontend framework (React, Vue, Angular), you can use custom HTML e
 <rai-store-widget
   community-id="YOUR_COMMUNITY_ID"
   theme="dark"
-  data-email="user@example.com"
-  api-url="YOUR_API_URL"
+  embed-token="eyJ..."
   widget-url="YOUR_WIDGET_URL"
 ></rai-store-widget>
 
@@ -309,8 +329,7 @@ When using a frontend framework (React, Vue, Angular), you can use custom HTML e
   community-id="YOUR_COMMUNITY_ID"
   channel-id="YOUR_CHANNEL_ID"
   theme="dark"
-  data-email="user@example.com"
-  api-url="YOUR_API_URL"
+  embed-token="eyJ..."
   widget-url="YOUR_WIDGET_URL"
 ></rai-channel-widget>
 ```
@@ -322,26 +341,24 @@ Types are included — no manual JSX declarations needed.
 ```tsx
 import '@returningai/widget-sdk'
 
-export function StoreEmbed({ email }: { email: string }) {
+export function StoreEmbed({ embedToken }: { embedToken: string }) {
   return (
     <rai-store-widget
       community-id="YOUR_COMMUNITY_ID"
       theme="dark"
-      data-email={email}
-      api-url="YOUR_API_URL"
+      embed-token={embedToken}
       widget-url="YOUR_WIDGET_URL"
     />
   )
 }
 
-export function ChannelEmbed({ email }: { email: string }) {
+export function ChannelEmbed({ embedToken }: { embedToken: string }) {
   return (
     <rai-channel-widget
       community-id="YOUR_COMMUNITY_ID"
       channel-id="YOUR_CHANNEL_ID"
       theme="dark"
-      data-email={email}
-      api-url="YOUR_API_URL"
+      embed-token={embedToken}
       widget-url="YOUR_WIDGET_URL"
     />
   )
@@ -353,6 +370,7 @@ export function ChannelEmbed({ email }: { email: string }) {
 ```vue
 <script setup>
 import '@returningai/widget-sdk'
+defineProps({ embedToken: String })
 </script>
 
 <template>
@@ -360,8 +378,7 @@ import '@returningai/widget-sdk'
   <rai-store-widget
     community-id="YOUR_COMMUNITY_ID"
     theme="dark"
-    :data-email="user.email"
-    api-url="YOUR_API_URL"
+    :embed-token="embedToken"
     widget-url="YOUR_WIDGET_URL"
   />
 
@@ -370,8 +387,7 @@ import '@returningai/widget-sdk'
     community-id="YOUR_COMMUNITY_ID"
     channel-id="YOUR_CHANNEL_ID"
     theme="dark"
-    :data-email="user.email"
-    api-url="YOUR_API_URL"
+    :embed-token="embedToken"
     widget-url="YOUR_WIDGET_URL"
   />
 </template>
@@ -392,8 +408,7 @@ import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'
 <rai-store-widget
   community-id="YOUR_COMMUNITY_ID"
   theme="dark"
-  [attr.data-email]="user.email"
-  api-url="YOUR_API_URL"
+  [attr.embed-token]="embedToken"
   widget-url="YOUR_WIDGET_URL"
 ></rai-store-widget>
 
@@ -402,8 +417,7 @@ import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'
   community-id="YOUR_COMMUNITY_ID"
   channel-id="YOUR_CHANNEL_ID"
   theme="dark"
-  [attr.data-email]="user.email"
-  api-url="YOUR_API_URL"
+  [attr.embed-token]="embedToken"
   widget-url="YOUR_WIDGET_URL"
 ></rai-channel-widget>
 ```
@@ -431,7 +445,7 @@ Listen for widget lifecycle events:
 | `rai-authenticated` | `{}` | Auth succeeded, before widget mounts |
 | `rai-ready` | `{}` | `WIDGET_READY` received, loader hidden (iframe mode) |
 | `rai-mounted` | `{}` | Widget bundle mounted successfully (bundle mode) |
-| `rai-error` | `{ message }` | Auth failed after all retries |
+| `rai-error` | `{ message, hint?, status? }` | Auth failed after all retries. `message` is the backend error text (e.g. `"Invalid or expired embed token"`), `hint` is the optional human-readable suggestion, `status` is the HTTP status code of the failing response. |
 | `rai-logout` | `{}` | Widget logged out |
 | `rai-height-change` | `{ height }` | iframe resized (after debounce) |
 
@@ -445,7 +459,7 @@ const widget = document.querySelector('rai-store-widget')
 widget.addEventListener('rai-authenticated', () => { /* auth succeeded */ })
 widget.addEventListener('rai-ready',         () => { /* widget loaded and visible (iframe mode) */ })
 widget.addEventListener('rai-mounted',       () => { /* widget mounted (bundle mode) */ })
-widget.addEventListener('rai-error',         (e) => console.error(e.detail.message))
+widget.addEventListener('rai-error',         (e) => console.error(e.detail.status, e.detail.message, e.detail.hint))
 widget.addEventListener('rai-logout',        () => { /* user logged out */ })
 widget.addEventListener('rai-height-change', (e) => console.log(e.detail.height))
 ```