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 visitor ID. 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.

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,16 @@ class AnswersSearchBar {
         return value;
     }
   }
+
+  setVisitor (visitor) {
+    if (visitor.id) {
+      this._analyticsReporterService?.setVisitor(visitor);
+      this.core.storage.set(StorageKeys.VISITOR, visitor);
+      this.core.init();
+    } else {
+      console.error(`Invalid visitor. Visitor was not set because "${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,16 @@ class Answers {
         return value;
     }
   }
+
+  setVisitor (visitor) {
+    if (visitor.id) {
+      this._analyticsReporterService?.setVisitor(visitor);
+      this.core.storage.set(StorageKeys.VISITOR, visitor);
+      this.core.init();
+    } else {
+      console.error(`Invalid visitor. Visitor was not set because "${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

@@ -133,6 +133,7 @@ export default class Core {
       experienceKey: this._experienceKey,
       locale: this._locale,
       experienceVersion: this._experienceVersion,
+      visitor: this.storage.get(StorageKeys.VISITOR),
       endpoints: this._getServiceUrls(),
       additionalQueryParams: {
         jsLibVersion: LIB_VERSION

src/core/storage/storagekeys.js

@@ -41,6 +41,7 @@ const StorageKeys = {
   QUERY_TRIGGER: 'queryTrigger',
   FACETS_LOADED: 'facets-loaded',
   QUERY_SOURCE: 'query-source',
-  HISTORY_POP_STATE: 'history-pop-state'
+  HISTORY_POP_STATE: 'history-pop-state',
+  VISITOR: 'visitor'
 };
 export default StorageKeys;

tests/answers-umd.js

@@ -1,6 +1,7 @@
 import ANSWERS from '../src/answers-umd';
 import mockWindow from './setup/mockwindow';
 import initAnswers from './setup/initanswers';
+import StorageKeys from '../src/core/storage/storagekeys';
 
 jest.mock('../src/core/analytics/analyticsreporter');
 
@@ -46,4 +47,42 @@ 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' });
+    expect(ANSWERS.core.storage.get(StorageKeys.VISITOR)).toEqual({ id: '123' });
+  });
+
+  it('Visitor is not set if missing id', async () => {
+    mockWindow(windowSpy, {
+      location: {
+        search: '?query=test'
+      }
+    });
+    await initAnswers(ANSWERS, {
+      visitor: { idMethod: 'test' }
+    });
+    expect(ANSWERS._analyticsReporterService.setVisitor).toHaveBeenCalledTimes(0);
+    expect(ANSWERS.core.storage.get(StorageKeys.VISITOR)).toBeUndefined();
+  });
+
+  it('Visitor can be changed', async () => {
+    mockWindow(windowSpy, {
+      location: {
+        search: '?query=test'
+      }
+    });
+    await initAnswers(ANSWERS, { visitor: { id: '123', idMethod: 'test' } });
+    ANSWERS.setVisitor({ id: '456' });
+    expect(ANSWERS._analyticsReporterService.setVisitor).toHaveBeenLastCalledWith({ id: '456' });
+    expect(ANSWERS.core.storage.get(StorageKeys.VISITOR)).toEqual({ 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' } }) }));
+  });
 });