@constructor-io/constructorio-ui-pia 2.14.0 → 2.16.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 +71 -35
- package/dist/constructorio-ui-pia-bundled.js +45 -45
- package/lib/cjs/components/CioPia/CheckoutTriggerBar.js +25 -0
- package/lib/cjs/components/CioPia/CioPiaQna.js +16 -4
- package/lib/cjs/components/CioPia/CioPiaStyles.css +33 -0
- package/lib/cjs/components/ConversationHistory/ConversationHistory.js +7 -2
- package/lib/cjs/components/PiaConversation/PiaConversation.js +2 -1
- package/lib/cjs/components/PiaConversation/PiaConversationStyles.css +5 -0
- package/lib/cjs/hooks/useConversation.js +41 -6
- package/lib/cjs/stories/assets/storybook-styles.css +12 -10
- package/lib/cjs/version.js +1 -1
- package/lib/mjs/components/CioPia/CheckoutTriggerBar.js +20 -0
- package/lib/mjs/components/CioPia/CioPiaQna.js +16 -4
- package/lib/mjs/components/CioPia/CioPiaStyles.css +33 -0
- package/lib/mjs/components/ConversationHistory/ConversationHistory.js +7 -3
- package/lib/mjs/components/PiaConversation/PiaConversation.js +2 -1
- package/lib/mjs/components/PiaConversation/PiaConversationStyles.css +5 -0
- package/lib/mjs/hooks/useConversation.js +39 -4
- package/lib/mjs/stories/assets/storybook-styles.css +12 -10
- package/lib/mjs/version.js +1 -1
- package/lib/types/components/CioPia/CheckoutTriggerBar.d.ts +11 -0
- package/lib/types/components/CioPia/index.d.ts +1 -1
- package/lib/types/components/CioPia/types.d.ts +52 -1
- package/lib/types/components/PiaConversation/PiaConversation.d.ts +3 -2
- package/lib/types/hooks/useConversation.d.ts +2 -1
- package/lib/types/index.d.ts +1 -1
- package/lib/types/types.d.ts +5 -0
- package/lib/types/version.d.ts +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -47,9 +47,7 @@ import CioPia from '@constructor-io/constructorio-ui-pia';
|
|
|
47
47
|
import '@constructor-io/constructorio-ui-pia/styles.css';
|
|
48
48
|
|
|
49
49
|
function YourComponent() {
|
|
50
|
-
return
|
|
51
|
-
<CioPia apiKey='YOUR_API_KEY' itemId='PRODUCT_ITEM_ID' />
|
|
52
|
-
);
|
|
50
|
+
return <CioPia apiKey='YOUR_API_KEY' itemId='PRODUCT_ITEM_ID' />;
|
|
53
51
|
}
|
|
54
52
|
```
|
|
55
53
|
|
|
@@ -118,50 +116,88 @@ omitting it would quietly put everyone in the test arm with no control group to
|
|
|
118
116
|
|
|
119
117
|
#### Configuration Options
|
|
120
118
|
|
|
121
|
-
| Prop
|
|
122
|
-
|
|
123
|
-
| `apiKey`
|
|
124
|
-
| `itemId`
|
|
125
|
-
| `variationId`
|
|
126
|
-
| `threadId`
|
|
127
|
-
| `
|
|
128
|
-
| `
|
|
129
|
-
| `
|
|
130
|
-
| `
|
|
131
|
-
| `
|
|
132
|
-
| `
|
|
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) |
|
|
133
132
|
|
|
134
133
|
**Display Configs:**
|
|
135
134
|
|
|
136
|
-
| Option
|
|
137
|
-
|
|
138
|
-
| `mode`
|
|
139
|
-
| `type`
|
|
140
|
-
| `showFeedback`
|
|
141
|
-
| `showPreviousItems` | `boolean`
|
|
142
|
-
| `learnMoreUrl`
|
|
135
|
+
| Option | Type | Default | Description |
|
|
136
|
+
| ------------------- | -------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------- |
|
|
137
|
+
| `mode` | `'default' \| 'conversation' \| 'recommendations'` | `'default'` | Display mode. `'recommendations'` is accepted by the type but not yet available — it renders nothing. |
|
|
138
|
+
| `type` | `'inline' \| 'modal'` | `'inline'` | Component type |
|
|
139
|
+
| `showFeedback` | `boolean` | `false` | Show feedback controls on answers |
|
|
140
|
+
| `showPreviousItems` | `boolean` | `true` | Show product carousels from previous conversation entries |
|
|
141
|
+
| `learnMoreUrl` | `string` | - | URL for the "Learn More" disclaimer link |
|
|
143
142
|
|
|
144
143
|
**Tracking Configs:**
|
|
145
144
|
|
|
146
|
-
| Option
|
|
147
|
-
|
|
148
|
-
| `viewThreshold` | `number` | `0.5`
|
|
145
|
+
| Option | Type | Default | Description |
|
|
146
|
+
| --------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
147
|
+
| `viewThreshold` | `number` | `0.5` | Fraction of the container (0–1) that must be visible before the `product_insights_agent.view` event fires. Lower it (e.g. `0.01`) to have the view event fire on minimal visibility. |
|
|
149
148
|
|
|
150
149
|
**AB Test:**
|
|
151
150
|
|
|
152
|
-
| Option
|
|
153
|
-
|
|
154
|
-
| `testCells` | `Record<string, string>` | -
|
|
155
|
-
| `isControl` | `boolean`
|
|
151
|
+
| Option | Type | Default | Description |
|
|
152
|
+
| ----------- | ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
153
|
+
| `testCells` | `Record<string, string>` | - | `{ [testName]: cellName }`, each sent as an `ef-<testName>` tracking parameter. Ignored when you supply your own `cioClient`. |
|
|
154
|
+
| `isControl` | `boolean` | required | Renders an invisible, tracking-only placeholder instead of the widget, so the control arm still records a view event. Takes precedence over `displayConfigs.mode`. |
|
|
156
155
|
|
|
157
156
|
**Callbacks:**
|
|
158
157
|
|
|
159
|
-
| Option
|
|
160
|
-
|
|
161
|
-
| `onQuestionSubmit`
|
|
162
|
-
| `onProductCardClick` | `(item: Item) => void`
|
|
163
|
-
| `onAddToCart`
|
|
164
|
-
| `onFeedback`
|
|
158
|
+
| Option | Type | Description |
|
|
159
|
+
| -------------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
160
|
+
| `onQuestionSubmit` | `(question: string) => void` | Called when a question is submitted (via Enter key, Send button, or suggested question click) |
|
|
161
|
+
| `onProductCardClick` | `(item: Item) => void` | Called when a product card in the carousel is clicked |
|
|
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 |
|
|
163
|
+
| `onFeedback` | `(type: 'up' \| 'down') => void` | Called when the user submits positive or negative feedback on an answer |
|
|
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`).
|
|
165
201
|
|
|
166
202
|
### Using the JavaScript Bundle
|
|
167
203
|
|