feat(headless SSR): add NavigatorContext in SSR sample

packages/headless/src/ssr.index.ts

@@ -88,6 +88,7 @@ export type {
   InferBuildResult,
 } from './app/ssr-engine/types/core-engine';
 export type {LoggerOptions} from './app/logger';
+export type {NavigatorContext} from './app/navigatorContextProvider';
 
 export type {LogLevel} from './app/logger';
 

packages/samples/headless-ssr/app-router/src/app/generic/page.tsx

@@ -1,6 +1,11 @@
 import SearchPage from '@/common/components/generic/search-page';
-import {fetchStaticState} from '@/common/lib/generic/engine';
+import {
+  fetchStaticState,
+  setNavigatorContextProvider,
+} from '@/common/lib/generic/engine';
 import {buildSSRSearchParameterSerializer} from '@coveo/headless/ssr';
+import {headers} from 'next/headers';
+import {NextJsAppRouterNavigatorContext} from '../../navigatorContextProvider';
 
 /**
  * This file defines a Search component that uses the Coveo Headless library to manage its state.
@@ -16,12 +21,22 @@ import {buildSSRSearchParameterSerializer} from '@coveo/headless/ssr';
 export default async function Search(url: {
   searchParams: {[key: string]: string | string[] | undefined};
 }) {
+  // Convert URL search parameters into a format that Coveo's search engine can understand.
   const {toSearchParameters} = buildSSRSearchParameterSerializer();
   const searchParameters = toSearchParameters(url.searchParams);
+
+  // Defines hard-coded context values to simulate user-specific information.
   const contextValues = {
     ageGroup: '30-45',
     mainInterest: 'sports',
   };
+
+  // Sets the navigator context provider to use the newly created `navigatorContext` before fetching the app static state
+  const navigatorContext = new NextJsAppRouterNavigatorContext(headers());
+
+  setNavigatorContextProvider(() => navigatorContext);
+
+  // Fetches the static state of the app with initial state (when applicable)
   const staticState = await fetchStaticState({
     controllers: {
       context: {
@@ -34,7 +49,12 @@ export default async function Search(url: {
       },
     },
   });
-  return <SearchPage staticState={staticState}></SearchPage>;
+  return (
+    <SearchPage
+      staticState={staticState}
+      navigatorContext={navigatorContext.marshal}
+    ></SearchPage>
+  );
 }
 
 // A page with search parameters cannot be statically rendered, since its rendered state should look different based on the current search parameters.

packages/samples/headless-ssr/app-router/src/app/react/page.tsx

@@ -3,8 +3,13 @@ import ResultList from '@/common/components/react/result-list';
 import SearchBox from '@/common/components/react/search-box';
 import {SearchPageProvider} from '@/common/components/react/search-page';
 import SearchParameterManager from '@/common/components/react/search-parameter-manager';
-import {fetchStaticState} from '@/common/lib/react/engine';
+import {
+  fetchStaticState,
+  setNavigatorContextProvider,
+} from '@/common/lib/react/engine';
 import {buildSSRSearchParameterSerializer} from '@coveo/headless-react/ssr';
+import {headers} from 'next/headers';
+import {NextJsAppRouterNavigatorContext} from '../../navigatorContextProvider';
 
 /**
  * This file defines a Search component that uses the Coveo Headless library to manage its state.
@@ -21,13 +26,22 @@ import {buildSSRSearchParameterSerializer} from '@coveo/headless-react/ssr';
 export default async function Search(url: {
   searchParams: {[key: string]: string | string[] | undefined};
 }) {
+  // Convert URL search parameters into a format that Coveo's search engine can understand.
   const {toSearchParameters} = buildSSRSearchParameterSerializer();
   const searchParameters = toSearchParameters(url.searchParams);
 
+  // Defines hard-coded context values to simulate user-specific information.
   const contextValues = {
     ageGroup: '30-45',
     mainInterest: 'sports',
   };
+
+  // Sets the navigator context provider to use the newly created `navigatorContext` before fetching the app static state
+  const navigatorContext = new NextJsAppRouterNavigatorContext(headers());
+
+  setNavigatorContextProvider(() => navigatorContext);
+
+  // Fetches the static state of the app with initial state (when applicable)
   const staticState = await fetchStaticState({
     controllers: {
       context: {
@@ -42,7 +56,10 @@ export default async function Search(url: {
   });
 
   return (
-    <SearchPageProvider staticState={staticState}>
+    <SearchPageProvider
+      staticState={staticState}
+      navigatorContext={navigatorContext.marshal}
+    >
       <SearchParameterManager />
       <SearchBox />
       <ResultList />

packages/samples/headless-ssr/app-router/src/middleware.ts

@@ -0,0 +1,43 @@
+/**
+ * Middleware for Next.js applications to handle clientID tracking with Coveo.
+ *
+ * This middleware generates a unique client ID using the `crypto.randomUUID()` method
+ * and injects this ID into both the request and response headers under 'x-coveo-client-id'.
+ * By doing so, it ensures that both server-side and client-side requests can be associated
+ * with the same client ID, facilitating consistent tracking across requests.
+ *
+ * The middleware utilizes Next.js's built-in `NextRequest` and `NextResponse` objects
+ * from 'next/server' to intercept and modify the requests and responses respectively.
+ *
+ * @param {NextRequest} request - The incoming request object provided by Next.js.
+ * @returns {NextResponse} - The modified response object with the 'x-coveo-client-id' header set.
+ */
+import {NextRequest, NextResponse} from 'next/server';
+
+export default function middleware(request: NextRequest) {
+  // Generate the next response object.
+  const response = NextResponse.next();
+
+  // Create a new Headers object based on the incoming request headers.
+  const requestHeaders = new Headers(request.headers);
+
+  // Generate a unique client ID.
+  const uuid = crypto.randomUUID();
+
+  // Assigns the 'x-coveo-client-id' header within the request headers. The specific header name is flexible, provided it remains consistent for client-side retrieval.
+  requestHeaders.set('x-coveo-client-id', uuid);
+
+  // Also set the 'x-coveo-client-id' header in the response headers to ensure
+  // the client ID is consistent across server-side and client-side requests.
+  response.headers.set('x-coveo-client-id', uuid);
+
+  // Storing document location for NavigatorContextProvider
+  response.headers.set('x-href', request.nextUrl.href);
+
+  // Return the modified response.
+  return response;
+}
+
+export const config = {
+  matcher: ['/react', '/generic'],
+};

