@constructor-io/constructorio-ui-pia 2.15.0 → 2.16.1
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 +50 -12
- package/dist/constructorio-ui-pia-bundled.js +45 -45
- package/lib/cjs/components/CioPia/CioPiaQna.js +11 -3
- package/lib/cjs/components/ConversationHistory/ConversationHistory.js +7 -2
- package/lib/cjs/hooks/useConversation.js +41 -6
- package/lib/cjs/version.js +1 -1
- package/lib/mjs/components/CioPia/CioPiaQna.js +11 -3
- package/lib/mjs/components/ConversationHistory/ConversationHistory.js +7 -3
- package/lib/mjs/hooks/useConversation.js +39 -4
- package/lib/mjs/version.js +1 -1
- package/lib/types/components/CioPia/types.d.ts +10 -1
- package/lib/types/hooks/useConversation.d.ts +2 -1
- package/lib/types/types.d.ts +5 -0
- package/lib/types/version.d.ts +1 -1
- package/package.json +3 -1
package/README.md
CHANGED
|
@@ -116,18 +116,19 @@ omitting it would quietly put everyone in the test arm with no control group to
|
|
|
116
116
|
|
|
117
117
|
#### Configuration Options
|
|
118
118
|
|
|
119
|
-
| Prop
|
|
120
|
-
|
|
|
121
|
-
| `apiKey`
|
|
122
|
-
| `itemId`
|
|
123
|
-
| `variationId`
|
|
124
|
-
| `threadId`
|
|
125
|
-
| `
|
|
126
|
-
| `
|
|
127
|
-
| `
|
|
128
|
-
| `
|
|
129
|
-
| `
|
|
130
|
-
| `
|
|
119
|
+
| Prop | Type | Description |
|
|
120
|
+
| ---------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
121
|
+
| `apiKey` | `string` | Your Constructor.io API key (required) |
|
|
122
|
+
| `itemId` | `string` | The product item ID (required) |
|
|
123
|
+
| `variationId` | `string` | Optional variation ID |
|
|
124
|
+
| `threadId` | `string` | Optional thread ID for conversation context (must be a valid UUID) |
|
|
125
|
+
| `initialConversationHistory` | `ConversationEntry[]` | A conversation you manage, shown before the first question and read once on mount. Conversation and modal modes only (see [Restoring a conversation](#restoring-a-conversation)) |
|
|
126
|
+
| `displayConfigs` | `object` | Display configuration options (see below) |
|
|
127
|
+
| `trackingConfigs` | `object` | Tracking configuration options (see below) |
|
|
128
|
+
| `callbacks` | `object` | Callback handlers for user interactions |
|
|
129
|
+
| `translations` | `object` | UI string translations for internationalization |
|
|
130
|
+
| `componentOverrides` | `object` | Custom component overrides |
|
|
131
|
+
| `abTest` | `object` | A/B test configuration — test cells for tracking, and a control-group placeholder (see below) |
|
|
131
132
|
|
|
132
133
|
**Display Configs:**
|
|
133
134
|
|
|
@@ -161,6 +162,43 @@ omitting it would quietly put everyone in the test arm with no control group to
|
|
|
161
162
|
| `onAddToCart` | `(item: Item, event: React.MouseEvent) => void` | Called when the "Add to Cart" button on a product card is clicked. Passing this callback is what renders the button; without it no cart control is shown |
|
|
162
163
|
| `onFeedback` | `(type: 'up' \| 'down') => void` | Called when the user submits positive or negative feedback on an answer |
|
|
163
164
|
|
|
165
|
+
#### Restoring a conversation
|
|
166
|
+
|
|
167
|
+
`initialConversationHistory` hands the conversation's history to you. Keep it wherever suits you, in the browser or on your own server. In conversation mode `onAnswer` receives the whole history after every answer, so save it per product along with the thread ID and pass both back to pick the conversation up where it left off:
|
|
168
|
+
|
|
169
|
+
```jsx
|
|
170
|
+
function ProductQuestions({ itemId }) {
|
|
171
|
+
// Your own loader: from browser storage, your server, or anywhere else.
|
|
172
|
+
const { isLoading, saved } = useSavedConversation(itemId);
|
|
173
|
+
|
|
174
|
+
// The history is read once, on mount, so wait for it.
|
|
175
|
+
if (isLoading) return null;
|
|
176
|
+
|
|
177
|
+
return (
|
|
178
|
+
<CioPia
|
|
179
|
+
key={itemId}
|
|
180
|
+
apiKey='YOUR_API_KEY'
|
|
181
|
+
itemId={itemId}
|
|
182
|
+
threadId={saved?.threadId}
|
|
183
|
+
initialConversationHistory={saved?.history ?? []}
|
|
184
|
+
displayConfigs={{ mode: 'conversation' }}
|
|
185
|
+
callbacks={{
|
|
186
|
+
onAnswer: (history, context) =>
|
|
187
|
+
saveConversation(context.itemId, { threadId: context.threadId, history }),
|
|
188
|
+
}}
|
|
189
|
+
/>
|
|
190
|
+
);
|
|
191
|
+
}
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
- Passing the prop, even as `[]`, means you manage the history. Pass `[]` when nothing is saved rather than leaving it out.
|
|
195
|
+
- The history is read once, on mount: render `CioPia` after your history has loaded, because a value that arrives later is ignored. Changing `itemId` clears it, so store it per product and remount with `key={itemId}` to load the next product's conversation.
|
|
196
|
+
- Pass the `threadId` the entries came from. The agent keeps the thread's context server-side, so history shown under a different thread is a transcript the agent does not remember.
|
|
197
|
+
- In `type: 'modal'` the entries appear in the dialog, which opens when the shopper asks their next question. Closing the modal clears them, as it does a live conversation.
|
|
198
|
+
- The suggested questions row shows the product's suggested questions, not the follow-ups from the last restored answer.
|
|
199
|
+
- Entries without a string `question` and `answer` are skipped with a console warning, and each entry's `id` is replaced with the widget's own numbering.
|
|
200
|
+
- It is ignored in `mode: 'default'`, which shows only the latest answer, in `mode: 'recommendations'`, and for the A/B control group (`abTest.isControl`).
|
|
201
|
+
|
|
164
202
|
### Using the JavaScript Bundle
|
|
165
203
|
|
|
166
204
|
This is a framework-agnostic method that can be used in any JavaScript project. The `CioPia` function provides a simple interface to inject the PIA component into the provided `selector`.
|