feat(api): allow insights options to be forwarded to Autocomplete (#1904)

* Allow insights options to be forwarded to Autocomplete

* Add autocomplete params to hits for insights

* Fixes TS errors after Autocomplete update

* Bump bundlesize after Autocomplete update

* Cleanup checking if insights is active

* Add documentation for sending events with DocSearch

* Move insights boolean casting to inside of getSources

* Update packages/docsearch-react/src/DocSearchModal.tsx

Co-authored-by: François Chalifour <[email protected]>

---------

Co-authored-by: François Chalifour <[email protected]>

Author: 8bittitan

bundlesize.config.json

@@ -6,11 +6,11 @@
     },
     {
       "path": "packages/docsearch-react/dist/umd/index.js",
-      "maxSize": "20.30 kB"
+      "maxSize": "22.47 kB"
     },
     {
       "path": "packages/docsearch-js/dist/umd/index.js",
-      "maxSize": "28.20 kB"
+      "maxSize": "30.33 kB"
     }
   ]
 }

examples/demo/src/App.js

@@ -12,6 +12,7 @@ function App() {
         indexName="docsearch"
         appId="R2IYF7ETH7"
         apiKey="599cec31baffa4868cae4e79f180729b"
+        insights
       />
     </div>
   );

package.json

@@ -25,6 +25,7 @@
     "cy:verify": "cypress verify",
     "lint:css": "stylelint **/src/**/*.css",
     "lint": "eslint --ext .js,.ts,.tsx .",
+    "playground:build": "yarn workspace @docsearch/react-example build",
     "playground:start": "yarn workspace @docsearch/react-example start",
     "playground-js:start": "yarn workspace @docsearch/js-example start",
     "release": "shipjs prepare",

packages/docsearch-react/package.json

@@ -33,8 +33,8 @@
     "watch": "watch \"yarn on:change\" --ignoreDirectoryPattern \"/dist/\""
   },
   "dependencies": {
-    "@algolia/autocomplete-core": "1.8.2",
-    "@algolia/autocomplete-preset-algolia": "1.8.2",
+    "@algolia/autocomplete-core": "1.9.2",
+    "@algolia/autocomplete-preset-algolia": "1.9.2",
     "@docsearch/css": "3.4.0",
     "algoliasearch": "^4.0.0"
   },

packages/docsearch-react/src/DocSearch.tsx

