Adds support for Analytics for Yext Pages

Also updates the main AnalyticsConfig, AnalyticsReporter, etc. to be aliases for SearchAnayticsConfig, SearchAnalytics Reporter, etc. in order to differentiate between the Pages & Search focused parts of the library. Additionally, introduces console debugging support enabled when the `debug` option is set. T=unit & manual Unit tests added for the new PagesAnalyticsReporter. Manually testing done by updating the test-site to add the new provider, fire a page view, and add a button to test click events. Co-authored-by: Ben McGinnis <bmcginnis@yext.com> Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>
yext · Jul 28, 2022 · 90e1daa · 90e1daa
1 parent 3d23f4a
commit 90e1daa
Show file tree

Hide file tree

Showing 143 changed files with 1,982 additions and 368 deletions.
diff --git a/README.md b/README.md
@@ -28,29 +28,31 @@ First, install the library via [npm](https://www.npmjs.com/get-npm):
 npm install @yext/analytics
 ```
 
-Next, import and initialize the library in your application.
+Next, import and initialize the library in your application.  Yext currently has different analytics reporting features 
+between Search and Pages and so they have slightly different interfaces for working with them.  There is also a combined
+interface that you can use when you are building a Search experience entirely on Pages (e.g. a Locator or a Help Site).
 
-The experienceKey will come from your Answers experience on yext.com. You can signup for a free trial at [https://www.yext.com/free-trial/](https://www.yext.com/free-trial/).
+### Search Analytics
 
 ```ts
-import { provideAnalytics } from '@yext/analytics';
+import { provideSearchAnalytics } from '@yext/analytics'; // can also be imported as provideAnalytics
 
-const analytics = provideAnalytics({
+const searchAnalytics = provideSearchAnalytics({
   experienceKey: '<your experience key>',
   experienceVersion: 'PRODUCTION',
-  businessId: 123456,
+  businessId: 123456, // this comes from the url of your Yext account
 });
 ```
 
 To use the library with Node, use the following import instead:
 ```ts
-const { provideAnalytics } = require('@yext/analytics');
+const { provideSearchAnalytics } = require('@yext/analytics');
 ``` 
 
-Now that the analytics reporter is initialized, let's fire off an event:
+Now that the search analytics reporter is initialized, let's fire off an event:
 
 ```ts
-analytics.report({
+searchAnalytics.report({
   type: 'CTA_CLICK',
   entityId: '1',
   verticalKey: 'people',
@@ -59,15 +61,54 @@ analytics.report({
 });
 ```
 
-### Analytics Event Types
-When specifying the analytics type, either the [AnalyticsEventType](./docs/analytics.analyticseventtype.md) enum
+#### Search Analytics Event Types
+When specifying the analytics type, either the [SearchAnalyticsEventType](./docs/analytics.searchanalyticseventtype.md) enum
 or its corresponding string can be specified. For example, you can specify the 'CTA_CLICK' event with either 'CTA_CLICK' or
 with `AnalyticsEventType.CtaClick`. Once the event type is specified, TypeScript is able to enforce the required and
 optional properties for that event type.
 
+### Pages Analytics
+
+```ts
+import { providePagesAnalytics } from '@yext/analytics';
+
+const pagesAnalytics = providePagesAnalytics({
+  debug: false, // enables console debugging logs if set to true
+  pageType: {
+    pageSetId: 'My  Page Set', // the name of the feature in your features.json or the name of your template file
+    id: 90210, // the uid of the entity your page represents
+    name: 'static',
+  },
+  pagesReferrer: 'https://www.google.com', // e.g. document.referrer
+  path: '/foo/bar', // e.g. window.location.pathname
+  businessId: 12345, // this comes from the url of your Yext account
+  production: false, // set to true if you are in the production environment
+  siteId: 654321, // the id of your site, you can find this in the url of your deploy page
+});
+```
+
+Now that the pages analytics reporter is initialized, we can fire a pageview:
+```ts
+pagesAnalytics.pageView();
+```
+
+If a user clicks on a CTA, we can track a CTA Click Event
+
+```ts
+import { CtaClick } from '@yext/analytics';
+
+pagesAnalytics.track(CtaClick);
+```
+
+We can also fire an event on any other type of user interaction and give it a custom name:
+```ts
+pagesAnalytics.track({eventType: 'C_MY_CUSTOM_EVENT'});
+```
+
+
 And that's it! See **[our documentation](./docs/analytics.md)** for a full list of analytics events.
 
-### Module support
+## Module support
 - The ESM (ES6) build will be used automatically by module bundlers that support it (e.g. Webpack). It can be specified directly by importing `@yext/analytics/lib/esm`
 - The CommonJS build will be used automatically by Node, but it can be specified directly by importing `@yext/analytics/lib/commonjs`
 

diff --git a/docs/analytics.accordiontoggleevent.md b/docs/analytics.accordiontoggleevent.md
@@ -19,6 +19,6 @@ export interface AccordionToggleEvent
 |  [entityId](./analytics.accordiontoggleevent.entityid.md) | string | The entity ID for the entity. |
 |  [queryId](./analytics.accordiontoggleevent.queryid.md) | string | The ID of the most recent query. |
 |  [searcher?](./analytics.accordiontoggleevent.searcher.md) | [Searcher](./analytics.searcher.md) | <i>(Optional)</i> Whether it was on universal or vertical search. |
-|  [type](./analytics.accordiontoggleevent.type.md) | [EnumOrString](./analytics.enumorstring.md)<!-- -->&lt;[AnalyticsEventType.RowExpand](./analytics.analyticseventtype.md) \| [AnalyticsEventType.RowCollapse](./analytics.analyticseventtype.md)<!-- -->&gt; | An enum member or its string value which denotes the event type. |
+|  [type](./analytics.accordiontoggleevent.type.md) | [EnumOrString](./analytics.enumorstring.md)<!-- -->&lt;[SearchAnalyticsEventType.RowExpand](./analytics.searchanalyticseventtype.md) \| [SearchAnalyticsEventType.RowCollapse](./analytics.searchanalyticseventtype.md)<!-- -->&gt; | An enum member or its string value which denotes the event type. |
 |  [verticalKey](./analytics.accordiontoggleevent.verticalkey.md) | string | The vertical key for the vertical on which the event was fired. Or, if it is a universal search, the vertical key for the section in the universal results. |
 
diff --git a/docs/analytics.accordiontoggleevent.type.md b/docs/analytics.accordiontoggleevent.type.md
@@ -9,5 +9,5 @@ An enum member or its string value which denotes the event type.
 <b>Signature:</b>
 
 ```typescript
-type: EnumOrString<AnalyticsEventType.RowExpand | AnalyticsEventType.RowCollapse>;
+type: EnumOrString<SearchAnalyticsEventType.RowExpand | SearchAnalyticsEventType.RowCollapse>;
 ```
diff --git a/docs/analytics.alltabnavigationevent.md b/docs/analytics.alltabnavigationevent.md
@@ -17,5 +17,5 @@ export interface AllTabNavigationEvent
 |  Property | Type | Description |
 |  --- | --- | --- |
 |  [queryId?](./analytics.alltabnavigationevent.queryid.md) | string | <i>(Optional)</i> The ID of the most recent query. |
-|  [type](./analytics.alltabnavigationevent.type.md) | [EnumOrString](./analytics.enumorstring.md)<!-- -->&lt;[AnalyticsEventType.AllTabNavigation](./analytics.analyticseventtype.md)<!-- -->&gt; | An enum member or its string value which denotes the event type. |
+|  [type](./analytics.alltabnavigationevent.type.md) | [EnumOrString](./analytics.enumorstring.md)<!-- -->&lt;[SearchAnalyticsEventType.AllTabNavigation](./analytics.searchanalyticseventtype.md)<!-- -->&gt; | An enum member or its string value which denotes the event type. |
 
diff --git a/docs/analytics.alltabnavigationevent.type.md b/docs/analytics.alltabnavigationevent.type.md
@@ -9,5 +9,5 @@ An enum member or its string value which denotes the event type.
 <b>Signature:</b>
 
 ```typescript
-type: EnumOrString<AnalyticsEventType.AllTabNavigation>;
+type: EnumOrString<SearchAnalyticsEventType.AllTabNavigation>;
 ```
diff --git a/docs/analytics.analyticsconfig.businessid.md b/docs/analytics.analyticsconfig.businessid.md
diff --git a/docs/analytics.analyticsconfig.md b/docs/analytics.analyticsconfig.md
diff --git a/docs/analytics.analyticsservice.md b/docs/analytics.analyticsservice.md
diff --git a/docs/analytics.autocompleteevent.md b/docs/analytics.autocompleteevent.md
@@ -18,5 +18,5 @@ export interface AutocompleteEvent
 |  --- | --- | --- |
 |  [queryId?](./analytics.autocompleteevent.queryid.md) | string | <i>(Optional)</i> The ID of the most recent query. |
 |  [suggestedSearchText](./analytics.autocompleteevent.suggestedsearchtext.md) | string | Selected search text from an autocomplete suggestion. |
-|  [type](./analytics.autocompleteevent.type.md) | [EnumOrString](./analytics.enumorstring.md)<!-- -->&lt;[AnalyticsEventType.AutocompleteSelection](./analytics.analyticseventtype.md)<!-- -->&gt; | An enum member or its string value which denotes the event type. |
+|  [type](./analytics.autocompleteevent.type.md) | [EnumOrString](./analytics.enumorstring.md)<!-- -->&lt;[SearchAnalyticsEventType.AutocompleteSelection](./analytics.searchanalyticseventtype.md)<!-- -->&gt; | An enum member or its string value which denotes the event type. |
 
diff --git a/docs/analytics.autocompleteevent.type.md b/docs/analytics.autocompleteevent.type.md
@@ -9,5 +9,5 @@ An enum member or its string value which denotes the event type.
 <b>Signature:</b>
 
 ```typescript
-type: EnumOrString<AnalyticsEventType.AutocompleteSelection>;
+type: EnumOrString<SearchAnalyticsEventType.AutocompleteSelection>;
 ```
diff --git a/docs/analytics.baseanalyticsconfig.businessid.md b/docs/analytics.baseanalyticsconfig.businessid.md
@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/analytics](./analytics.md) &gt; [BaseAnalyticsConfig](./analytics.baseanalyticsconfig.md) &gt; [businessId](./analytics.baseanalyticsconfig.businessid.md)
+
+## BaseAnalyticsConfig.businessId property
+
+Your Yext Account ID Can be easily found from the url of your homepage of your Yext account e.g. https://www.yext.com/s/\[businessId\]/home
+
+<b>Signature:</b>
+
+```typescript
+businessId: number;
+```
diff --git a/docs/analytics.baseanalyticsconfig.debug.md b/docs/analytics.baseanalyticsconfig.debug.md
@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/analytics](./analytics.md) &gt; [BaseAnalyticsConfig](./analytics.baseanalyticsconfig.md) &gt; [debug](./analytics.baseanalyticsconfig.debug.md)
+
+## BaseAnalyticsConfig.debug property
+
+Turn on analytics event logging in the console
+
+<b>Signature:</b>
+
+```typescript
+debug?: boolean;
+```
diff --git a/docs/analytics.baseanalyticsconfig.md b/docs/analytics.baseanalyticsconfig.md
@@ -0,0 +1,22 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/analytics](./analytics.md) &gt; [BaseAnalyticsConfig](./analytics.baseanalyticsconfig.md)
+
+## BaseAnalyticsConfig interface
+
+Base analytics configuration
+
+<b>Signature:</b>
+
+```typescript
+export interface BaseAnalyticsConfig 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [businessId](./analytics.baseanalyticsconfig.businessid.md) | number | Your Yext Account ID Can be easily found from the url of your homepage of your Yext account e.g. https://www.yext.com/s/\[businessId\]/home |
+|  [debug?](./analytics.baseanalyticsconfig.debug.md) | boolean | <i>(Optional)</i> Turn on analytics event logging in the console |
+|  [visitor?](./analytics.baseanalyticsconfig.visitor.md) | [Visitor](./analytics.visitor.md) | <i>(Optional)</i> Information used to associate analytics with a particular user. |
+
diff --git a/docs/analytics.analyticsconfig.visitor.md → .../analytics.baseanalyticsconfig.visitor.md b/docs/analytics.analyticsconfig.visitor.md → .../analytics.baseanalyticsconfig.visitor.md
@@ -1,8 +1,8 @@
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
-[Home](./index.md) &gt; [@yext/analytics](./analytics.md) &gt; [AnalyticsConfig](./analytics.analyticsconfig.md) &gt; [visitor](./analytics.analyticsconfig.visitor.md)
+[Home](./index.md) &gt; [@yext/analytics](./analytics.md) &gt; [BaseAnalyticsConfig](./analytics.baseanalyticsconfig.md) &gt; [visitor](./analytics.baseanalyticsconfig.visitor.md)
 
-## AnalyticsConfig.visitor property
+## BaseAnalyticsConfig.visitor property
 
 Information used to associate analytics with a particular user.
 

diff --git a/docs/analytics.ctaclick.md b/docs/analytics.ctaclick.md
@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/analytics](./analytics.md) &gt; [CtaClick](./analytics.ctaclick.md)
+
+## CtaClick variable
+
+A Pages CTA Event
+
+<b>Signature:</b>
+
+```typescript
+CtaClick: PagesAnalyticsEvent
+```
diff --git a/docs/analytics.ctaevent.md b/docs/analytics.ctaevent.md
@@ -22,7 +22,7 @@ export interface CtaEvent
 |  [fieldName?](./analytics.ctaevent.fieldname.md) | string | <i>(Optional)</i> The name of the Rich Text field used. |
 |  [queryId](./analytics.ctaevent.queryid.md) | string | The ID of the most recent query. |
 |  [searcher](./analytics.ctaevent.searcher.md) | [Searcher](./analytics.searcher.md) | Whether it was on universal or vertical search. |
-|  [type](./analytics.ctaevent.type.md) | [EnumOrString](./analytics.enumorstring.md)<!-- -->&lt;[AnalyticsEventType.CtaClick](./analytics.analyticseventtype.md) \| [AnalyticsEventType.TitleClick](./analytics.analyticseventtype.md) \| [AnalyticsEventType.TapToCall](./analytics.analyticseventtype.md) \| [AnalyticsEventType.OrderNow](./analytics.analyticseventtype.md) \| [AnalyticsEventType.AddToCart](./analytics.analyticseventtype.md) \| [AnalyticsEventType.ApplyNow](./analytics.analyticseventtype.md) \| [AnalyticsEventType.DrivingDirections](./analytics.analyticseventtype.md) \| [AnalyticsEventType.ViewWebsite](./analytics.analyticseventtype.md) \| [AnalyticsEventType.Email](./analytics.analyticseventtype.md) \| [AnalyticsEventType.BookAppointment](./analytics.analyticseventtype.md) \| [AnalyticsEventType.Rsvp](./analytics.analyticseventtype.md)<!-- -->&gt; | An enum member or its string value which denotes the event type. |
+|  [type](./analytics.ctaevent.type.md) | [EnumOrString](./analytics.enumorstring.md)<!-- -->&lt;[SearchAnalyticsEventType.CtaClick](./analytics.searchanalyticseventtype.md) \| [SearchAnalyticsEventType.TitleClick](./analytics.searchanalyticseventtype.md) \| [SearchAnalyticsEventType.TapToCall](./analytics.searchanalyticseventtype.md) \| [SearchAnalyticsEventType.OrderNow](./analytics.searchanalyticseventtype.md) \| [SearchAnalyticsEventType.AddToCart](./analytics.searchanalyticseventtype.md) \| [SearchAnalyticsEventType.ApplyNow](./analytics.searchanalyticseventtype.md) \| [SearchAnalyticsEventType.DrivingDirections](./analytics.searchanalyticseventtype.md) \| [SearchAnalyticsEventType.ViewWebsite](./analytics.searchanalyticseventtype.md) \| [SearchAnalyticsEventType.Email](./analytics.searchanalyticseventtype.md) \| [SearchAnalyticsEventType.BookAppointment](./analytics.searchanalyticseventtype.md) \| [SearchAnalyticsEventType.Rsvp](./analytics.searchanalyticseventtype.md)<!-- -->&gt; | An enum member or its string value which denotes the event type. |
 |  [url?](./analytics.ctaevent.url.md) | string | <i>(Optional)</i> The url of the event target. |
 |  [verticalKey](./analytics.ctaevent.verticalkey.md) | string | The vertical key for the vertical on which the event was fired. Or, if it is a universal search, the vertical key for the section in the universal results. |
 
diff --git a/docs/analytics.ctaevent.type.md b/docs/analytics.ctaevent.type.md
@@ -9,5 +9,5 @@ An enum member or its string value which denotes the event type.
 <b>Signature:</b>
 
 ```typescript
-type: EnumOrString<AnalyticsEventType.CtaClick | AnalyticsEventType.TitleClick | AnalyticsEventType.TapToCall | AnalyticsEventType.OrderNow | AnalyticsEventType.AddToCart | AnalyticsEventType.ApplyNow | AnalyticsEventType.DrivingDirections | AnalyticsEventType.ViewWebsite | AnalyticsEventType.Email | AnalyticsEventType.BookAppointment | AnalyticsEventType.Rsvp>;
+type: EnumOrString<SearchAnalyticsEventType.CtaClick | SearchAnalyticsEventType.TitleClick | SearchAnalyticsEventType.TapToCall | SearchAnalyticsEventType.OrderNow | SearchAnalyticsEventType.AddToCart | SearchAnalyticsEventType.ApplyNow | SearchAnalyticsEventType.DrivingDirections | SearchAnalyticsEventType.ViewWebsite | SearchAnalyticsEventType.Email | SearchAnalyticsEventType.BookAppointment | SearchAnalyticsEventType.Rsvp>;
 ```
diff --git a/docs/analytics.defaultpageseventnames.md b/docs/analytics.defaultpageseventnames.md
@@ -0,0 +1,24 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/analytics](./analytics.md) &gt; [DefaultPagesEventNames](./analytics.defaultpageseventnames.md)
+
+## DefaultPagesEventNames enum
+
+Default pages analytics event types.
+
+<b>Signature:</b>
+
+```typescript
+export declare enum DefaultPagesEventNames 
+```
+
+## Enumeration Members
+
+|  Member | Value | Description |
+|  --- | --- | --- |
+|  CTA | <code>&quot;CTA_CLICK&quot;</code> |  |
+|  DrivingDirection | <code>&quot;DRIVING_DIRECTIONS&quot;</code> |  |
+|  PageView | <code>&quot;PAGE_VIEW&quot;</code> |  |
+|  PhoneCall | <code>&quot;CALL&quot;</code> |  |
+|  Website | <code>&quot;WEBSITE&quot;</code> |  |
+
diff --git a/docs/analytics.directorypage.directoryid.md b/docs/analytics.directorypage.directoryid.md
@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/analytics](./analytics.md) &gt; [DirectoryPage](./analytics.directorypage.md) &gt; [directoryId](./analytics.directorypage.directoryid.md)
+
+## DirectoryPage.directoryId property
+
+The name of the directory page feature, may be from the 'name' property of your feature in features.json or the name of your page template file if you are using yext/pages to implement your page.
+
+<b>Signature:</b>
+
+```typescript
+directoryId: string;
+```
diff --git a/docs/analytics.directorypage.id.md b/docs/analytics.directorypage.id.md
@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/analytics](./analytics.md) &gt; [DirectoryPage](./analytics.directorypage.md) &gt; [id](./analytics.directorypage.id.md)
+
+## DirectoryPage.id property
+
+Yext Internal ID of Entities to Track. May come from meta.id or the uid parameter of a stream document
+
+<b>Signature:</b>
+
+```typescript
+id: number;
+```
diff --git a/docs/analytics.directorypage.md b/docs/analytics.directorypage.md
@@ -0,0 +1,23 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/analytics](./analytics.md) &gt; [DirectoryPage](./analytics.directorypage.md)
+
+## DirectoryPage interface
+
+Represents the analytics parameters required to track events on a directory page
+
+<b>Signature:</b>
+
+```typescript
+export interface DirectoryPage extends PageType 
+```
+<b>Extends:</b> [PageType](./analytics.pagetype.md)
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [directoryId](./analytics.directorypage.directoryid.md) | string | The name of the directory page feature, may be from the 'name' property of your feature in features.json or the name of your page template file if you are using yext/pages to implement your page. |
+|  [id](./analytics.directorypage.id.md) | number | Yext Internal ID of Entities to Track. May come from meta.id or the uid parameter of a stream document |
+|  [name](./analytics.directorypage.name.md) | 'directory' | The string name of the page type |
+
diff --git a/docs/analytics.directorypage.name.md b/docs/analytics.directorypage.name.md
@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/analytics](./analytics.md) &gt; [DirectoryPage](./analytics.directorypage.md) &gt; [name](./analytics.directorypage.name.md)
+
+## DirectoryPage.name property
+
+The string name of the page type
+
+<b>Signature:</b>
+
+```typescript
+readonly name: 'directory';
+```