Merge main (v2.1.0) into develop (#634)

github-actions[bot] · Fondryext · web-flow · commit f2a522003e77 · 2026-02-18T14:33:29.000-05:00
* feat: allow users to turn analytics on and off (v2.1.0) (#632) * feat: allow users to turn analytics on and off (v2.1.0) This PR adds a new property to the SearchAnalyticsConfig, which can be used to start with analytics enabled or disabled by default. Three new methods are added to the analytics object- two to turn analytics on/off, and one to get the current enabled status. J=WAT-5404 TEST=auto, manual Ran test site locally with debugging and buttons to turn analytics on and off, saw expected behavior. * Update various names to be in-line with pages code * Automated update to repo's documentation from github action * Add enableYextAnalytics function to window * drop unneeded parens --------- Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com> * release: v2.1.0 --------- Co-authored-by: Fondryext <160865254+Fondryext@users.noreply.github.com> Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Jacob Fondriest <jfondriest@yext.com>
diff --git a/docs/search-ui-react.searchanalyticsconfig.md b/docs/search-ui-react.searchanalyticsconfig.md
@@ -91,6 +91,25 @@ Environment
 _(Optional)_ The Yext environment to send requests to. Defaults to 'PRODUCTION'.
 
 
+</td></tr>
+<tr><td>
+
+[requireOptIn?](./search-ui-react.searchanalyticsconfig.requireoptin.md)
+
+
+</td><td>
+
+
+</td><td>
+
+boolean
+
+
+</td><td>
+
+_(Optional)_ Whether a user must consent to analytics tracking before events are fired. Defaults to false.
+
+
 </td></tr>
 <tr><td>
 
diff --git a/docs/search-ui-react.searchanalyticsconfig.requireoptin.md b/docs/search-ui-react.searchanalyticsconfig.requireoptin.md
@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/search-ui-react](./search-ui-react.md) &gt; [SearchAnalyticsConfig](./search-ui-react.searchanalyticsconfig.md) &gt; [requireOptIn](./search-ui-react.searchanalyticsconfig.requireoptin.md)
+
+## SearchAnalyticsConfig.requireOptIn property
+
+Whether a user must consent to analytics tracking before events are fired. Defaults to false.
+
+**Signature:**
+
+```typescript
+requireOptIn?: boolean;
+```
diff --git a/docs/search-ui-react.searchanalyticseventservice.isyextanalyticsenabled.md b/docs/search-ui-react.searchanalyticseventservice.isyextanalyticsenabled.md
@@ -0,0 +1,17 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/search-ui-react](./search-ui-react.md) &gt; [SearchAnalyticsEventService](./search-ui-react.searchanalyticseventservice.md) &gt; [isYextAnalyticsEnabled](./search-ui-react.searchanalyticseventservice.isyextanalyticsenabled.md)
+
+## SearchAnalyticsEventService.isYextAnalyticsEnabled() method
+
+Returns whether analytics reporting is currently enabled
+
+**Signature:**
+
+```typescript
+isYextAnalyticsEnabled(): boolean;
+```
+**Returns:**
+
+boolean
+
diff --git a/docs/search-ui-react.searchanalyticseventservice.md b/docs/search-ui-react.searchanalyticseventservice.md
@@ -27,6 +27,39 @@ Description
 </th></tr></thead>
 <tbody><tr><td>
 
+[isYextAnalyticsEnabled()](./search-ui-react.searchanalyticseventservice.isyextanalyticsenabled.md)
+
+
+</td><td>
+
+Returns whether analytics reporting is currently enabled
+
+
+</td></tr>
+<tr><td>
+
+[optIn()](./search-ui-react.searchanalyticseventservice.optin.md)
+
+
+</td><td>
+
+Enables analytics reporting
+
+
+</td></tr>
+<tr><td>
+
+[optOut()](./search-ui-react.searchanalyticseventservice.optout.md)
+
+
+</td><td>
+
+Disables analytics reporting
+
+
+</td></tr>
+<tr><td>
+
 [report(payload)](./search-ui-react.searchanalyticseventservice.report.md)
 
 