@@ -44,6 +44,7 @@ export interface DocSearchProps {
   navigator?: AutocompleteOptions<InternalDocSearchHit>['navigator'];
   translations?: DocSearchTranslations;
   getMissingResultsUrl?: ({ query }: { query: string }) => string;
+  insights?: AutocompleteOptions<InternalDocSearchHit>['insights'];
 }
 
 export function DocSearch(props: DocSearchProps) {

packages/docsearch-react/src/DocSearchModal.tsx

@@ -58,6 +58,7 @@ export function DocSearchModal({
   initialQuery: initialQueryFromProp = '',
   translations = {},
   getMissingResultsUrl,
+  insights = false,
 }: DocSearchModalProps) {
   const {
     footer: footerTranslations,
@@ -147,6 +148,7 @@ export function DocSearchModal({
             searchSuggestions: [],
           },
         },
+        insights,
         navigator,
         onStateChange(props) {
           setState(props.state);
@@ -171,7 +173,7 @@ export function DocSearchModal({
                   return item.url;
                 },
                 getItems() {
-                  return recentSearches.getAll();
+                  return recentSearches.getAll() as InternalDocSearchHit[];
                 },
               },
               {
@@ -187,12 +189,14 @@ export function DocSearchModal({
                   return item.url;
                 },
                 getItems() {
-                  return favoriteSearches.getAll();
+                  return favoriteSearches.getAll() as InternalDocSearchHit[];
                 },
               },
             ];
           }
 
+          const insightsActive = Boolean(insights);
+
           return searchClient
             .search<DocSearchHit>([
               {
@@ -224,6 +228,7 @@ export function DocSearchModal({
                   highlightPreTag: '<mark>',
                   highlightPostTag: '</mark>',
                   hitsPerPage: 20,
+                  clickAnalytics: insightsActive,
                   ...searchParameters,
                 },
               },
@@ -260,6 +265,19 @@ export function DocSearchModal({
 
               setContext({ nbHits });
 
+              let insightsParams = {};
+
+              if (insightsActive) {
+                insightsParams = {
+                  __autocomplete_indexName: indexName,
+                  __autocomplete_queryID: results[0].queryID,
+                  __autocomplete_algoliaCredentials: {
+                    appId,
+                    apiKey,
+                  },
+                };
+              }
+
               return Object.values<DocSearchHit[]>(sources).map(
                 (items, index) => {
                   return {
@@ -285,16 +303,23 @@ export function DocSearchModal({
                         .map(transformItems)
                         .map((groupedHits) =>
                           groupedHits.map((item) => {
+                            let parent: InternalDocSearchHit | null = null;
+
+                            const potentialParent = groupedHits.find(
+                              (siblingItem) =>
+                                siblingItem.type === 'lvl1' &&
+                                siblingItem.hierarchy.lvl1 ===
+                                  item.hierarchy.lvl1
+                            ) as InternalDocSearchHit | undefined;
+
+                            if (item.type !== 'lvl1' && potentialParent) {
+                              parent = potentialParent;
+                            }
+
                             return {
                               ...item,
-                              __docsearch_parent:
-                                item.type !== 'lvl1' &&
-                                groupedHits.find(
-                                  (siblingItem) =>
-                                    siblingItem.type === 'lvl1' &&
-                                    siblingItem.hierarchy.lvl1 ===
-                                      item.hierarchy.lvl1
-                                ),
+                              __docsearch_parent: parent,
+                              ...insightsParams,
                             };
                           })
                         )
@@ -320,6 +345,9 @@ export function DocSearchModal({
       navigator,
       transformItems,
       disableUserPersonalization,
+      insights,
+      appId,
+      apiKey,
     ]
   );
 

packages/docsearch-react/src/types/DocSearchHit.ts

@@ -78,4 +78,10 @@ export declare type DocSearchHit = {
     };
   };
   _distinctSeqID?: number;
+  __autocomplete_indexName?: string;
+  __autocomplete_queryID?: string;
+  __autocomplete_algoliaCredentials?: {
+    appId: string;
+    apiKey: string;
+  };
 };

packages/website/docs/DocSearch-v3.mdx

@@ -229,6 +229,46 @@ docsearch({
 
 </Tabs>
 
+### Sending events
+
+You can send search events to your DocSearch index by passing in the `insights` parameter when creating your DocSearch instance.
+
+<Tabs
+  groupId="language"
+  defaultValue="js"
+  values={[
+    { label: 'JavaScript', value: 'js', },
+    { label: 'React', value: 'react', }
+  ]
+}>
+<TabItem value="js">
+
+```js
+docsearch({
+  searchParameters: {
+    facetFilters: ['language:en', 'version:1.0.0'],
+  },
+  insights,
+});
+```
+
+</TabItem>
+
+<TabItem value="react">
+
+```jsx
+<DocSearch
+  searchParameters={{
+    facetFilters: ['language:en', 'version:1.0.0'],
+  }}
+  insights
+/>
+```
+
+</TabItem>
+
+</Tabs>
+
 ## Performance optimization
 
 ### Preconnect

yarn.lock

@@ -7,24 +7,32 @@
   resolved "https://registry.yarnpkg.com/@adobe/css-tools/-/css-tools-4.0.1.tgz#b38b444ad3aa5fedbb15f2f746dcd934226a12dd"
   integrity sha512-+u76oB43nOHrF4DDWRLWDCtci7f3QJoEBigemIdIeTi1ODqjx6Tad9NCVnPRwewWlKkVab5PlK8DCtPTyX7S8g==
 
-"@algolia/autocomplete-core@1.8.2":
-  version "1.8.2"
-  resolved "https://registry.yarnpkg.com/@algolia/autocomplete-core/-/autocomplete-core-1.8.2.tgz#8d758c8652742e2761450d2b615a841fca24e10e"
-  integrity sha512-mTeshsyFhAqw/ebqNsQpMtbnjr+qVOSKXArEj4K0d7sqc8It1XD0gkASwecm9mF/jlOQ4Z9RNg1HbdA8JPdRwQ==
+"@algolia/autocomplete-core@1.9.2":
+  version "1.9.2"
+  resolved "https://registry.yarnpkg.com/@algolia/autocomplete-core/-/autocomplete-core-1.9.2.tgz#1c9ffcfac7fc4733fe97356247b25d9d7a83538c"
+  integrity sha512-hkG80c9kx9ClVAEcUJbTd2ziVC713x9Bji9Ty4XJfKXlxlsx3iXsoNhAwfeR4ulzIUg7OE5gez0UU1zVDdG7kg==
   dependencies:
-    "@algolia/autocomplete-shared" "1.8.2"
+    "@algolia/autocomplete-plugin-algolia-insights" "1.9.2"
+    "@algolia/autocomplete-shared" "1.9.2"
 
-"@algolia/autocomplete-preset-algolia@1.8.2":
-  version "1.8.2"
-  resolved "https://registry.yarnpkg.com/@algolia/autocomplete-preset-algolia/-/autocomplete-preset-algolia-1.8.2.tgz#706e87f94c5f198c0e90502b97af09adeeddcc79"
-  integrity sha512-J0oTx4me6ZM9kIKPuL3lyU3aB8DEvpVvR6xWmHVROx5rOYJGQcZsdG4ozxwcOyiiu3qxMkIbzntnV1S1VWD8yA==
+"@algolia/autocomplete-plugin-algolia-insights@1.9.2":
+  version "1.9.2"
+  resolved "https://registry.yarnpkg.com/@algolia/autocomplete-plugin-algolia-insights/-/autocomplete-plugin-algolia-insights-1.9.2.tgz#b4672d5662acc2d0a0547d14dfbdcc70c17625de"
+  integrity sha512-2LVsf4W66hVHQ3Ua/8k15oPlxjELCztbAkQm/hP42Sw+GLkHAdY1vaVRYziaWq64+Oljfg6FKkZHCdgXH+CGIA==
   dependencies:
-    "@algolia/autocomplete-shared" "1.8.2"
+    "@algolia/autocomplete-shared" "1.9.2"
 
-"@algolia/[email protected]":
-  version "1.8.2"
-  resolved "https://registry.yarnpkg.com/@algolia/autocomplete-shared/-/autocomplete-shared-1.8.2.tgz#e6972df5c6935a241f16e4909aa82902338e029d"
-  integrity sha512-b6Z/X4MczChMcfhk6kfRmBzPgjoPzuS9KGR4AFsiLulLNRAAqhP+xZTKtMnZGhLuc61I20d5WqlId02AZvcO6g==
+"@algolia/[email protected]":
+  version "1.9.2"
+  resolved "https://registry.yarnpkg.com/@algolia/autocomplete-preset-algolia/-/autocomplete-preset-algolia-1.9.2.tgz#a31fc9a88800ee7312cd177c738e9e4c0e0f78e8"
+  integrity sha512-pqgIm2GNqtCT59Y1ICctIPrYTi34+wNPiNWEclD/yDzp5uDUUsyGe5XrUjCNyQRTKonAlmYxoaEHOn8FWgmBHA==
+  dependencies:
+    "@algolia/autocomplete-shared" "1.9.2"
+
+"@algolia/[email protected]":
+  version "1.9.2"
+  resolved "https://registry.yarnpkg.com/@algolia/autocomplete-shared/-/autocomplete-shared-1.9.2.tgz#b5b909377439c45774cfb91947ad8e6ebd4652c1"
+  integrity sha512-XxX6YDn+7LG+SmdpXEOnj7fc3TjiVpQ0CbGhjLwrd2tYr6LVY2D4Iiu/iuYJ4shvVDWWnpwArSk0uIWC/8OPUA==
 
 "@algolia/[email protected]":
   version "4.14.1"