Add visitor support

README.md

@@ -129,6 +129,13 @@ function initAnswers() {
     apiKey: '<API_KEY_HERE>',
     // Required, the key used for your Answers experience
     experienceKey: '<EXPERIENCE_KEY_HERE>',
+    // Optional, visitor interacting with the experience, see Visitor Configuration below for details
+    visitor: {
+      // Required, see below
+      id: '<ID_HERE>',
+      // Optional, see below
+      idMethod: '<ID_METHOD_HERE>',
+    },
     // Optional, initialize components here, invoked when the Answers component library is loaded/ready.
     //    If components are not added here, they can also be added when the init promise resolves
     onReady: function() {},
@@ -323,6 +330,21 @@ function (searchParams) => {
 }),
 ```
 
+## Visitor Configuration
+
+Below is a list of configuration attributes related to a visitor, used in the [base configuration](#answersinit-configuration-options) above.
+
+The visitor object ties a user's identity to their searches and actions. The visitor can also be set or changed using the `ANSWERS.setVisitor` function.
+
+```js
+    visitor: {
+      // Required, the ID associated with the user. This will be the yextUserId if Yext Auth is used.
+      id: '123919',
+      // Optional, the method used to generate the visitor ID.
+      idMethod: 'YEXT_USER',
+    },
+```
+
 # Component Usage
 
 The Answers Component Library exposes an easy to use interface for adding and customizing various types of UI components on your page.

THIRD-PARTY-NOTICES

@@ -304,7 +304,7 @@ MIT License
 
 The following NPM package may be included in this product:
 
- - @yext/answers-core@1.3.0
+ - @yext/answers-core@1.3.3-beta.0
 
 This package contains the following license and notice below:
 

package.json

@@ -24,7 +24,7 @@
   ],
   "dependencies": {
     "@mapbox/mapbox-gl-language": "^0.10.1",
-    "@yext/answers-core": "^1.3.0",
+    "@yext/answers-core": "^1.3.3-beta.0",
     "@yext/answers-storage": "^1.1.0",
     "@yext/rtf-converter": "^1.5.0",
     "cross-fetch": "^3.1.4",
@@ -239,4 +239,4 @@
     "./zh-Hant/modern.min": "./dist/zh-Hant-answers-modern.min.js",
     "./zh-Hant/template": "./dist/zh-Hant-answerstemplates.compiled.min.js"
   }
-}
+}

src/answers-search-bar.js

@@ -207,7 +207,11 @@ class AnswersSearchBar {
 
     this._setDefaultInitialSearch(parsedConfig.search);
 
-    this.core.init();
+    if (parsedConfig.visitor) {
+      this.setVisitor(parsedConfig.visitor);
+    } else {
+      this.core.init();
+    }
 
     this._onReady = parsedConfig.onReady || function () {};
 
@@ -450,6 +454,15 @@ class AnswersSearchBar {
         return value;
     }
   }
+
+  setVisitor (visitor) {
+    if (visitor.id) {
+      this._analyticsReporterService?.setVisitor(visitor);
+      this.core.init({ visitor: visitor });
+    } else {
+      console.error(`Invalid visitor. Visitor was not set because "${JSON.stringify(visitor)}" does not have an id.`);
+    }
+  }
 }
 
 /**

src/answers-umd.js

@@ -297,7 +297,11 @@ class Answers {
 
     this._setDefaultInitialSearch(parsedConfig.search);
 
-    this.core.init();
+    if (parsedConfig.visitor) {
+      this.setVisitor(parsedConfig.visitor);
+    } else {
+      this.core.init();
+    }
 
     this._onReady = parsedConfig.onReady || function () {};
 
@@ -693,6 +697,15 @@ class Answers {
         return value;
     }
   }
+
+  setVisitor (visitor) {
+    if (visitor.id) {
+      this._analyticsReporterService?.setVisitor(visitor);
+      this.core.init({ visitor: visitor });
+    } else {
+      console.error(`Invalid visitor. Visitor was not set because "${JSON.stringify(visitor)}" does not have an id.`);
+    }
+  }
 }
 
 /**

src/core/analytics/analyticsreporter.js

@@ -74,6 +74,10 @@ export default class AnalyticsReporter {
     this._globalOptions.queryId = queryId;
   }
 
+  setVisitor (visitor) {
+    this._globalOptions.visitor = visitor;
+  }
+
   /**
    * Opt in or out of analytics click events
    * @param {boolean} analyticsEventsEnabled

src/core/core.js

@@ -127,7 +127,7 @@ export default class Core {
   /**
    * Initializes the {@link Core} by providing it with an instance of the Core library.
    */
-  init () {
+  init (config) {
     const params = {
       apiKey: this._apiKey,
       experienceKey: this._experienceKey,
@@ -136,7 +136,8 @@ export default class Core {
       endpoints: this._getServiceUrls(),
       additionalQueryParams: {
         jsLibVersion: LIB_VERSION
-      }
+      },
+      ...config
     };
 
     this._coreLibrary = provideCore(params);

tests/answers-umd.js

@@ -46,4 +46,43 @@ describe('ANSWERS instance integration testing', () => {
     };
     expect(ANSWERS._analyticsReporterService.report).toHaveBeenCalledWith(expectedEvent, expect.anything());
   });
+
+  it('Visitor is set if passed to ANSWERS.init', async () => {
+    mockWindow(windowSpy, {
+      location: {
+        search: '?query=test'
+      }
+    });
+    await initAnswers(ANSWERS, {
+      visitor: { id: '123' }
+    });
+    expect(ANSWERS._analyticsReporterService.setVisitor).toHaveBeenCalledWith({ id: '123' });
+  });
+
+  it('Visitor is not set if missing id', async () => {
+    const consoleSpy = jest.spyOn(console, 'error');
+    mockWindow(windowSpy, {
+      location: {
+        search: '?query=test'
+      }
+    });
+    await initAnswers(ANSWERS, {
+      visitor: { idMethod: 'test' }
+    });
+    expect(ANSWERS._analyticsReporterService.setVisitor).toHaveBeenCalledTimes(0);
+    expect(consoleSpy).toHaveBeenCalled();
+  });
+
+  it('Visitor can be changed', async () => {
+    mockWindow(windowSpy, {
+      location: {
+        search: '?query=test'
+      }
+    });
+    await initAnswers(ANSWERS, { visitor: { id: '123', idMethod: 'test' } });
+    const initSpy = jest.spyOn(ANSWERS.core, 'init');
+    ANSWERS.setVisitor({ id: '456' });
+    expect(ANSWERS._analyticsReporterService.setVisitor).toHaveBeenLastCalledWith({ id: '456' });
+    expect(initSpy).toHaveBeenCalledWith({ visitor: { id: '456' } });
+  });
 });

tests/core/analytics/analyticsreporter.js

@@ -121,4 +121,15 @@ describe('reporting events', () => {
       expect.anything(),
       expect.objectContaining({ data: expect.not.objectContaining({ queryId: '123' }) }));
   });
+
+  it('Includes visitor when set', () => {
+    analyticsReporter.setVisitor({ id: '123' });
+    const expectedEvent = new AnalyticsEvent('thumbs_up');
+    analyticsReporter.report(expectedEvent);
+
+    expect(mockedBeacon).toBeCalledTimes(1);
+    expect(mockedBeacon).toBeCalledWith(
+      expect.anything(),
+      expect.objectContaining({ data: expect.objectContaining({ visitor: { id: '123' } }) }));
+  });
 });