feat: Add queryID & postion as a preperation for Recommend Analytics [RECO-2391]

examples/demo/package.json

@@ -21,7 +21,7 @@
     "react": "17.0.2",
     "react-dom": "17.0.2",
     "react-router-dom": "^6.17.0",
-    "search-insights": "2.4.0"
+    "search-insights": "2.17.3"
   },
   "devDependencies": {
     "@babel/core": "7.21.4",

examples/demo/src/components/ComparisonChartItem/index.tsx

@@ -2,7 +2,6 @@ import React from 'react';
 import './style.css';
 import { InsightsClient } from 'search-insights';
 
-import { indexName } from '../../config';
 import { ProductHit, ProductReviews } from '../../types';
 import { ButtonComponent } from '../common';
 
@@ -56,10 +55,12 @@ export const ComparisonChartItem: React.FC<ChartItemProps<ProductHit>> = ({
             event.preventDefault();
 
             onSelect(item);
-            insights('clickedObjectIDs', {
+            insights('clickedObjectIDsAfterSearch', {
               objectIDs: [item.objectID],
               eventName: 'Product Clicked',
-              index: indexName,
+              index: item.__indexName,
+              positions: [item.__position],
+              queryID: item.__queryID,
             });
           }}
         >
@@ -78,7 +79,7 @@ export const ComparisonChartItem: React.FC<ChartItemProps<ProductHit>> = ({
                 insights('convertedObjectIDsAfterSearch', {
                   eventName: 'Product Added To Cart',
                   objectIDs: [item.objectID],
-                  index: indexName,
+                  index: item.__indexName,
                   queryID: item.__queryID,
                 });
               }}

examples/demo/src/components/Facet/index.tsx

@@ -1,29 +1,21 @@
 import { TrendingFacetHit } from '@algolia/recommend';
 import React from 'react';
-import { InsightsClient } from 'search-insights';
 
 import './style.css';
 
 type FacetProps = {
   hit: TrendingFacetHit;
   indexName: string;
-  insights: InsightsClient;
   onSelect(hit: TrendingFacetHit): void;
 };
 
-export function Facet({ hit, onSelect, indexName, insights }: FacetProps) {
+export function Facet({ hit, onSelect }: FacetProps) {
   return (
     <div
       className="Hit"
       onClick={(event) => {
         event.preventDefault();
-
         onSelect(hit);
-        insights('clickedFilters', {
-          index: indexName,
-          eventName: 'Facet Clicked',
-          filters: [`${hit.facetName}:${hit.facetValue}`],
-        });
       }}
     >
       <div className="Facet-Content">

examples/demo/src/components/Hit/index.tsx

@@ -1,7 +1,6 @@
 import React from 'react';
 import { InsightsClient } from 'search-insights';
 
-import { indexName } from '../../config';
 import { ProductHit } from '../../types';
 import './style.css';
 import { ButtonComponent } from '../common';
@@ -21,10 +20,12 @@ export function Hit({ hit, onSelect, insights }: HitProps) {
         event.preventDefault();
 
         onSelect(hit);
-        insights('clickedObjectIDs', {
+        insights('clickedObjectIDsAfterSearch', {
           objectIDs: [hit.objectID],
           eventName: 'Product Clicked',
-          index: indexName,
+          index: hit.__indexName,
+          positions: [hit.__position],
+          queryID: hit.__queryID,
         });
       }}
     >
@@ -45,7 +46,7 @@ export function Hit({ hit, onSelect, insights }: HitProps) {
             insights('convertedObjectIDsAfterSearch', {
               eventName: 'Product Added To Cart',
               objectIDs: [hit.objectID],
-              index: indexName,
+              index: hit.__indexName,
               queryID: hit.__queryID,
             });
           }}

examples/demo/src/routes/HomePage.tsx

@@ -28,7 +28,6 @@ export const HomePage: React.FC = () => {
         itemComponent={({ item }) => (
           <Facet
             hit={item}
-            insights={insights}
             onSelect={(facetHits) => {
               const isSameValue =
                 selectedFacetValue &&
@@ -70,13 +69,17 @@ export const HomePage: React.FC = () => {
             selectedFacetValue ? `in ${selectedFacetValue.facetValue}` : ''
           }`,
         }}
+        queryParameters={{
+          clickAnalytics: true,
+        }}
       />
       <RecommendedForYou<ProductHit>
         recommendClient={recommendClient}
         indexName={indexName}
         maxRecommendations={15}
         queryParameters={{
           userToken: 'likes-gender-men',
+          clickAnalytics: true,
         }}
         itemComponent={({ item }) => (
           <Hit

examples/demo/src/types/ProductHit.ts

@@ -28,7 +28,7 @@ export type ProductReviews = {
 };
 
 type WithInsights<THit> = THit & {
-  __position: string;
+  __position: number;
   __indexName: string;
   __queryID: string;
 };

examples/js-demo/RelatedItem.tsx

@@ -12,10 +12,12 @@ export function RelatedItem({ item, insights, onSelect }: RelatedItemProps) {
       onClick={(event) => {
         event.preventDefault();
         onSelect(item);
-        insights('clickedObjectIDs', {
+        insights('clickedObjectIDsAfterSearch', {
           objectIDs: [item.objectID],
           eventName: 'Product Clicked',
           index: item.__indexName,
+          positions: [item.__position],
+          queryID: item.__queryID,
         });
       }}
     >

examples/js-demo/package.json

@@ -21,7 +21,7 @@
     "@babel/runtime": "7.21.0",
     "algoliasearch": "4.17.0",
     "preact": "10.13.2",
-    "search-insights": "2.4.0"
+    "search-insights": "2.17.3"
   },
   "devDependencies": {
     "@babel/core": "7.21.4",

examples/js-demo/types/ProductHit.ts

@@ -29,7 +29,7 @@ export type ProductRecord = {
 };
 
 type WithInsights<THit> = THit & {
-  __position: string;
+  __position: number;
   __indexName: string;
   __queryID: string;
 };

packages/recommend-core/src/getBatchRecommendations.ts

@@ -7,6 +7,8 @@ import {
 
 import { TrendingFacetHit, ProductRecord } from './types';
 import { mapByScoreToRecommendations, mapToRecommendations } from './utils';
+import { addAbsolutePosition } from './utils/addAbsolutePosition';
+import { addIndexName } from './utils/addIndexName';
 import { version } from './version';
 
 export type BatchKeyPair = {
@@ -55,9 +57,11 @@ export async function getBatchRecommendations<TObject>({
     const { model } = JSON.parse(keyPair.key);
 
     allChunks += keyPair.value;
-    const { maxRecommendations, transformItems = (x) => x } = queries[
-      prevChunks
-    ];
+    const {
+      indexName,
+      maxRecommendations,
+      transformItems = (x) => x,
+    } = queries[prevChunks];
     const splitResult = response?.results?.slice(prevChunks, allChunks);
     prevChunks += keyPair.value;
 
@@ -71,13 +75,18 @@ export async function getBatchRecommendations<TObject>({
       recommendations = mapByScoreToRecommendations<ProductRecord<TObject>>({
         maxRecommendations,
         hits: splitResult.map((res) => res.hits).flat(),
+        indexName,
+        queryID: splitResult.at(0)?.queryID,
       });
     } else {
       recommendations = mapToRecommendations<ProductRecord<TObject>>({
         maxRecommendations,
         hits: splitResult.map((res) => res.hits),
         nrOfObjs: keyPair.value,
-      });
+        queryIDs: splitResult.map((res) => res.queryID),
+      })
+        .map((hit) => addIndexName(hit, indexName))
+        .map((hit, idx) => addAbsolutePosition(hit, idx));
     }
     recommendations = transformItems(recommendations);
     results[keyPair.key] = { recommendations, trendingFacets };

packages/recommend-core/src/getFrequentlyBoughtTogether.ts

@@ -3,6 +3,8 @@ import { FrequentlyBoughtTogetherQuery } from '@algolia/recommend';
 import { RecommendationsProps } from './getRecommendations';
 import { ProductRecord } from './types';
 import { mapToRecommendations } from './utils';
+import { addAbsolutePosition } from './utils/addAbsolutePosition';
+import { addIndexName } from './utils/addIndexName';
 import { version } from './version';
 
 export type GetFrequentlyBoughtTogetherProps<
@@ -40,7 +42,13 @@ export function getFrequentlyBoughtTogether<TObject>({
         maxRecommendations,
         hits: response.results.map((result) => result.hits),
         nrOfObjs: objectIDs.length,
+        queryIDs: response.results.map((res) => res.queryID),
       })
     )
+    .then((hits) =>
+      hits
+        .map((hit) => addIndexName(hit, indexName))
+        .map((hit, idx) => addAbsolutePosition(hit, idx))
+    )
     .then((hits) => ({ recommendations: transformItems(hits) }));
 }

packages/recommend-core/src/getLookingSimilar.ts

@@ -3,6 +3,8 @@ import { LookingSimilarQuery } from '@algolia/recommend';
 import { RecommendationsProps } from './getRecommendations';
 import { ProductRecord } from './types';
 import { mapToRecommendations } from './utils';
+import { addAbsolutePosition } from './utils/addAbsolutePosition';
+import { addIndexName } from './utils/addIndexName';
 import { version } from './version';
 
 export type GetLookingSimilarProps<TObject> = RecommendationsProps<TObject> &
@@ -40,7 +42,13 @@ export function getLookingSimilar<TObject>({
         maxRecommendations,
         hits: response.results.map((result) => result.hits),
         nrOfObjs: objectIDs.length,
+        queryIDs: response.results.map((res) => res.queryID),
       })
     )
+    .then((hits) =>
+      hits
+        .map((hit) => addIndexName(hit, indexName))
+        .map((hit, idx) => addAbsolutePosition(hit, idx))
+    )
     .then((hits) => ({ recommendations: transformItems(hits) }));
 }

packages/recommend-core/src/getRecommendations.ts

@@ -2,6 +2,8 @@ import type { RecommendClient, RecommendationsQuery } from '@algolia/recommend';
 
 import { ProductRecord, RecordWithObjectID } from './types';
 import { mapToRecommendations } from './utils';
+import { addAbsolutePosition } from './utils/addAbsolutePosition';
+import { addIndexName } from './utils/addIndexName';
 import { version } from './version';
 
 export type RecommendationsProps<TObject> = {
@@ -66,7 +68,13 @@ export function getRecommendations<TObject>({
         maxRecommendations,
         hits: response.results.map((result) => result.hits),
         nrOfObjs: objectIDs.length,
+        queryIDs: response.results.map((res) => res.queryID),
       })
     )
+    .then((hits) =>
+      hits
+        .map((hit) => addIndexName(hit, indexName))
+        .map((hit, idx) => addAbsolutePosition(hit, idx))
+    )
     .then((hits) => ({ recommendations: transformItems(hits) }));
 }

packages/recommend-core/src/getRecommendedForYou.ts

@@ -1,6 +1,9 @@
 import { Hit } from '@algolia/client-search';
 import { RecommendClient, RecommendedForYouParams } from '@algolia/recommend';
 
+import { addAbsolutePosition } from './utils/addAbsolutePosition';
+import { addIndexName } from './utils/addIndexName';
+import { addQueryID } from './utils/addQueryID';
 import { version } from './version';
 
 export type GetRecommendedForYouProps<TObject> = {
@@ -36,9 +39,16 @@ export function getRecommendedForYou<TObject>({
 
   return recommendClient
     .getRecommendedForYou<TObject>(queries)
-    .then((hits) => ({
+    .then((response) => ({
       recommendations: transformItems(
-        hits.results.map((result) => result.hits).flat()
+        response.results
+          .map((result) =>
+            result.hits
+              .map((hit) => addIndexName(hit, indexName))
+              .map((hit) => addQueryID(hit, result.queryID))
+          )
+          .flat()
+          .map((hit, idx) => addAbsolutePosition(hit, idx))
       ),
     }));
 }

packages/recommend-core/src/getRelatedProducts.ts

@@ -3,6 +3,8 @@ import { RelatedProductsQuery } from '@algolia/recommend';
 import { RecommendationsProps } from './getRecommendations';
 import { ProductRecord } from './types';
 import { mapToRecommendations } from './utils';
+import { addAbsolutePosition } from './utils/addAbsolutePosition';
+import { addIndexName } from './utils/addIndexName';
 import { version } from './version';
 
 export type GetRelatedProductsProps<TObject> = RecommendationsProps<TObject> &
@@ -39,8 +41,14 @@ export function getRelatedProducts<TObject>({
       mapToRecommendations<ProductRecord<TObject>>({
         maxRecommendations,
         hits: response.results.map((result) => result.hits),
+        queryIDs: response.results.map((result) => result.queryID),
         nrOfObjs: objectIDs.length,
       })
     )
+    .then((hits) =>
+      hits
+        .map((hit) => addIndexName(hit, indexName))
+        .map((hit, idx) => addAbsolutePosition(hit, idx))
+    )
     .then((hits) => ({ recommendations: transformItems(hits) }));
 }

packages/recommend-core/src/getTrendingFacets.ts

@@ -46,6 +46,7 @@ export function getTrendingFacets({
       mapByScoreToRecommendations<TrendingFacetHit>({
         maxRecommendations,
         hits: response.results.map((result) => result.hits).flat(),
+        indexName,
       })
     )
     .then((hits) => ({ recommendations: transformItems(hits) }));

packages/recommend-core/src/getTrendingItems.ts

@@ -64,6 +64,8 @@ export function getTrendingItems<TObject>({
           'objectID',
           response.results.map((result) => result.hits).flat()
         ),
+        indexName,
+        queryID: response.results?.at(0)?.queryID,
       })
     )
     .then((hits) => ({ recommendations: transformItems(hits) }));

packages/recommend-core/src/types/ProductRecord.ts

@@ -1,4 +1,7 @@
 export type ProductRecord<TObject> = TObject & {
   objectID: string;
   _score?: number;
+  __queryID?: string;
+  __position?: number;
+  __indexName?: string;
 };

packages/recommend-core/src/types/RecordWithObjectID.ts

@@ -1,3 +1,6 @@
 export type RecordWithObjectID<TObject = {}> = TObject & {
   objectID: string;
+  __queryID?: string;
+  __position?: number;
+  __indexName?: string;
 };

packages/recommend-core/src/utils/addAbsolutePosition.ts

@@ -0,0 +1,6 @@
+export function addAbsolutePosition<THit>(hit: THit, index: number): THit {
+  return {
+    ...hit,
+    __position: index + 1,
+  };
+}

packages/recommend-core/src/utils/addIndexName.ts

@@ -0,0 +1,6 @@
+export function addIndexName<THit>(hit: THit, indexName: string): THit {
+  return {
+    ...hit,
+    __indexName: indexName,
+  };
+}

packages/recommend-core/src/utils/addQueryID.ts

@@ -0,0 +1,10 @@
+export function addQueryID<THit>(hit: THit, queryID?: string): THit {
+  if (!queryID) {
+    return hit;
+  }
+
+  return {
+    ...hit,
+    __queryID: queryID,
+  };
+}