@algolia/wizard 0.17.0 → 0.18.0

package/dist/main.js

@@ -3604,7 +3604,7 @@ async function runAnalysis(mode, extraInstructions = []) {
 // package.json
 var package_default = {
   name: "@algolia/wizard",
-  version: "0.17.0",
+  version: "0.18.0",
   description: "Magically implement Algolia functionality in your codebase",
   type: "module",
   engines: {
@@ -4429,7 +4429,7 @@ function searchInstructions(input) {
     "Implement an in-app Algolia search experience.",
     `Build the search UI for ${input.searchUiTarget}.`,
     ...doc ? [
-      "Follow the Algolia SDK reference below for client setup and search UI wiring; prefer it over prior knowledge:",
+      "Follow the Algolia SDK reference below for client setup, search UI wiring, and Insights instrumentation \u2014 Insights is required, not optional; prefer the reference over prior knowledge:",
       doc
     ] : [
       "No bundled Algolia SDK reference exists for this stack, so rely on the project's own conventions and Algolia's official client for its language. Do not invent APIs \u2014 keep to the documented search endpoint and its parameters."

package/docs/algolia-sdk/README.md

@@ -27,6 +27,7 @@ Always install the **latest stable** within the major (use a caret range like `^
   client cache and causes re-renders.
 - For InstantSearch, import the client from `algoliasearch/lite` (smaller bundle and
   correct types — see `instantsearch-setup.md`).
+- Always enable **Insights** on the InstantSearch root with `insights: true`. Without it there are no click/conversion events, so many Algolia features will not work as expected.
 
 ## Files
 

package/docs/algolia-sdk/instantsearch-setup-js.md

@@ -22,7 +22,11 @@ import { searchBox, hits } from 'instantsearch.js/es/widgets'
 
 const searchClient = algoliasearch(APP_ID, SEARCH_ONLY_KEY)
 
-const search = instantsearch({ indexName: 'INDEX_NAME', searchClient })
+const search = instantsearch({
+  indexName: 'INDEX_NAME',
+  searchClient,
+  insights: true,
+})
 
 search.addWidgets([
   searchBox({ container: '#searchbox' }),
@@ -32,6 +36,122 @@ search.addWidgets([
 search.start()
 ```
 
+## Insights (click analytics) — always enable it
+
+The `insights` option turns on the Insights middleware (`instantsearch.js` v4.55+),
+which adds `clickAnalytics: true` to every query and keeps the `userToken` in sync
+between search and event calls. Never set `clickAnalytics` or `userToken` on the `configure` widget by hand.
+
+Use `insights: true`. The middleware loads `search-insights` from the jsDelivr CDN
+itself; do not install the package or pass `insightsClient`.
+
+If a Content-Security-Policy blocks jsDelivr, the CDN script cannot load. In that
+case, install `search-insights` from npm and pass its default export as
+`insightsClient` in the `insights` option:
+
+```js
+import aa from 'search-insights'
+
+const search = instantsearch({
+  indexName: 'INDEX_NAME',
+  searchClient,
+  insights: { insightsClient: aa },
+})
+```
+
+The middleware calls `aa('init', ...)` itself with the app ID and search key, so no
+manual `init` call is needed. Keep using the `insightsInitParams` option (for
+example `useCookie`) the same way as with the CDN path.
+
+The middleware sets an anonymous `userToken` itself, so events fire with no extra
+code. That token lives in memory only — a page reload starts a new one, which is
+enough for search→click attribution within a session but not across sessions, and not
+enough for Personalization to build a profile. To persist it in the first-party
+`_ALGOLIA` cookie, switch to the object form — only where the app's cookie-consent
+policy allows it:
+
+```js
+insights: {
+  insightsInitParams: {
+    useCookie: true
+  }
+}
+```
+
+### Click and conversion events
+
+The `hits` and `infiniteHits` widgets send `view` and `click` events on their own. A
+custom `item` template whose click target is your own element gets `sendEvent` as the
+second argument:
+
+```js
+hits({
+  container: '#hits',
+  templates: {
+    item(hit, { html, sendEvent }) {
+      return html`<a
+        href="${hit.url}"
+        onClick="${() => sendEvent('click', hit, 'Hit Clicked')}"
+        >${hit.name}</a
+      >`
+    },
+  },
+})
+```
+
+Conversions are business actions (add to cart, signup, booking), so wire them at the
+real action, not at render:
+
+```js
+sendEvent('conversion', hit, 'Product Added To Cart', {
+  eventSubtype: 'addToCart',
+  objectData: [{ price: hit.price, quantity: 1 }],
+  value: hit.price,
+  currency: 'USD',
+})
+```
+
+Where the app has no such action on a search hit, leave a TODO at the best
+candidate instead of inventing one.
+
+Connector-based custom widgets get `sendEvent` in their render options, and unlike
+the widgets above they send **no** click events automatically — wire them yourself.
+
+### Authenticated users
+
+Anonymous tokens need no code. When the app already has a stable user id, link it
+after login and clear it on logout — the anonymous `userToken` keeps flowing
+alongside it (Personalization uses that one, not the authenticated token):
+
+```js
+if (typeof window !== 'undefined') {
+  window.aa('setAuthenticatedUserToken', userId)
+}
+```
+
+```js
+if (typeof window !== 'undefined') {
+  window.aa('setAuthenticatedUserToken', undefined) // on logout
+}
+```
+
+The middleware installs `window.aa` as a queue before the CDN script arrives, so these
+calls need no load-order guard. Under a server-side rendering framework (Angular
+Universal, SvelteKit), `window` does not exist on the server, so `window.aa` throws
+unless you add this guard or call it only from client-side code. In TypeScript
+nothing augments `Window`, so declare it once:
+`declare global { interface Window { aa: (method: string, ...args: unknown[]) => void } }`.
+
+With the npm `insightsClient` fallback, call the same method on the imported `aa`
+function instead of `window.aa`:
+
+```js
+import aa from 'search-insights'
+
+aa('setAuthenticatedUserToken', userId)
+aa('setAuthenticatedUserToken', undefined) // on logout
+```
+
 ## Frameworks without their own flavor
 
 Only React and Vue have a maintained InstantSearch wrapper. For any other

package/docs/algolia-sdk/instantsearch-setup-react.md

@@ -28,7 +28,11 @@ const searchClient = algoliasearch(
 
 export function Search() {
   return (
-    <InstantSearch searchClient={searchClient} indexName="INDEX_NAME">
+    <InstantSearch
+      searchClient={searchClient}
+      indexName="INDEX_NAME"
+      insights={true}
+    >
       <SearchBox />
       <Hits />
     </InstantSearch>
@@ -37,3 +41,111 @@ export function Search() {
 ```
 
 Do not inline `searchClient={algoliasearch(...)}` — keep the stable reference above.
+
+## Insights (click analytics) — always enable it
+
+The `insights` prop turns on the Insights middleware, which adds
+`clickAnalytics: true` to every query and keeps the `userToken` in sync between search
+and event calls. Never set `clickAnalytics` or `userToken` on `<Configure>` by hand.
+
+Use `insights={true}`. The middleware loads `search-insights` from the jsDelivr CDN
+itself; do not install the package or pass `insightsClient`.
+
+If a Content-Security-Policy blocks jsDelivr, the CDN script cannot load. In that
+case, install `search-insights` from npm and pass its default export as
+`insightsClient`:
+
+```tsx
+import aa from 'search-insights'
+
+<InstantSearch insights={{ insightsClient: aa }} />
+```
+
+The middleware calls `aa('init', ...)` itself with the app ID and search key, so no
+manual `init` call is needed. Keep using the `insightsInitParams` option (for
+example `useCookie`) the same way as with the CDN path.
+
+The middleware sets an anonymous `userToken` itself, so events fire with no extra
+code. That token lives in memory only — a page reload starts a new one, which is
+enough for search→click attribution within a session but not across sessions, and not
+enough for Personalization to build a profile. To persist it in the first-party
+`_ALGOLIA` cookie, switch to the object form — only where the app's cookie-consent
+policy allows it:
+
+```tsx
+<InstantSearch insights={{ insightsInitParams: { useCookie: true } }} />
+```
+
+### Click and conversion events
+
+`<Hits>` and `<InfiniteHits>` send `view` and `click` events on their own. Two cases
+need explicit wiring:
+
+- A custom `hitComponent` whose click target is your own element — it receives a
+  `sendEvent` prop.
+- `useHits` / `useInfiniteHits`: `view` is automatic, `click` is **not**.
+
+```tsx
+function Hit({ hit, sendEvent }) {
+  return (
+    <a href={hit.url} onClick={() => sendEvent('click', hit, 'Hit Clicked')}>
+      {hit.name}
+    </a>
+  )
+}
+```
+
+Conversions are business actions (add to cart, signup, booking), so wire them at the
+real action, not at render:
+
+```tsx
+sendEvent('conversion', hit, 'Product Added To Cart', {
+  eventSubtype: 'addToCart',
+  objectData: [{ price: hit.price, quantity: 1 }],
+  value: hit.price,
+  currency: 'USD',
+})
+```
+
+Where the app has no such action on a search hit, leave a TODO at the best
+candidate instead of inventing one.
+
+### Authenticated users
+
+Anonymous tokens need no code. When the app already has a stable user id, link it
+after login and clear it on logout — the anonymous `userToken` keeps flowing
+alongside it (Personalization uses that one, not the authenticated token):
+
+```ts
+// `search-insights` is CDN-loaded, so nothing augments Window — declare it once.
+declare global {
+  interface Window {
+    aa: (method: string, ...args: unknown[]) => void
+  }
+}
+
+if (typeof window !== 'undefined') {
+  window.aa('setAuthenticatedUserToken', userId)
+}
+```
+
+```ts
+if (typeof window !== 'undefined') {
+  window.aa('setAuthenticatedUserToken', undefined) // on logout
+}
+```
+
+The middleware installs `window.aa` as a queue before the CDN script arrives, so these
+calls need no load-order guard. Under Next.js SSR (and React Server Components),
+`window` does not exist on the server, so `window.aa` throws unless you add this
+guard or call it only from a client-side hook such as `useEffect`.
+
+With the npm `insightsClient` fallback, call the same method on the imported `aa`
+function instead of `window.aa`:
+
+```ts
+import aa from 'search-insights'
+
+aa('setAuthenticatedUserToken', userId)
+aa('setAuthenticatedUserToken', undefined) // on logout
+```

package/docs/algolia-sdk/instantsearch-setup-vue.md

@@ -17,7 +17,11 @@ const searchClient = algoliasearch(APP_ID, SEARCH_ONLY_KEY)
 
 ```vue
 <template>
-  <ais-instant-search :search-client="searchClient" index-name="INDEX_NAME">
+  <ais-instant-search
+    :search-client="searchClient"
+    index-name="INDEX_NAME"
+    :insights="true"
+  >
     <ais-search-box />
     <ais-hits />
   </ais-instant-search>
@@ -39,3 +43,99 @@ Register the widgets via the InstantSearch Vue plugin in your app entry:
 import InstantSearch from 'vue-instantsearch/vue3/es'
 app.use(InstantSearch)
 ```
+
+## Insights (click analytics) — always enable it
+
+The `insights` prop turns on the Insights middleware, which adds
+`clickAnalytics: true` to every query and keeps the `userToken` in sync between search
+and event calls. Never set `clickAnalytics` or `userToken` on `ais-configure` by hand.
+
+Use `:insights="true"`. The middleware loads `search-insights` from the jsDelivr CDN itself; do not install
+the package or pass `insightsClient`.
+
+If a Content-Security-Policy blocks jsDelivr, the CDN script cannot load. In that
+case, install `search-insights` from npm and pass its default export as
+`insightsClient`:
+
+```js
+import aa from 'search-insights'
+const insights = { insightsClient: aa } // then :insights="insights"
+```
+
+The middleware calls `aa('init', ...)` itself with the app ID and search key, so no
+manual `init` call is needed.
+
+The middleware sets an anonymous `userToken` itself, so events fire with no extra
+code. That token lives in memory only — a page reload starts a new one, which is
+enough for search→click attribution within a session but not across sessions, and not
+enough for Personalization to build a profile. To persist it in the first-party
+`_ALGOLIA` cookie, bind the object form — only where the app's cookie-consent policy
+allows it:
+
+```js
+const insights = { insightsInitParams: { useCookie: true } } // then :insights="insights"
+```
+
+### Click and conversion events
+
+`ais-hits` sends `view` and `click` events on its own. A custom `item` slot whose
+click target is your own element needs the slot's `sendEvent`:
+
+```vue
+<ais-hits>
+  <template v-slot:item="{ item, sendEvent }">
+    <a :href="item.url" @click="sendEvent('click', item, 'Hit Clicked')">
+      {{ item.name }}
+    </a>
+  </template>
+</ais-hits>
+```
+
+Conversions are business actions (add to cart, signup, booking), so wire them at the
+real action, not at render:
+
+```js
+sendEvent('conversion', item, 'Product Added To Cart', {
+  eventSubtype: 'addToCart',
+  objectData: [{ price: item.price, quantity: 1 }],
+  value: item.price,
+  currency: 'USD',
+})
+```
+
+Where the app has no such action on a search hit, leave a TODO at the best
+candidate instead of inventing one.
+
+### Authenticated users
+
+Anonymous tokens need no code. When the app already has a stable user id, link it
+after login and clear it on logout — the anonymous `userToken` keeps flowing
+alongside it (Personalization uses that one, not the authenticated token):
+
+```js
+if (typeof window !== 'undefined') {
+  window.aa('setAuthenticatedUserToken', userId)
+}
+```
+
+```js
+if (typeof window !== 'undefined') {
+  window.aa('setAuthenticatedUserToken', undefined) // on logout
+}
+```
+
+The middleware installs `window.aa` as a queue before the CDN script arrives, so these
+calls need no load-order guard. Under Nuxt SSR, `window` does not exist on the server,
+so `window.aa` throws unless you add this guard or call it only from a client-side
+hook such as `onMounted`. In TypeScript nothing augments `Window`, so declare it
+once: `declare global { interface Window { aa: (method: string, ...args: unknown[]) => void } }`.
+
+With the npm `insightsClient` fallback, call the same method on the imported `aa`
+function instead of `window.aa`:
+
+```js
+import aa from 'search-insights'
+
+aa('setAuthenticatedUserToken', userId)
+aa('setAuthenticatedUserToken', undefined) // on logout
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@algolia/wizard",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Magically implement Algolia functionality in your codebase",
   "type": "module",
   "engines": {