packages/samples/headless-ssr/app-router/src/navigatorContextProvider.ts

@@ -0,0 +1,39 @@
+import {NavigatorContext} from '@coveo/headless/ssr';
+import type {ReadonlyHeaders} from 'next/dist/server/web/spec-extension/adapters/headers';
+
+/**
+ * Provides navigation context for Coveo within Next.js App Router applications.
+ * This class is essential for returning the client ID, user agent, and referrer information.
+ *
+ * Prior to constructing and hydrating the application's static state, instantiate a navigator context to avoid warnings
+ */
+export class NextJsAppRouterNavigatorContext implements NavigatorContext {
+  constructor(private headers: ReadonlyHeaders) {}
+
+  get referrer() {
+    // The referrer is null on first page load (github.com/vercel/next.js/issues/59301)
+    return this.headers.get('referer') || this.headers.get('referrer'); // Some browsers use 'referer'
+  }
+
+  get userAgent() {
+    return this.headers.get('user-agent');
+  }
+
+  get location() {
+    return this.headers.get('x-href');
+  }
+
+  get clientId() {
+    const clientId = this.headers.get('x-coveo-client-id');
+    return clientId || crypto.randomUUID();
+  }
+
+  get marshal(): NavigatorContext {
+    return {
+      clientId: this.clientId,
+      location: this.location,
+      referrer: this.referrer,
+      userAgent: this.userAgent,
+    };
+  }
+}

packages/samples/headless-ssr/common/components/common/search-engine-config.ts

