ksearch: upgrade to Events API #508

Fondryext · 2025-04-07T16:55:37Z

This PR upgrades our analytics calls to the next major version, also called the Events API. As part of this work, analytics calls have changed shape, and some deprecated properties have been dropped.
J=WAT-4651
TEST=auto,manual

Updated auto tests. Ran test site locally and saw events all the way to snowflake.

This PR upgrades our analytics calls to the next major version, also called the Events API. As part of this work, analytics calls have changed shape, and some deprecated properties have been dropped. J=WAT-4651 TEST=auto,manual Updated auto tests. Ran test site locally and saw events all the way to snowflake.

…y notices check

github-actions · 2025-04-07T16:59:14Z

Current unit coverage is 91.4992993928071%
Current visual coverage is 77.20391807658059%
Current combined coverage is 92.01680672268908%

Fondryext · 2025-04-07T16:59:31Z

src/components/AnalyticsProvider.tsx

@@ -1,5 +1,5 @@
 import React, { PropsWithChildren } from 'react';
-import { provideAnalytics, AnalyticsConfig } from '@yext/analytics';


This AnalyticsConfig has changed shape in the new analytics, the old one was actually very search specific and had properties like experienceKey - the new one is very high level and only requires an auth type and an auth key. I think because of this alone this is breaking.

Yeh I think this makes sense to me.

Fondryext · 2025-04-07T17:00:52Z

src/hooks/useCardAnalytics.ts

-      queryId,
-      verticalKey: verticalKey || '',
-      url,
-      fieldName,


we drop 'searcher' and 'fieldName'

Fondryext · 2025-04-07T17:01:18Z

src/hooks/usePaginationAnalytics.ts

-      verticalKey: verticalKey,
-      newPage,
-      currentPage,
-      totalPageCount


We drop all three of these page-related values.

Hm so we're just no longer sending that data with the event after this change? Or is that information picked up elsewhere?

If this was never actually being used, then that's fine. Otherwise I'd want to keep sending (and recording) that information. Just wanted to double check.

Fondryext · 2025-04-07T17:01:33Z

src/hooks/usePaginationAnalytics.ts