diff --git a/docs/search-ui-react.searchanalyticseventservice.optin.md b/docs/search-ui-react.searchanalyticseventservice.optin.md
@@ -0,0 +1,17 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/search-ui-react](./search-ui-react.md) &gt; [SearchAnalyticsEventService](./search-ui-react.searchanalyticseventservice.md) &gt; [optIn](./search-ui-react.searchanalyticseventservice.optin.md)
+
+## SearchAnalyticsEventService.optIn() method
+
+Enables analytics reporting
+
+**Signature:**
+
+```typescript
+optIn(): void;
+```
+**Returns:**
+
+void
+
diff --git a/docs/search-ui-react.searchanalyticseventservice.optout.md b/docs/search-ui-react.searchanalyticseventservice.optout.md
@@ -0,0 +1,17 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/search-ui-react](./search-ui-react.md) &gt; [SearchAnalyticsEventService](./search-ui-react.searchanalyticseventservice.md) &gt; [optOut](./search-ui-react.searchanalyticseventservice.optout.md)
+
+## SearchAnalyticsEventService.optOut() method
+
+Disables analytics reporting
+
+**Signature:**
+
+```typescript
+optOut(): void;
+```
+**Returns:**
+
+void
+
diff --git a/etc/search-ui-react.api.md b/etc/search-ui-react.api.md
@@ -689,11 +689,15 @@ export interface SearchAnalyticsConfig {
     apiKey: string;
     cloudRegion?: CloudRegion;
     environment?: Environment;
+    requireOptIn?: boolean;
     sessionTrackingEnabled?: boolean;
 }
 
 // @public
 export interface SearchAnalyticsEventService {
+    isYextAnalyticsEnabled(): boolean;
+    optIn(): void;
+    optOut(): void;
     // Warning: (ae-forgotten-export) The symbol "SearchEventPayload" needs to be exported by the entry point index.d.ts
     report(payload: SearchEventPayload): Promise<string>;
 }