@@ -14,7 +14,10 @@ import {
 export const config = {
   configuration: {
     ...getSampleSearchEngineConfiguration(),
-    analytics: {enabled: false},
+    analytics: {
+      analyticsMode: 'next',
+      trackingId: 'sports-ui-samples',
+    },
   },
   controllers: {
     context: defineContext(),

packages/samples/headless-ssr/common/components/generic/search-page.tsx

@@ -1,11 +1,13 @@
 'use client';
 
+import {NavigatorContext} from '@coveo/headless/ssr';
 import {useEffect, useState} from 'react';
 import {useSyncSearchParameterManager} from '../../hooks/generic/search-parameter-manager';
 import {
   SearchStaticState,
   SearchHydratedState,
   hydrateStaticState,
+  setNavigatorContextProvider,
 } from '../../lib/generic/engine';
 import {HydrationMetadata} from '../common/hydration-metadata';
 import {Facet} from './facet';
@@ -14,13 +16,18 @@ import {SearchBox} from './search-box';
 
 export default function SearchPage({
   staticState,
+  navigatorContext,
 }: {
   staticState: SearchStaticState;
+  navigatorContext: NavigatorContext;
 }) {
   const [hydratedState, setHydratedState] = useState<
     SearchHydratedState | undefined
   >(undefined);
 
+  // Setting the navigator context provider also in client-side before hydrating the application
+  setNavigatorContextProvider(() => navigatorContext);
+
   useEffect(() => {
     const {searchParameterManager, context} = staticState.controllers;
     hydrateStaticState({

packages/samples/headless-ssr/common/components/react/search-page.tsx

@@ -1,27 +1,34 @@
 'use client';
 
+import {NavigatorContext} from '@coveo/headless/ssr';
 import {useEffect, useState, PropsWithChildren} from 'react';
 import {
   SearchStaticState,
   SearchHydratedState,
   hydrateStaticState,
   HydratedStateProvider,
   StaticStateProvider,
+  setNavigatorContextProvider,
 } from '../../lib/react/engine';
 import {HydrationMetadata} from '../common/hydration-metadata';
 
 interface SearchPageProviderProps {
   staticState: SearchStaticState;
+  navigatorContext: NavigatorContext;
 }
 
 export function SearchPageProvider({
   staticState,
+  navigatorContext,
   children,
 }: PropsWithChildren<SearchPageProviderProps>) {
   const [hydratedState, setHydratedState] = useState<
     SearchHydratedState | undefined
   >(undefined);
 
+  // Setting the navigator context provider also in client-side before hydrating the application
+  setNavigatorContextProvider(() => navigatorContext);
+
   useEffect(() => {
     const {searchParameterManager, context} = staticState.controllers;
     hydrateStaticState({

packages/samples/headless-ssr/common/lib/generic/engine.ts

@@ -10,4 +10,8 @@ const engineDefinition = defineSearchEngine(config);
 export type SearchStaticState = InferStaticState<typeof engineDefinition>;
 export type SearchHydratedState = InferHydratedState<typeof engineDefinition>;
 
-export const {fetchStaticState, hydrateStaticState} = engineDefinition;
+export const {
+  fetchStaticState,
+  hydrateStaticState,
+  setNavigatorContextProvider,
+} = engineDefinition;

packages/samples/headless-ssr/common/lib/react/engine.ts

@@ -12,6 +12,7 @@ export const {
   hydrateStaticState,
   StaticStateProvider,
   HydratedStateProvider,
+  setNavigatorContextProvider,
 } = engineDefinition;
 
 export const {

packages/samples/headless-ssr/pages-router/src/middleware.ts

@@ -0,0 +1,43 @@
+/**
+ * Middleware for Next.js applications to handle clientID tracking with Coveo.
+ *
+ * This middleware generates a unique client ID using the `crypto.randomUUID()` method
+ * and injects this ID into both the request and response headers under 'x-coveo-client-id'.
+ * By doing so, it ensures that both server-side and client-side requests can be associated
+ * with the same client ID, facilitating consistent tracking across requests.
+ *
+ * The middleware utilizes Next.js's built-in `NextRequest` and `NextResponse` objects
+ * from 'next/server' to intercept and modify the requests and responses respectively.
+ *
+ * @param {NextRequest} request - The incoming request object provided by Next.js.
+ * @returns {NextResponse} - The modified response object with the 'x-coveo-client-id' header set.
+ */
+import {NextRequest, NextResponse} from 'next/server';
+
+export default function middleware(request: NextRequest) {
+  // Generate the next response object.
+  const response = NextResponse.next();
+
+  // Create a new Headers object based on the incoming request headers.
+  const requestHeaders = new Headers(request.headers);
+
+  // Generate a unique client ID.
+  const uuid = crypto.randomUUID();
+
+  // Assigns the 'x-coveo-client-id' header within the request headers. The specific header name is flexible, provided it remains consistent for client-side retrieval.
+  requestHeaders.set('x-coveo-client-id', uuid);
+
+  // Also set the 'x-coveo-client-id' header in the response headers to ensure
+  // the client ID is consistent across server-side and client-side requests.
+  response.headers.set('x-coveo-client-id', uuid);
+
+  // Storing document location for NavigatorContextProvider
+  response.headers.set('x-href', request.nextUrl.href);
+
+  // Return the modified response.
+  return response;
+}
+
+export const config = {
+  matcher: ['/react', '/generic'],
+};

packages/samples/headless-ssr/pages-router/src/navigatorContextProvider.ts

@@ -0,0 +1,52 @@
+import {NavigatorContext} from '@coveo/headless/ssr';
+import {IncomingHttpHeaders} from 'node:http';
+
+/**
+ * Provides navigation context for Coveo within Next.js  Pages Router applications.
+ * This class is essential for returning the client ID, user agent, and referrer information.
+ *
+ * Prior to constructing and hydrating the application's static state, instantiate a navigator context to avoid warnings
+ */
+export class NextJsPagesRouterNavigatorContext implements NavigatorContext {
+  constructor(private headers: IncomingHttpHeaders) {}
+
+  get referrer() {
+    const referrerHeader = this.headers['referer'] ?? this.headers['referrer']; // Some browsers use 'referer'
+    const referrer = Array.isArray(referrerHeader)
+      ? referrerHeader[0]
+      : referrerHeader;
+    return referrer ?? null;
+  }
+
+  get userAgent() {
+    const userAgentHeader = this.headers['user-agent'];
+    return Array.isArray(userAgentHeader)
+      ? userAgentHeader[0]
+      : userAgentHeader;
+  }
+
+  get location() {
+    const locationHeader = this.headers['x-href'];
+    const location = Array.isArray(locationHeader)
+      ? locationHeader[0]
+      : locationHeader;
+    return location ?? null;
+  }
+
+  get clientId() {
+    const clientIdHeader = this.headers['x-coveo-client-id'];
+    const clientId = Array.isArray(clientIdHeader)
+      ? clientIdHeader[0]
+      : clientIdHeader;
+    return clientId || crypto.randomUUID();
+  }
+
+  get marshal(): NavigatorContext {
+    return {
+      clientId: this.clientId,
+      location: this.location,
+      referrer: this.referrer,
+      userAgent: this.userAgent,
+    };
+  }
+}