@constructor-io/constructorio-ui-asa 1.6.1 → 1.7.0

package/README.md

@@ -81,6 +81,7 @@ function ShoppingAgent() {
 |------|------|-------------|
 | `apiKey` | `string` | Your Constructor index key. Required unless you pass your own `cioClient`. |
 | `cioClient` | `ConstructorIOClient` | A pre-configured Constructor client. Provide this instead of `apiKey` when you need to customize client options (e.g. `serviceUrl`, `segments`, `userId`). |
+| `testCells` | `Record<string, string>` | A/B test cells to attach to tracking events, as `{ [testName]: cellName }`. See [A/B Testing](#ab-testing). |
 | `staticRequestConfigs` | `RequestConfigs` | Request-level config passed to the ASA agent. Defaults to `{ domain: 'chatbot' }`. |
 | `formatters` | `Formatters` | Override built-in formatters (e.g. `formatPrice`). Merged over the defaults. |
 | `urlHelpers` | `UrlHelpers` | Override built-in URL read/write helpers. Merged over the defaults. |
@@ -89,6 +90,34 @@ function ShoppingAgent() {
 
 > **Server-side rendering.** The Constructor client is only instantiated in the browser, so `Chat` and `useAsaResults` must run client-side only. In Next.js App Router, add `'use client'` and defer rendering until mounted (or load with `next/dynamic` and `{ ssr: false }`). See the [Integration Guide](https://constructor-io.github.io/constructorio-ui-asa/?path=/docs/general-integration-guide--variants) for a full example.
 
+### A/B Testing
+
+Attach test cells so ASA's tracking events can be attributed to a cell. Each entry is sent as its
+own `ef-<testName>` parameter, so a shopper in several concurrent tests carries every cell:
+
+```jsx
+<CioAsa
+  apiKey='YOUR_API_KEY'
+  testCells={{ constructorio: 'variant_a', your_other_test: 'variant_b' }}
+/>
+```
+
+The keys are your own test names, not values Constructor defines. Constructor's docs have the page
+set `window.cnstrc.testCell` to a bare cell name, which carries no test name of its own, so label
+it with yours:
+
+```jsx
+<CioAsa apiKey='YOUR_API_KEY' testCells={{ constructorio: window.cnstrc.testCell }} />
+```
+
+Some integrations expose a `window.cnstrc.testCells` map instead, which you can pass straight
+through. Empty and non-string values are dropped, so a cell read from a global that resolves to
+`undefined` is simply not sent.
+
+If you supply your own `cioClient`, that client owns its own options: set `testCells` there
+instead, as a `ConstructorIOClient` constructor option. `testCells` is ignored in that case, and
+passing both logs a warning rather than dropping the value silently.
+
 ### Using the Hook Directly
 
 For custom UI implementations, use the `useAsaResults` hook. It takes no arguments — all configuration comes from the surrounding `CioAsaProvider`.