@@ -1039,7 +1043,7 @@ export interface VisualAutocompleteConfig {
 
 // Warnings were encountered during analysis:
 //
-// dist/index.d.ts:1741:5 - (ae-forgotten-export) The symbol "translations" needs to be exported by the entry point index.d.ts
+// dist/index.d.ts:1749:5 - (ae-forgotten-export) The symbol "translations" needs to be exported by the entry point index.d.ts
 
 // (No @packageDocumentation comment for this package)
 
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@yext/search-ui-react",
-  "version": "2.0.5",
+  "version": "2.1.0",
   "description": "A library of React Components for powering Yext Search integrations",
   "author": "watson@yext.com",
   "license": "BSD-3-Clause",
diff --git a/src/components/AnalyticsProvider.tsx b/src/components/AnalyticsProvider.tsx
@@ -1,7 +1,8 @@
-import React, { PropsWithChildren } from 'react';
+import React, { PropsWithChildren, useEffect, useRef } from 'react';
 import { AnalyticsContext } from '../hooks/useAnalytics';
 import { CloudRegion, Environment } from '@yext/search-core';
 import { SearchAnalyticsEventServiceImpl } from '../models/SearchAnalyticsEventServiceImpl';
+import { SearchAnalyticsEventService } from '../models';
 
 /**
  * A higher-order component which provides analytics for its children.
@@ -13,11 +14,28 @@ import { SearchAnalyticsEventServiceImpl } from '../models/SearchAnalyticsEventS
  */
 export function AnalyticsProvider(props: PropsWithChildren<SearchAnalyticsConfig>): React.JSX.Element {
   const { children, ...searchAnalyticsConfig } = props;
-  const analyticsReporter =
-      new SearchAnalyticsEventServiceImpl(searchAnalyticsConfig);
+
+  const analyticsRef = useRef<SearchAnalyticsEventService | null>(null);
+
+  if (analyticsRef.current === null) {
+    analyticsRef.current = new SearchAnalyticsEventServiceImpl(searchAnalyticsConfig);
+  }
+
+  const analytics = analyticsRef.current;
+
+  // Adds enableYextAnalytics to the window. Typically used during consent banner implementation.
+  useEffect(() => {
+    (window as any).enableYextAnalytics = () => {
+      analytics.optIn();
+    };
+
+    return () => {
+      delete (window as any).enableYextAnalytics;
+    };
+  }, [analytics]);
 
   return (
-    <AnalyticsContext.Provider value={ analyticsReporter }>
+    <AnalyticsContext.Provider value={ analytics }>
       {children}
     </AnalyticsContext.Provider>
   );
@@ -36,5 +54,7 @@ export interface SearchAnalyticsConfig {
   /** The region to send requests to. Defaults to 'US'. */
   cloudRegion?: CloudRegion,
   /** Whether to enable session tracking for analytics events. */
-  sessionTrackingEnabled?: boolean
+  sessionTrackingEnabled?: boolean,
+  /** Whether a user must consent to analytics tracking before events are fired. Defaults to false. */
+  requireOptIn?: boolean
 }
diff --git a/src/models/SearchAnalyticsEventService.ts b/src/models/SearchAnalyticsEventService.ts
@@ -11,5 +11,11 @@ export interface SearchAnalyticsEventService {
      *
      * @param payload - desired values to be applied
      */
-  report(payload: SearchEventPayload): Promise<string>
+  report(payload: SearchEventPayload): Promise<string>,
+  /** Enables analytics reporting */
+  optIn(): void,
+  /** Disables analytics reporting */
+  optOut(): void,
+  /** Returns whether analytics reporting is currently enabled */
+  isYextAnalyticsEnabled(): boolean
 }
diff --git a/src/models/SearchAnalyticsEventServiceImpl.ts b/src/models/SearchAnalyticsEventServiceImpl.ts
@@ -7,6 +7,7 @@ import { SearchAnalyticsEventService } from './SearchAnalyticsEventService';
 /** An implementation of {@link SearchAnalyticsEventService} which makes calls to the Analytics Events API */
 export class SearchAnalyticsEventServiceImpl implements SearchAnalyticsEventService {
   private internalService: AnalyticsEventService;
+  private analyticsEnabled: boolean;
   /**
    * @param searchAnalyticsConfig - configuration for analytics reporting.
    */
@@ -21,9 +22,26 @@ export class SearchAnalyticsEventServiceImpl implements SearchAnalyticsEventServ
       sessionTrackingEnabled: searchAnalyticsConfig.sessionTrackingEnabled
     };
     this.internalService = analytics(analyticsConfig);
+    // if requireOptIn is undefined or set to false, analytics are enabled
+    this.analyticsEnabled = !searchAnalyticsConfig.requireOptIn;
+  }
+
+  public optIn(): void {
+    this.analyticsEnabled = true;
+  }
+
+  public optOut(): void {
+    this.analyticsEnabled = false;
+  }
+
+  public isYextAnalyticsEnabled(): boolean {
+    return this.analyticsEnabled;
   }
 
   public async report(payload: SearchEventPayload): Promise<string> {
+    if (!this.analyticsEnabled) {
+      return Promise.resolve('');
+    }
     const eventPayload: EventPayload = {
       action: payload.action,
       destinationUrl: payload.destinationUrl,
diff --git a/test-site/package-lock.json b/test-site/package-lock.json
diff --git a/test-site/src/config.ts b/test-site/src/config.ts
@@ -1,5 +1,4 @@
 import { CloudRegion, CloudChoice, Environment } from '@yext/search-headless-react';
-import {AnalyticsConfig} from "@yext/analytics";
 import {SearchAnalyticsConfig} from "../../src";
 
 export const config = {
@@ -17,4 +16,5 @@ export const analyticsConfig: SearchAnalyticsConfig = {
   apiKey: process.env.REACT_APP_EVENTS_API_KEY || 'REPLACE_ME',
   environment: Environment.PROD,
   cloudRegion: CloudRegion.US,
+  requireOptIn: false,
 };
diff --git a/tests/components/SearchBar.test.tsx b/tests/components/SearchBar.test.tsx
@@ -6,14 +6,11 @@ import {
   State, SearchTypeEnum
 } from '@yext/search-headless-react';
 import { render, RenderResult, screen } from '@testing-library/react';
-import { SearchBar, onSearchFunc } from '../../src/components/SearchBar';
-import { VerticalLink } from '../../src/models/verticalLink';
-import { SearchI18nextProvider } from '../../src/components/SearchI18nextProvider';
+import { SearchBar, onSearchFunc, VerticalLink, SearchI18nextProvider, SearchAnalyticsEventService } from '../../src';
 import userEvent from '@testing-library/user-event';
 import { generateMockedHeadless } from '../__fixtures__/search-headless';
 import { RecursivePartial } from '../__utils__/mocks';
 import * as Analytics from '../../src/hooks/useAnalytics';
-import { AnalyticsEventService } from '@yext/analytics';
 import React from 'react';
 
 const mockedState: Partial<State> = {
@@ -560,7 +557,7 @@ describe('SearchBar', () => {
 
     beforeEach(() => {
       jest.spyOn(Analytics, 'useAnalytics')
-        .mockImplementation(() => ({ report: mockedReport }) as unknown as AnalyticsEventService);
+        .mockImplementation(() => ({ report: mockedReport }) as unknown as SearchAnalyticsEventService);
     });
 
     it('reports AUTO_COMPLETE_SELECTION feedback', async () => {

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@yext/search-ui-react",`
`3`		`- "version": "2.0.5",`
	`3`	`+ "version": "2.1.0",`
`4`	`4`	`"description": "A library of React Components for powering Yext Search integrations",`
`5`	`5`	`"author": "watson@yext.com",`
`6`	`6`	`"license": "BSD-3-Clause",`