-  currentPage: number,
-  totalPageCount: number
-) => void {
+export function usePaginationAnalytics(): () => void {


This function changes signature

Fondryext · 2025-04-07T17:02:16Z

src/hooks/useSearchBarAnalytics.ts

-    analytics?.report({
-      type: 'AUTO_COMPLETE_SELECTION',
-      ...(queryId && { queryId }),
-      suggestedSearchText


We drop suggestedSearchText

That's interesting, seems like it'd be a pretty relevant piece of data for this

How do you mean? Interesting that analytics dropped it from their new system, or that I followed it?

Interesting that analytics dropped it. We should ofc follow whatever their system supports / expects

coveralls · 2025-04-07T20:14:50Z

coverage: 86.688% (-0.5%) from 87.142%
when pulling 6ae8d8e on dev/events-api
into 055c51d on main.

k-gerner · 2025-04-10T16:18:23Z

src/components/sections/SectionHeader.tsx

@@ -90,10 +93,19 @@ export function SectionHeader(props: SectionHeaderProps): JSX.Element {
      console.error('Unable to report a vertical view all event. Missing field: queryId.');
      return;
    }
+    if (!experienceKey) {


Do we need a check for locale or searchId? Or are those automatically set

locale can be unset in the event payload so passing it possible undefined is ok. For searchId we could also add error handling if the searchId is not present.

Hm as I think about it, our analytics are all based off query id now right? Probably not necessary to require the search id if we don't see that changing

Actually trying to send an analytics event without search id crashes out, as I recall. My understanding was that the events are based on the first search id of a query, which is the same as the query id.

Got it, so it seems necessary, but also that it should be automatically set elsewhere correct? Therefore not requiring any extra check here?

I agree a check would be nice, and I will add it. Could you elaborate the second comment? What should be set, the searchId? Isn't that pulled from the meta state? I'm not sure we have any guarantees about that.

Sorry maybe I was misunderstanding your prior comment. The way I read it was that the search id was being set as the query id by default somewhere up the chain in the SDK somewhere. Feel free to disregard. I agree adding a check is good then

Hm, locale really isn't required? I agree about adding a check for the search id if it's required.

src/hooks/useCardAnalytics.ts

k-gerner · 2025-04-10T16:27:46Z

src/hooks/useSearchBarAnalytics.ts

-    analytics?.report({
-      type: 'AUTO_COMPLETE_SELECTION',
-      ...(queryId && { queryId }),
-      suggestedSearchText


That's interesting, seems like it'd be a pretty relevant piece of data for this

src/hooks/useSearchBarAnalytics.ts

k-gerner · 2025-04-14T17:06:38Z

package.json

@@ -1,6 +1,6 @@
 {
  "name": "@yext/search-ui-react",
-  "version": "1.8.2",
+  "version": "1.8.3",


My debounce change is 1.8.3 so this will have to change - I assume to 2.0.0 since this has breaking changes

Yes, this change is a draft.

k-gerner · 2025-04-14T17:08:29Z

src/components/sections/SectionHeader.tsx

@@ -90,10 +93,19 @@ export function SectionHeader(props: SectionHeaderProps): JSX.Element {
      console.error('Unable to report a vertical view all event. Missing field: queryId.');
      return;
    }
+    if (!experienceKey) {


Got it, so it seems necessary, but also that it should be automatically set elsewhere correct? Therefore not requiring any extra check here?

Fondryext · 2025-06-24T13:44:40Z

src/hooks/useAnalytics.ts


 /**
 * Returns a service that can be used to report analytics events.
 *
 * @public
 */
-export function useAnalytics(): AnalyticsService | null {
+export function useAnalytics(): AnalyticsEventService | null {


So if we want to hide all analytics stuff, we'd need to make our own service implementation, which has the report() method which calls the analytics report() behind the scenes. This would involve making our own event payload interface, perhaps with fewer properties than the analytics one, and maybe with no search object, instead having all properties on the top level

I think this would be a good idea given that we want to abstract away the analytics code like you said

…y notices check

analytics import

Fondryext · 2025-07-03T16:59:07Z

src/models/SearchEventPayload.ts

+    searchTerm?: string;
+}
+
+//todo - how many of these do we want to delete?


I want to prune these down - open to what we use as our canonical list.

Is there a reason we want to prune these down? At the very least, I imagine we want things like map pin, auto complete selection, the paginates, chat impression, search clear, etc.

So as we discussed, let's pare this down based on user event types and then consider any remaining enum types more individually. If it's clearly search related or has been used before, include it. If it's clearly for another product, exclude it, etc. Use your discretion, but feel free to loop in Baigel / others if you want a 2nd opinion while I'm out.

vijay267 · 2025-08-21T17:51:19Z

docs/search-ui-react.cardctaeventtype.md

@@ -9,5 +9,9 @@ Analytics event types for cta click, title click, and citation click.
 **Signature:**

 ```typescript
+<<<<<<< HEAD


Don't we need to resolve this?

vijay267 · 2025-08-21T18:54:37Z

etc/search-ui-react.api.md

@@ -130,7 +130,7 @@ export type CardAnalyticsType = CardCtaEventType | FeedbackType;
 export type CardComponent<T = DefaultRawDataType> = (props: CardProps<T>) => JSX.Element;

 // @public
-export type CardCtaEventType = 'CTA_CLICK' | 'TITLE_CLICK' | 'CITATION_CLICK' | 'DRIVING_DIRECTIONS' | 'VIEW_WEBSITE' | 'TAP_TO_CALL';
+export type CardCtaEventType = 'CTA_CLICK' | 'TITLE' | 'CITATION_CLICK' | 'DRIVING_DIRECTIONS' | 'WEBSITE' | 'TAP_TO_CALL';


Any reason this changed?

We decided to change these back so that future folks won't need to update their code from "TITLE_CLICK" to "title", etc. We'd just map our enum to the analytics one internally.

vijay267 · 2025-08-21T19:46:13Z

etc/search-ui-react.api.md

@@ -939,8 +947,10 @@ export interface UnknownFieldTypeDisplayProps {
 // @public
 export function updateLocationIfNeeded(searchActions: SearchActions, intents: SearchIntent[], geolocationOptions?: PositionOptions): Promise<void>;

+// Warning: (ae-forgotten-export) The symbol "SearchAnalyticsEventService" needs to be exported by the entry point index.d.ts


What is this warning about? Do we need to actually export the service like it suggests?

src/components/SearchBar.tsx

vijay267 · 2025-08-21T20:17:00Z

src/hooks/useCardAnalytics.ts

+      action: feedbackType,
+      entity: entityId,
+      locale,
+        searchId,


Hm is the different indenting between this line and the line before intentional

vijay267 · 2025-08-21T20:18:16Z

src/hooks/usePaginationAnalytics.ts

-      verticalKey: verticalKey,
-      newPage,
-      currentPage,
-      totalPageCount


Hm so we're just no longer sending that data with the event after this change? Or is that information picked up elsewhere?

vijay267 · 2025-08-21T20:20:52Z

src/models/SearchEventPayload.ts

+    searchTerm?: string;
+}
+
+//todo - how many of these do we want to delete?


Is there a reason we want to prune these down? At the very least, I imagine we want things like map pin, auto complete selection, the paginates, chat impression, search clear, etc.

vijay267

Generally looks good! Had some comments about specific details, but I like the wrapper, and overall the changes make sense.

vijay267 · 2025-08-21T20:32:44Z

src/hooks/usePaginationAnalytics.ts

-      verticalKey: verticalKey,
-      newPage,
-      currentPage,
-      totalPageCount


If this was never actually being used, then that's fine. Otherwise I'd want to keep sending (and recording) that information. Just wanted to double check.

vijay267 · 2025-08-21T20:35:27Z

etc/search-ui-react.api.md

@@ -130,7 +130,7 @@ export type CardAnalyticsType = CardCtaEventType | FeedbackType;
 export type CardComponent<T = DefaultRawDataType> = (props: CardProps<T>) => JSX.Element;

 // @public
-export type CardCtaEventType = 'CTA_CLICK' | 'TITLE_CLICK' | 'CITATION_CLICK' | 'DRIVING_DIRECTIONS' | 'VIEW_WEBSITE' | 'TAP_TO_CALL';
+export type CardCtaEventType = 'CTA_CLICK' | 'TITLE' | 'CITATION_CLICK' | 'DRIVING_DIRECTIONS' | 'WEBSITE' | 'TAP_TO_CALL';


We decided to change these back so that future folks won't need to update their code from "TITLE_CLICK" to "title", etc. We'd just map our enum to the analytics one internally.

vijay267 · 2025-08-21T20:38:57Z

src/models/SearchEventPayload.ts

+    searchTerm?: string;
+}
+
+//todo - how many of these do we want to delete?


So as we discussed, let's pare this down based on user event types and then consider any remaining enum types more individually. If it's clearly search related or has been used before, include it. If it's clearly for another product, exclude it, etc. Use your discretion, but feel free to loop in Baigel / others if you want a 2nd opinion while I'm out.

Fondryext and others added 2 commits April 7, 2025 12:53

Automated update to THIRD-PARTY-NOTICES from github action's 3rd part…

08ef2ae

…y notices check

Fondryext commented Apr 7, 2025

View reviewed changes

k-gerner reviewed Apr 10, 2025

View reviewed changes

Fondryext added 2 commits April 10, 2025 14:22

Cleanup, renamings, and fixing error messages

92cd4b0

fix tests

6ae8d8e

k-gerner reviewed Apr 14, 2025

View reviewed changes

Update checking, add wrapper

11c2671

Fondryext commented Jun 24, 2025

View reviewed changes

Fondryext marked this pull request as ready for review June 24, 2025 13:45

Fondryext requested a review from a team as a code owner June 24, 2025 13:45

Fondryext and others added 4 commits June 24, 2025 09:53

Merge branch 'main' into dev/events-api

bccd7d0

Automated update to THIRD-PARTY-NOTICES from github action's 3rd part…

3c5a6e2

…y notices check

Fix at least some tests

a535595

Add more wraparound services and values, to fully hide the

89b34f0

analytics import

Fondryext commented Jul 3, 2025

View reviewed changes

vijay267 reviewed Aug 21, 2025

View reviewed changes

		@@ -1,5 +1,5 @@
		import React, { PropsWithChildren } from 'react';
		import { provideAnalytics, AnalyticsConfig } from '@yext/analytics';

ksearch: upgrade to Events API #508

Are you sure you want to change the base?

ksearch: upgrade to Events API #508

Uh oh!

Conversation

Fondryext commented Apr 7, 2025

Uh oh!

github-actions bot commented Apr 7, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Fondryext Apr 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

coveralls commented Apr 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Fondryext Apr 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Fondryext Apr 10, 2025 •

edited

Loading

coveralls commented Apr 7, 2025 •

edited

Loading

Fondryext Apr 14, 2025 •

edited

Loading